Remote API responses and errors

This page is the response reference for the Remote API calls a wallet uses to take a payment: /lookup, /generateTransactionId, /purchaseTx and /transactionState/{transactionId}/v2. It applies to card (3D Secure and PIN) payments and to bill payments. For the call sequence, see Purchase flow; for bill payments and the hosted bill menu, see Bill payments and VAS.

General behaviour

These rules apply to every Remote API endpoint.

Framework-level errors (before business logic)

Framework-level errors share the standard body shape. Field-validation messages join multiple field errors with ; . The unauthenticated 401 response is produced by the security layer and may not follow this shape.

Field validation failure - HTTP 400:

{
  "status": "ERROR",
  "message": "'msisdn' must match \"^[1-9]\\d{8,16}\"; 'value' must not be null"
}

Malformed JSON body - HTTP 400:

{
  "status": "ERROR",
  "message": "Not valid JSON/XML"
}

Not authorised for the endpoint - HTTP 403:

{
  "status": "ERROR",
  "message": "You are not authorized to access this resource"
}

Unhandled system error - HTTP 500:

{
  "status": "ERROR",
  "message": "System error"
}

/lookup

Success (HTTP 200): status is either SUCCESS (code resolved, full lookup data returned) or NEED_INPUT (further input required; inputsRequired populated).

Errors (HTTP 400, status: "ERROR")

Sample responses

Success - HTTP 200, SUCCESS:

{
  "status": "SUCCESS",
  "merchantName": "Bob's Store - Sandton",
  "merchant": "Bob's Store",
  "value": "0123456789",
  "merchantId": 123456,
  "postilionRouting": true,
  "data": {
    "amount": 10.50,
    "currency": "R",
    "currencyCode": "ZAR",
    "shortDescription": "Bob's basket of goods",
    "tipRequired": false,
    "acceptedCards": "master,visa",
    "acceptedPaymentMethods": "SECURE_CODE",
    "secureCodeMerchantId": "70012345",
    "secureCodeUrl": "https://3ds.example.com/api/v2/auth",
    "poi": "12"
  }
}

Need input - HTTP 200, NEED_INPUT: returned when the code needs extra input from the customer before a purchase can proceed. Each entry in inputsRequired describes one prompt (ref, title, and type = NUMBER, NUMERIC, MSISDN, DROPDOWN or TEXT).

{
  "status": "NEED_INPUT",
  "merchantName": "Bob's Store",
  "merchantId": 123456,
  "inputsRequired": [
    {
      "ref": "accountNumber",
      "title": "Please enter your account number",
      "type": "NUMBER",
      "regex": "^[0-9]{6,20}$",
      "regexErrorMessage": "Enter digits only"
    }
  ]
}

Failure - HTTP 400, ERROR:

{
  "status": "ERROR",
  "message": "Code Expired"
}

/generateTransactionId

This endpoint runs the entire /lookup flow first: every /lookup success, NEED_INPUT and error outcome above applies here unchanged. Only when the lookup returns SUCCESS does it issue a transactionId.

Success (HTTP 200): status: "SUCCESS", with transactionId populated.

You can register an optional webhook URL on this call for the transaction's outcome (see Webhooks).

Additional error (HTTP 400, status: "ERROR")

Sample response - HTTP 200, SUCCESS (transactionId issued)

{
  "status": "SUCCESS",
  "merchantName": "Bob's Store - Sandton",
  "merchantId": 123456,
  "transactionId": 988123456,
  "data": {
    "amount": 10.50,
    "currencyCode": "ZAR",
    "acceptedPaymentMethods": "SECURE_CODE"
  }
}

/purchaseTx

📘

Asynchronous processing

A successful submission returns HTTP 200 with status: "PENDING". The purchase is processed asynchronously and the final outcome is not returned on this call. Most processing failures (including a failed or declined 3D Secure authentication, a bank decline, insufficient funds, a limit exceeded and fraud) surface as a terminal state on /transactionState. The synchronous errors below are limited to validation performed at submission time. This endpoint never returns NEED_INPUT.

Authentication block. Provide the authentication data matching the payment method the transaction is configured for: pinData (PIN / account based, encrypted, never plain text), or secureCodeData / secureCodeBasic (3D Secure). An applicable block must be supplied unless your profile is configured for card-not-present (CNP) purchases. Use acceptedPaymentMethods from the lookup (or /binLookup) to decide which to send.

Success (HTTP 200): status: "PENDING", with transactionId and date.

Validation errors (HTTP 400, status: "ERROR")

System errors (HTTP 500)

Sample responses

Success - HTTP 200, PENDING (poll /transactionState for the final outcome):

{
  "status": "PENDING",
  "transactionId": 988123456,
  "date": "2026-07-19 14:32:05"
}

Failure - HTTP 400, ERROR:

{
  "status": "ERROR",
  "message": "Validation error: 'tip' Value cannot be more than 'amount' value"
}

Transaction state (/transactionState/{transactionId}/v2)

Success (HTTP 200): status reflects the transaction's progress. The /v2 variant also returns UTC-normalised date fields alongside the standard transaction detail. /transactionState/{transactionId} (without /v2) applies the same status rules.

📘

Which states you will see

The endpoint returns the state name as is for any state beginning with END_, and for ISSUER_NEVER_APPROVE / ISSUER_NOT_APPROVE_NOW. Every other in-flight state (for example OFF_TO_BANK) is returned as PENDING, and a completed transaction is returned as SUCCESS. Keep polling while you see PENDING.

Terminal states for card and bill payments

Treat the terminal state as an open list: handle any END_* value you do not recognise as a generic failure. The full platform list is in Transaction states.

Errors

Integration notes

• Integrate against the HTTP status and message. Internal error codes are never sent on the wire; they are mapped to 400 or 500.
• Payment is poll-based. PENDING is the normal success response from /purchaseTx; poll /transactionState/{transactionId}/v2 for the final outcome. An optional webhook can be registered on /generateTransactionId or /purchaseTx and used alongside polling. Webhook delivery is best effort: a failed delivery is retried and then abandoned, and never reverses the transaction. Rely on polling for the authoritative result.
• Echo the returned value during a multi-step lookup. The value in a NEED_INPUT response may be rewritten; send it back on the next /lookup or /generateTransactionId call. /purchaseTx uses the transactionId.
• Sample payloads are illustrative. Responses omit null fields, and the exact field set varies by merchant and biller configuration.
• Match message text exactly as returned. Two messages contain spelling mistakes, Bliing is required (billing details missing) and Invalid transaction to provice transaction state., and are returned exactly so. If you match on message text, use the exact strings shown.

What's next

• Step through a payment → Purchase flow
• Bill payments and the hosted bill menu → Bill payments and VAS
• Integration rules → Remote API business rules
• Every platform transaction state → Transaction states