Remote API — business rules

The constraints, validation rules, and routing logic that govern the Scan to Pay Remote API.

These rules govern how the Remote API behaves at integration time and at runtime. For the call sequence itself, see Purchase flow; for the protocol overview, see Remote API overview.


Authentication and authorisation

RuleDetail
One auth mode per managerA manager profile is either Basic or Bearer — not both. Switching between them clears the existing credentials.
JWT is opt-inNew integrations should request Bearer + PKI from the Operations team. Existing Basic integrations continue working without forced migration.
TLS 1.2+ mandatoryHTTP is rejected at the load balancer. No exceptions.
Content-TypeAll POSTs must include Content-Type: application/json. Other content types are rejected with HTTP 400.
No session reuseEach request is independently authenticated. No cookies, no server-side session state.

For the full authentication walk-through, see Authentication.


MSISDN handling

The MSISDN is the wallet's primary identifier across the Remote API — it's effectively the user ID.

RuleDetail
International formatE.g. 27832006283. Leading + is accepted but stripped server-side. National-format (0832006283) is rejected.
Required on most requestsEvery lookup, purchase, history, menu-session, and provisioning call needs msisdn or clientIdentifier. Only /menu and /binLookup are MSISDN-less.
One profile per MSISDN per wallet brandThe same MSISDN can have profiles across different wallet providers, but only one profile per provider.
clientIdentifier as an alternativeIf your wallet identifies customers with its own ID, send clientIdentifier (up to 100 characters) instead of msisdn. A request with neither returns HTTP 400 Validation error: Either 'clientIdentifier' or 'msisdn' is required.

Lookup behaviour

RuleDetail
URL-encode valuesIf value contains URL-special characters (e.g. a short URL), URL-encode before sending.
value is rewritten on responseThe value you sent on lookup may not be the value you send on purchase. Always use the value returned in the lookup response.
transactionId is single-useEach lookup generates a fresh transactionId. Don't reuse it across distinct payments.
NEED_INPUT means call againWhen status: "NEED_INPUT" is returned, prompt the user for the listed inputs and re-call generateTransactionId with the populated inputs array. Use the exact ref names from inputsRequired, and repeat until status is SUCCESS; some billers ask for the account first and the amount on a later step.
Menu selectionsTo pay an item chosen from GET /menu, send value: "MENU-<id>" with the item's id.
/lookup vs /generateTransactionIdBoth run the same lookup and return the same outcomes. Only /generateTransactionId issues a transactionId, once every input is resolved.
Inputs supportedcontact, shipping, billing, extraReference, extraInput, and per-VAS inputs. Anything beyond this list is unsupported and lookup will fail.
Static vs dynamic QRpoi: "11" = static (same QR reused for many transactions). poi: "12" = dynamic (single-use QR).
VAS menuAvailable via GET /menu only if the wallet brand is configured with VAS products by Operations.

Purchase authentication

The /purchaseTx request must include exactly one authentication block — either PIN data (AMT) or 3D Secure data — depending on what the card requires.

MethodRequired blockNotes
AMT (PIN)pinData.encryptedDataPIN must be encrypted using the Scan to Pay PinSecLib. Never send plain PIN.
3DS — fullsecureCodeData with cavv, xid, eciFlag, errorNo, paresStatus, signatureVerificationUse when your wallet has its own ACS integration.
3DS — basicsecureCodeBasic with secureCodeId and paResUse when you ran /secureCodeLookup and the customer completed the ACS challenge in a WebView.

Missing the required block, or sending both, results in HTTP 400 BAD_REQUEST. The only exception is a profile configured for card-not-present (CNP) purchases; without that, a missing block returns Validation error: Required transaction data missing or CNP is not configured for <manager>.

The acceptable auth method for a card is exposed via the lookup response's acceptedPaymentMethods and via /binLookup's authMethod field.


Card data validation

RuleDetail
PAN length14-19 digits, Luhn-10 valid. Non-numeric or invalid Luhn → HTTP 400.
Expiry formatMMYY only. Past-dated expiry rejected at lookup.
CVVRequired when binLookup.cvvNeeded: true (most credit cards).
Account typeRequired when binLookup.accNeeded: true (most debit cards). Values: 10 (Savings), 20 (Current), 30 (Credit). Defaults to 30 if invalid.
Date of birthRequired when binLookup.dobNeeded: true. Format CCYYMMDD.
Cardholder nameRequired when binLookup.cardHolderNameNeeded: true. 3-26 characters.

Card details supplied to /purchaseTx are not auto-registered to a wallet. The wallet provider must explicitly use Card Provisioning to link a card.


Webhook vs polling

The Remote API supports both — but with rules.

RuleDetail
Webhook URL is per transactionPass webhook on /generateTransactionId or on /purchaseTx. It's not a profile-level config. An invalid URL on /generateTransactionId returns HTTP 400 Invalid webhook, must be a valid URL.
Webhook acknowledgementYour endpoint must respond HTTP 200; any other status, or no response within 3 seconds, counts as a failed attempt. A failed delivery is retried up to 9 times with a growing delay (1 to 9 seconds), then abandoned. An unacknowledged wallet webhook never reverses the transaction; the auto-reversal safety net applies only to merchant notifications. See Webhooks (transaction webhooks channel).
Webhook timingIf the merchant uses Portal HTTP notifications, your webhook is sent only after the merchant notification succeeds. If the merchant notification fails on a successful payment, the payment is reversed by the platform; keep polling /transactionState for the authoritative result.
Polling is allowed alongside webhooksUnlike the Merchant API (where polling and webhooks are mutually exclusive), the Remote API allows both — the wallet UI polls for UX, the backend gets the webhook for accounting.
Final state arrives via either channelWhichever you read first, the answer is the same. The webhook payload and the /transactionState body are semantically equivalent.

VAS rules

RuleDetail
Menu is per-walletEach wallet brand has its own VAS configuration. The customer sees what your brand is configured for.
Menu structure is dynamicDon't hard-code menu IDs or names in your wallet UI — render them from the /menu response.
inputsRequired drives the UIWhen a VAS leaf has inputsRequired, prompt the customer accordingly. Validate against the supplied regex.
No VAS for unconfigured walletsIf /menu returns empty arrays, your wallet hasn't been provisioned with VAS — contact [email protected].
Hosted bill menu is opt-inThe hosted bill menu (POST /menu/session) must be enabled for your wallet, with your app deep link per platform registered with Scan to Pay. Until then it returns HTTP 400 Validation error: Web menu not available for this wallet.
Hosted menu URL is single-useCreate a menu session from your back end each time the customer opens bill payments, open the returned url at once (within expiresIn seconds), and never log, store or share it. See Bill payments and VAS.

Transaction history

RuleDetail
Last 10 successful onlyThe history endpoint returns at most 10 most-recent successful transactions for the given MSISDN.
Not a ledgerThis is a wallet-UI convenience — don't use it as a source of truth for reconciliation. Maintain your own ledger from webhooks or polling.
Newest firstSorted descending by transaction date.

State semantics

Status patternWhat to do
SUCCESSShow success, store authCode and retrievalReferenceNumber for any future dispute.
PENDINGTransient. Keep polling. /transactionState returns every in-flight state (for example OFF_TO_BANK) as PENDING.
END_BANK_NON_00 / BANK_REJECTEDBank declined. Check bankResponse against ISO response codes. Show a useful message to the customer.
END_INSUFFICIENT_FUNDS_OR_OVER_CREDIT_LIMITCard lacks funds. Don't retry without customer action.
END_REVERSED / END_REFUNDEDMoney returned to the customer. Update the wallet UI accordingly.
END_VALIDATION_FAILEDRequest was malformed at acquirer hop. Investigate; not the customer's problem.
END_TIMEOUT_*The customer or the network took too long. Allow retry.

Full list with descriptions in Transaction states.


Device data (optional but recommended)

The deviceData block isn't strictly required, but sending it improves fraud-screening and dispute-readiness:

FieldWhy send it
os, osVersion, appVersion, deviceDevice fingerprinting
serialHardware-level identifier for device-binding rules
latitude, longitudeVelocity / geographic fraud checks
clientIPCross-channel anomaly detection

Omit fields you can't capture — partial deviceData is fine. Never spoof values; the platform may flag implausible deltas (e.g. device that was in Cape Town 5 minutes ago suddenly transacting from Lagos).


Idempotency

The Remote API doesn't use a client-supplied idempotency key. Instead:

  • Lookup is naturally idempotent — repeated calls return fresh transactionIds, but it's cheap to call repeatedly.
  • Purchase is keyed by transactionId — a retry with the same transactionId and same card details is safe; the platform de-duplicates server-side.
  • State is read-only — call as often as you need.

If you need stricter idempotency semantics (e.g. retry-safe purchases across network failures), use /transactionState/{transactionId} to confirm before retrying /purchaseTx.


Error handling

HTTPBody statusWhat it means
200SUCCESSRequest completed successfully.
200PENDINGRequest accepted, processing async — poll for the result.
200NEED_INPUTLookup needs additional inputs from the customer.
400ERRORBusiness or validation failure. Read message for the reason.
401Bad credentials, expired JWT, or wrong auth mode for the manager.
403ERRORYour profile is not authorised for this endpoint.
500ERRORInternal server error. Safe to retry with the same transactionId.

Error bodies have the shape { "status": "ERROR", "message": "<message>" }. The platform's extended error codes are not sent on the Remote API. Every message per endpoint is listed in Remote API responses and errors.


Rate limits and abuse prevention

There are no published per-request rate limits today, but the platform monitors for abuse patterns. See Rate limits for the canonical position. Specifically for the Remote API:

  • Lookup spam is the most-common anti-pattern — re-scanning the same QR every second. Implement client-side debouncing.
  • Polling cadence — every 1-2 seconds for the first 30 seconds is fine. Slower is fine. Faster than 1 second has no useful purpose and may trigger throttling.

What's next


Did this page help you?