Jump to Content

API Response

All Centiwise API responses are returned as JSON with an HTTP status of 200, regardless of whether the transaction succeeded or failed. Always inspect the status field in the response body — do not rely on the HTTP status code alone.

Response Fields

Field	Type	Description
`status`	String	Transaction outcome: `success`, `error`, or `processing`
`orderid`	String	Centiwise's internal order identifier
`client_orderid`	String	Your original order reference, echoed back
`amount`	Integer	Confirmed transaction amount
`currency`	String	ISO 4217 currency code

Status Values

Status	Meaning	Action
`success`	Transaction completed successfully	Update your system, fulfil the order
`error`	Transaction failed	Check `error_code` and `error_message`; do not fulfil
`processing`	Transaction is pending	Wait for the webhook callback to deliver the final status

Success Response

{
  "status":         "success",
  "orderid":        "CW-987654",
  "client_orderid": "ORD-001",
  "amount":         1000,
  "currency":       "KES"
}

Error Response

{
  "status":         "error",
  "orderid":        "CW-987655",
  "client_orderid": "ORD-002",
  "error_code":     "INVALID_CONTROL_CODE",
  "error_message":  "The provided control code does not match."
}

Processing Response

{
  "status":         "processing",
  "orderid":        "CW-987656",
  "client_orderid": "ORD-003",
  "amount":         500,
  "currency":       "KES"
}

When you receive processing, the transaction has been accepted and routed to the provider but has not yet completed. The final result will arrive via your webhook callback.

Handling Responses (Node.js)

async function handleCentiwiseResponse(responseData) {
  const { status, client_orderid, orderid, amount, currency } = responseData;

  switch (status) {
    case 'success':
      await db.orders.update(client_orderid, {
        status:     'paid',
        gateway_id: orderid,
      });
      await fulfillOrder(client_orderid);
      break;

    case 'processing':
      await db.orders.update(client_orderid, { status: 'pending' });
      // Final status will arrive via webhook
      break;

    case 'error':
      await db.orders.update(client_orderid, {
        status:       'failed',
        error_code:   responseData.error_code,
        error_message: responseData.error_message,
      });
      break;

    default:
      console.warn('Unknown status:', status, client_orderid);
  }
}

📝
Note: processing is a normal outcome for mobile-money transactions. Most providers complete within seconds to a few minutes, but some can take longer during network congestion. Design your system to handle delayed callbacks gracefully.

Updated 5 months ago

Did this page help you?