KreedX — Banking API and Payments Platformby DigiPulse Solutions
Developer Docs

Status & Error Codes

Every API answers in the same envelope, so a single handler in your code covers the whole catalogue.

Sample guide

This shows how it works across our APIs. Exact header names, values and any extra steps are confirmed with your sandbox credentials.

The response envelope

Check success first. When it is true the result is in data; when it is false the reason is in error.

Success
{
  "success": true,
  "data": {
    "referenceId": "KRXB71Q2M8",
    "status": "SUCCESS"
  }
}
Failure
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "billerId is required"
  }
}

HTTP status codes

Branch on error.code, not on the message — messages are written for people and may be reworded.

StatusCodeDescription
400VALIDATION_ERRORA field is missing or malformed. The message names the field.
401UNAUTHORIZEDThe API key is missing, wrong, or for the other environment.
404NOT_FOUNDNo resource with that ID or reference exists.
409DUPLICATE_REFERENCEThis clientReference was already used. Safe to treat as a repeat of the first call.
429RATE_LIMITEDToo many requests. Back off and retry after the Retry-After header.
503UPSTREAM_UNAVAILABLEThe biller, bank or network is down. Retry later; nothing was charged.

What to retry, and what not to

StatusDo this
400Fix the request. Retrying the same body will fail the same way.
401Check the key and which environment it belongs to.
409Nothing to do — the first call with this clientReference already went through.
429Wait for the Retry-After header, then try again.
503Retry later with the same clientReference. Nothing was charged.

Transaction statuses

A successful request is not always a finished transaction. The status field tells you where it stands.

StatusAPIsDescription
PENDINGBill and card paymentsAccepted and in progress. The final result arrives by webhook or the status call.
SUCCESSBill and card paymentsCompleted. Safe to show the customer a receipt.
FAILEDBill and card paymentsDid not go through. Show the reason; the customer can try again.
RECEIVEDCash collectionsCash taken at the counter, not yet on the account.
CREDITEDCash collectionsLanded on the loan or customer account.
REVERSEDCash collectionsA credited collection was reversed.

A timeout is not a failure

If your request times out, the transaction may still have gone through. Do not mark it failed, and do not retry with a new reference. Check its status — or resend with the same clientReference, which returns the first result instead of charging twice.