Crown Agents Bank

Payment Gateway API 1.0 Reference

Introduction

Crown Agents Bank (CAB)'s payment gateway offers a unified API to interact with a range of payment services across multiple countries.

The API is language- and platform-independent. Requests are sent using HTTPS requests; JSON is the data format for both input and responses. Responses are asynchronous and are sent using HTTPS requests from the payment gateway to the client. Transactions are sent in batches to efficiently support bulk-payment operations, but single-transaction batches are supported for use by clients that don’t need bulk payments.

Terminology

Banking Transaction: A transaction that can be accessed through the gateway API, but which originated in a system outside the gateway (e.g. e-banking, SWIFT).

Callback: An HTTPS request sent by the gateway to the client.

Client: A system that sends requests to the gateway and receives results.

Client ID: A unique, CAB-assigned identifier for a client.

Gateway: The software system described by this document, which provides a uniform API to multiple providers.

Intermediary: A financial service provider inbetween the sender and the payer in the payment flow. Typically not present. See payment flow for more.

Payer: The entity that is integrated with the CAB payments platform and is sending payment instructions to CAB. May be different from the sender. See payment flow for more.

Payer account ID: An identifier associated with a payer for a particular provider. A single payer may have multiple account IDs with a single provider.

Provider (or Payment provider): A third-party company or service that distributes money to recipients.

Recipient: A person who receives money from a provider.

Recipient account ID: The identifier associated with a recipient for a particular provider. For mobile money providers, this would typically be the recipient’s phone number. For bank accounts, this would be the recipient's bank account number. A single physical recipient may have multiple account IDs, e.g., because they have more than one mobile phone or because they are served by multiple providers of different types.

Request: An HTTPS request sent by the client to the gateway.

Sender: The originator of the transaction; the entity (person or organisation) whose underlying funds are actually being transferred. May be different to the payer. See payment flow for more.

Subscriber: An end user who receives money from a CAB customer or sends money to a CAB customer. For example, a mobile money account holder.

Subscriber account ID: The identifier associated with a subscriber for a particular provider. For mobile money providers, this would typically be the subscriber’s phone number. A single person or company may have multiple subscriber account IDs, e.g., because they have more than one mobile phone or because they are served by multiple providers of different types.

Transaction ID: A client-supplied unique string value that identifies a single transaction (where a "transaction" is an individual payment or other operation, not a batch). Transaction IDs may not be reused, not even for requests of different types, and it is an error to send a transaction with a previously-used ID. Though any string value may be used, a universally unique identifier (UUID) in canonical hexadecimal format is a recommended choice.

Payment flow

Fundamentally, the Payments Gateway supports bulk disbursements to recipients through various bank and mobile money payment service providers. Where CAB - and our client - sit in the payment chain may vary. These diagrams show some high-level payment chain scenarios and where each party sits. They may be used to contextualise some of the terms in the glossary.

Case 1: CAB client makes payments on its own behalf

Owned payments

No additional transaction information needs to be passed in this case - you've already identified yourself through client ID so the payments platform is aware who the sender is.

Case 2: CAB client makes payments on behalf of its client

Payments on behalf of

In this case, there is an "underlying sender" who is originating payments, and CAB's client sends the payment request to CAB on that sender's behalf.

If this is the case, the sender object must be specified with payment requests to properly identify the payment originator.

Case 3: Sender relationship is owned by a financial service provider intermediary

Intermediated payments

In this case, the relationship with the "underlying sender", the entity originating the payments, is owned by a financial service provider intermediary. CAB's client receives payment instructions from that intermediary, and in turn passes them to CAB.

If this is the case, both the sender and intermediary objects must be specified with payment requests to properly identify the payment originator and ordering institution.

Note that payments of this type - with an intermediary institution - must strictly be pre-agreed in advance of execution, and will be approved on a case-by-case basis.

Requests

All requests are sent over HTTPS using the POST verb. Request and response bodies are in JSON format using UTF-8 encoding. The gateway will send UTF-8 regardless of the value of any HTTP Accept: header included in the request; this is to prevent ambiguous output if the client were to specify an encoding that wasn't capable of representing the text of the response.

Requests that ask the gateway to perform an action are processed asynchronously. HTTPS responses are always generated immediately. For any operation that is not guaranteed to complete instantly, the HTTPS response simply indicates that the request was received and was valid.

To ensure that all requests are processed efficiently, the payment gateway may reject large requests. For more exact information on these request limitations, please see /api/info/requestlimits. If you need to execute requests that are larger than these limits, please contact CAB support at pg.operations@crownagentsbank.com.

Each request must include the following headers:

There are two ways to get results from API requests that perform actions: callbacks and polling.

Callbacks

Callback requests are the preferred way to receive results from the gateway.

Callbacks may be enabled on a per-client or a per-request basis. The result of the operation is transmitted to the client using one or more separate HTTPS requests ("callbacks") to a URL that is associated with the particular client. This allows the API to support operations that would take longer than a client’s request timeout, and allows a client to be restarted or become unreachable while requests are pending, which is particularly important for clients in regions with frequent Internet or power outages.

The results from a single client-to-gateway request can be spread across multiple gateway-to-client callback requests, e.g., if the original request contains a list of payment instructions some of which complete more quickly than others.

The gateway rate-limits its callbacks to avoid pummeling the client with requests; each callback request contains a list of updates. For any pending API request, the gateway will only send one callback request at a time, to prevent situations where clients could process concurrent callbacks in the wrong order.

The gateway may send any number of informational status updates to inform the client of the progress of the transactions in a request; the current states of individual transactions will be indicated by the transaction status codes as described in the "Transaction Status Codes" section. There will be exactly one non-informational status update for each transaction. When the client responds to that update with an HTTP 2xx response code, the gateway considers the transaction complete and will no longer issue further requests about it to the client, though the client may request its status explicitly using the /api/transactionstatus endpoint.

Not all transactions from a given request will necessarily be included in every callback; only transactions whose statuses have changed since the previous callback will be reported. A single callback may contain a mix of informational and final updates for different transactions. A transaction will never be mentioned more than once in a single callback. When all transactions have completed (whether successfully or not) the final callback will contain a flag indicating that it's the last one.

If the client is unreachable when the gateway attempts to make a callback request, the gateway will retry the callback request periodically for at least 3 days before discontinuing further attempts. In that case the status of individual transactions may be queried later using the /api/transactionstatus endpoint.

If the client is still unreachable after 3 days, an automated notification email can be sent to a pre-agreed email address. This email will contain callback failure error details to support debugging.

Each callback request includes a timestamp field in its body. This may be ignored by the client, but may also be used to detect attempted replay attacks; the gateway will never send two callback requests for the same API request with the same timestamp.

Callback requests are signed using the payment gateway's private key, and clients should verify the signature using the gateway's public key. The signature is generated the same way as signatures on requests to the gateway; see the Request Signatures page for details.

The sequence of HTTPS requests and responses looks like this:

Request sequence diagram

Callbacks can only be used for transactions that were originated via the gateway. Details of banking transactions from other systems can only be obtained via the polling mechanism.

Result Polling

Callback requests require the client to be accessible from the public Internet so that the gateway can initiate connections to it, and they require that the client run an HTTPS server to accept requests from the gateway. In cases where one or the other of those requirements is prohibitive, the client may also poll for transaction results using the /api/transactionstatus endpoint.

The client may poll for status at any time; for each transaction, the most recently available status is returned. Client implementations should take a couple of things into account:

  1. The gateway requires time to process a batch. If the client polls for the status of a transaction in a large batch before the gateway has gotten to that transaction, a "transaction not found" error status may be returned since the transaction in question won't have been processed yet. In that case the client should try again later.
  2. Each transaction status record includes a finished flag. Though the API doesn't forbid repeatedly querying the status of a transaction, it's more efficient to stop polling for the status of transactions once that flag is set; it indicates that there will be no further processing and that the current status is final.

It is permitted (though should usually be unnecessary) to poll for the status of transactions whose updates are also being sent to the client using callback requests.

Banking transactions that are not originated via the gateway can only be retrieved via the polling mechanism.

Payment returns

Payments may, from time to time, be marked as "successful" (status 2xx) and be returned by the payment provider due to last-mile delivery issues. For example, a recipient may initiate a reversal; the receiving institution may not recognise the account number; a downstream payment provider may reject a payment for regulatory or compliance reasons. In this case, the payment will be reversed with a new transaction crediting the principal back into the client's wallet. This new transaction will have a new ID, and will include a field transactionIdToReverse which denotes the original payment being reversed.

The client system can be informed of these events in one of three ways:

  1. If configured, callbacks will be sent to a pre-agreed static URL. Recommended.
  2. By polling /api/transactionstatus, specifying startTime and transactionTypes.
  3. If configured, automated emails will be sent to a pre-agreed email address.

Request Format

The body of every API request should be a single JSON object rendered using UTF-8 encoding. The exact contents of the object vary, but most requests include some common fields. These fields are listed in the documentation for individual API requests but described in more detail here.

Field Type Description
clientId String(50) CAB-assigned identifier of the client making the request. In addition to determining which account(s) to use to process the request, a public key associated with this client ID is used to verify the request signature. Required.
requestId String(100) A client-generated unique identifier for this request. This may be any arbitrary string value but must be unique; the gateway will reject a request with a previously-used ID. The request ID serves both as a key to look up request status and as a nonce that's included in the request signature to prevent replay attacks. A universally unique identifier (UUID) in canonical hexadecimal format is a recommended choice. Required.
callbackArgs Any Value to be passed back to the client in all callback requests resulting from this API request. This may be any valid JSON value, including an object with an arbitrary set of fields, and its contents are not interpreted by the gateway, though the gateway may parse and rerender the value (which could result in side effects such as the order of fields in JSON objects changing).
callbackUrl String If supplied, this URL is used for callback requests. This may not be included in requests from clients whose callback URL is configured in the per-client configuration; this is to ensure that the client is informed of all requests performed on its behalf. May be up to 200 characters long.

String Values

If no specific maximum length is indicated in the field type, the maximum string length is 200 characters.

Note that field length restrictions documented here are the "maximum" limits imposed by the CAB platform. Longer strings are never accepted; sometimes shorter strings are required. This is because some downstream payment providers may have more restrictive field length limits.

Similarly, the gateway accepts any valid unicode. But as with string lengths, some providers may be more restrictive.

For more information on string lengths and charsets: * Detailed information for specific providers is given in the section Provider Guide * Please consult with your representative, when integrating, regarding the provider(s) you are using, and if they have any specific restrictions * Finally, descriptive errors are provided if provider-restrictions are breached

Numeric Values

Decimal and integer values may be passed to the payment gateway either as JSON numbers or as strings. That is, "amount": 123.45 and "amount": "123.45" are considered equivalent. If using string formatting, the numbers should use JSON's numeric format: no currency symbol and no punctuation other than a single period character separating the whole and fractional parts.

HTTP Headers

Every API request must contain an API version number in the API-Version HTTP header line. This document describes version 1.0 of the API, so the header should be

API-Version: 1.0

In addition, every API request must be signed using a valid private key. The CAB-assigned ID of the key must be included in the Key-ID header line and the signature must be included in the Request-Signature header line.

See the Request Signatures page for details and example code.

API Functions

/api/balance

Queries the current balances of the wallets used for managed payments. This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

See the Wallets page for information about how wallets work.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
walletId String(100) Restrict the results to a particular wallet. This is in path format, wallet-name. If this isn't specified, all wallets are queried.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String(50) The client ID specified in the request. Required.
wallets Array An array of objects with information about the wallet(s) available to the client. Required.

Each element in the wallets array is an object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
walletId String(100) The wallet's unique identifier. Required.
currency String(3) ISO-4217 currency code of the currency held by this wallet. All amounts are in units of this currency. Required.
currentBalance Decimal The amount of money in the wallet. Required.
availableBalance Decimal The amount of money available to send to recipients. May be less than currentBalance if there are transactions currently in process. Required.

/api/callback/key

Retrieves the ECDSA public key that may be used to verify the signatures of callback requests from the payment gateway. See the Request Signatures page for details about verifying callback request signatures.

Unlike other requests, this should be fetched with HTTPS GET and does not require authentication.

GET Parameters

Parameter Type Description
keyId String The identifier of the key to retrieve. This corresponds to the value of the Key-ID header in callback requests. If this parameter is not passed, the public key for the current signing key is returned.

Response Fields

Field Type Description
keyId String Identifier of this key. This will be included in callback requests as the value of the Key-ID header. Required.
pem String The public key in X.509-encoded PEM format. This value will include line breaks. Required.

/api/cancel

Cancels pending transactions if possible. In general, a transaction may be cancelled if it has not yet been sent to a payment provider. Typically this would be because the provider is offline or because the provider imposes a rate limit and the transaction is part of a large batch.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactionIds Array An array of strings, the IDs of transactions to cancel. Required.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String(50) The client ID specified in the request. Required.
requestId String(100) Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of JSON objects describing the results of the operation. Required.

Each element of the transactions array is a JSON object with the following fields.

Field Type Description
transactionId String(100) The ID of the transaction. Required.
transactionType String One of lookup, pay, reverse, or validate. Additional types may be added over time. Required.
statusType String One of pending, succeeded, or failed. Required.
statusCode Integer Numeric code indicating the current status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the current status of the transaction. Required.
finished Boolean A boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless the original transaction was not found, or when autodetection was requested for the original transaction but wasn't successful.

/api/info/requestlimits

Retrieves the limits on request size currently being enforced by Payment Gateway. These limits are applied per request.

Unlike other requests, this should be fetched with HTTPS GET and does not require authentication.

Input Fields

None. Use the HTTPS GET method.

Response Fields

Field Type Description
maximumRequestTransactionCount Integer For transaction-bearing requests, specifies a limit to the total transactions sent per request.
maximumRequestPayloadBytes Long For all requests, specifies an absolute limit to request payload size, in bytes.

/api/lookup

Looks up the names of a list of recipients. Not all providers are supported; if a lookup request for an unsupported provider is sent, a 320 Operation Not Supported By Provider will be returned.

It is possible to get a failure status in a response that nonetheless includes a value in the name field. If the payment gateway has a name on record for a given recipient account from a previous transaction, that name will be returned even if the provider doesn't support on-demand name lookups. The nameTimestamp field indicates when a name was supplied by the payment provider. Applications can examine that value if they want to discard names that were looked up too long ago and are potentially stale; what age should be considered "stale" depends on the specific needs of each application.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
transactions Array The lookups to process. Required.

Each element of the lookups array has the following fields.

Field Type Description
transactionId String(100) A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String(100) The provider-assigned ID of the recipient, e.g., a phone number in the case of mobile money providers. Required.
recipientBank Object If looking up a name for a bank account, information about the bank that holds the account.
country String(2) The recipient’s two-letter ISO-3166-1 country code.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry requests that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt the request if the initial attempt fails.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

The optional recipientBank field is a JSON object with the following fields. For non-bank lookups, the field should not be included in the transaction data.

Field Type Description
bic String(11) SWIFT/BIC identifier of the recipient's bank. This must be an 8-character bank code with an optional 3-character branch suffix. Either this or bankCode must be specified.
bankCode String(50) Country-specific national code for the bank. This is also known as the "sort code" or "routing code." If this is specified, the country field must be present in the transaction data.
branchCode String(50) If required in the recipient's country, the country-specific identifier for the branch that holds the recipient's account. This is ignored if bankCode is not specified.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String(50) The client ID specified in the request. Required.
requestId String(100) Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of lookup data. Each element in this array corresponds to an element in the lookups array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactionId String(100) Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string lookup. Required.
statusType String One of pending, succeeded, or failed. Required.
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
providerTransactionId String The provider-generated ID for this transaction, if any.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
accountCurrencies Array If available, an array of ISO 4217 currency codes that the account can receive.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.

/api/pay

Initiates payments to some number of recipients.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
scheduledTime String If the request should be deferred, an ISO-8601 timestamp in complete date and time format with time zone (YYYY-MM-DDThh:mm:ssZ) indicating when to process it. Note that this is the time the gateway will start processing the request, not the time that payments will be delivered to recipients. Requests may be scheduled for processing up to six weeks in advance.
fxDetails Object Request-level parameters describing the underlying FX trade, for cross-currency payments. Required for cross-currency payments
transactions Array The transactions to process. Required.

The fxDetails field is a JSON object with the following fields:

Field Type Description
tenor String The tenor on which the FX trade should be credited. Can be equal to spot, tomorrow, or today

Each element of the transactions array is a JSON object with the following fields. This is identical to the transaction structure of the /api/validate request except that some fields which are optional in those requests are required here.

Field Type Description
transactionId String(100) A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String(100) The provider-assigned ID of the recipient. For mobile money payments, this should be the recipient's mobile number including country code. For bank payments, this is the recipient's bank account number. Required.
amount Decimal The amount of money, in the receiving currency, to transfer to the recipient. Required. For cross-currency payments, may be substituted for sourceCurrencyAmount
sourceCurrencyAmount Decimal For cross-currency payments, the amount of money, in the source currency, to transfer to the recipient. The recipient will receive an equivalent amount in the destination currency. Either sourceCurrencyAmount or amount is required for cross-currency payments.
currency String(3) ISO 4217 currency code for the receiving currency. Required.
sourceCurrency String(3) For cross-currency payments, the ISO 4217 currency code for the source currency. Required for cross-currency payments.
name String The recipient’s full name. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy. Required.
recipientBank Object If paying into a bank account, information about the bank that holds the recipient's account.
reference String An identifier for this transaction. Not required to be unique. Recipients will not see this.
recipientId String A unique identifier for this recipient.
clientCustomerId String If the request is being made on behalf of a customer of the client, that customer's unique ID.
reason String(1000) A description of the purpose of the payment. Required for bank payments.
message String Message to include with the payment, if supported by the provider. This may be sent to recipients, e.g. in the body of a confirmation SMS. Ignored if the provider does not support including messages with payments. Some providers may restrict the maximum length or only allow certain characters.
nameParts Array An array of individual name parts. May contain empty strings as elements to maintain consistency across recipients, e.g., if a country’s name format is "First Middle Last" and someone has no middle name, this could be, ["John", "", "Smith"]. If not present and the payment provider requires names to be split into separate parts, the gateway will attempt to parse the value of name.
trusteeName String The name of a person or organization who will accept the funds on the recipient’s behalf. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
aliases Array Additional names that the recipient or trustee is known by. These names will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
phone String The recipient’s telephone number.
address String The recipient’s street address or post office box number. Required for bank payments.
address2 String Additional information about the recipient’s street address.
city String The recipient’s city or town.
province String The recipient’s province or state.
postalCode String The recipient’s postal code.
country String(2) The recipient’s two-letter ISO-3166-1 country code. Required for bank payments.
birthDate String The recipient’s birthdate in ISO-8601 (YYYY-MM-DD) format.
purposeCode String Regulatory-defined purpose code for the payment. Required for specific jurisdictions and payments types only.
documentType String(20) The type of document being used in the documentNumber field. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
documentNumber String(50) The identifier of an identity document for this recipient. For example, a passport or national ID number. If this field is present, documentType must also be present. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
walletId String(100) Which wallet to use for this payment. Be aware that wallets are often tied to payment providers; specifying a wallet ID that isn't valid for this payment's provider will result in an error. If this field isn't present, the payment gateway will select the appropriate main wallet for the payment provider.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry payments that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt payment transmission if the initial attempt fails.
sender Object Details of the transaction's sender, if applicable. See terminology and payment flow for details. If applicable, must be supplied.
intermediary Object Details of the ordering institution, if applicable. See terminology and payment flow for details. If applicable, must be supplied.
swiftParams Object Additional parameters relating to SWIFT payments, not covered by the fields above, for more advanced SWIFT users. Not required in most cases. Usage described in more detail in provider guide's swiftParams section.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

The optional recipientBank field is a JSON object with the following fields. For non-bank payments, the field should not be included in the transaction data.

Field Type Description
bic String(11) SWIFT/BIC identifier of the recipient's bank. This must be an 8-character bank code with an optional 3-character branch suffix. Either this or bankCode must be specified.
bankCode String(50) Country-specific national code for the bank. This is also known as the "sort code" or "routing code".
branchCode String(50) If required in the recipient's country, the country-specific identifier for the branch that holds the recipient's account. This is ignored if bankCode is not specified.

The optional sender field is a JSON object with the following fields.

Field Type Description
customerIdentificationNumber String A client-assigned identifier for this individual sender. For example, if you have a unique user ID for each sender in your application, you can use that user ID as the value for this field. If you ever need to request individual sender data that you've transmitted to the gateway, this identifier will be used to look up the relevant sender details. Required.
accountNumber String The sender's account number associated with this payment. This should be a unique identifier that will enable you to associate a payment with that individual. If your system doesn't have the notion of an account number that's distinct from a customer identification number, you may use the same value as the customerIdentificationNumber field. Required.
name String The sender's full name. Required.
address String The sender's street address or post office box number. Required.
country String(2) The sender's two-letter ISO-3166-1 country code. Required.
address2 String Additional information about the sender's street address.
city String The sender's city or town.
province String The sender's province or state.
postalCode String The sender's postal code.
birthDate String The sender's birthdate in ISO-8601 (YYYY-MM-DD) format.
phone String The sender's telephone number including country code.
documentType String(20) The type of document being used in the documentNumber field. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
documentNumber String(50) The identifier of an identity document for this sender. For example, a passport or national ID number. If this field is present, documentType must also be present. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.

The optional intermediary field is a JSON object with the following fields.

Field Type Description
bic String(11) The intermediary institution's BIC identifier. This must be an 8-character bank code with an optional 3-character branch suffix
partyIdentifier String Unique identifier for the intermediary institution. Typically their account number on the client system. Required if BIC not present.
name String The intermediary institution's full name. Required if BIC not present.
address String The intermediary institution's street address or post office box number. Required if BIC not present.
address2 String Additional information about the intermediary institution's street address.
city String The intermediary institution's city or town.
province String The intermediary institution's province or state.
country String(2) The intermediary institution's two-letter ISO-3166-1 country code. Required if BIC not present.
postalCode String The intermediary institution's postal code.

For more information on provider-specific configurations, see the Provider Guide.

Callback Fields

The callback request contains the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String(50) The client ID specified in the request. Required.
requestId String(100) Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String(100) Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string pay. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.
providerTransactionId String The provider-generated ID for this transaction, if any.
amountPaid Decimal The amount actually paid. May be less than the requested amount for some providers, e.g., if the provider imposes limits on maximum amounts.
currency String(3) ISO 4217 currency code of the amount paid. This field will be present if the payment succeeded.
feePaid Decimal The amount of money charged to process the transaction. This is not included in amountPaid; that is, the total amount debited from the payer account is amountPaid + feePaid.
feeCurrency String ISO 4217 currency code of the fee amount.
datePaid String If it can be determined, the date (and possibly time) the payment was actually made. ISO-8601 format, e.g., 2018-01-01T12:34:56.789Z. Not available on all providers.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.
redemptionCode String Code or password the recipient needs to present to collect the payment, if required by payment provider.
paymentValueDate String The date on which the payment will be made, i.e., settled to the recipient's bank. The value date is calculated from currency cut-off times, banking days, and time taken for a payment to arrive. Relevant only to bank payments with daily settlement cycles.
walletUpdate Object If the payment succeeded, a JSON object describing the effect on the wallet balance.
bankDetails Object For some bank payments, confirmation of the bank to which the payment was paid

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String(100) The ID of the affected wallet if any. Required.
walletCurrency String(3) ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet before the payment was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet after the payment was applied. Required.

The bankDetails object is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
bic String(11) If present, the SWIFT/BIC identifier of the recipient's bank. This will be an 8-character bank code with an optional 3-character branch suffix. Either this or bankCode will be present
bankCode String(50) If present, country-specific national code for the bank. This is also known as the "sort code" or "routing code."
branchCode String(50) If present, the country-specific identifier for the branch that holds the recipient's account.

/api/paymentproviders

Returns a list of the client's supported payment providers, along with any currency restrictions they have. This call always returns its results immediately, in the HTTPS response, and does not generate callbacks.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.

Response Fields

Field Type Description
clientId String(50) Identifies the client. Required.
paymentProviders Array An array of payment provider information. Required.

Each element of the paymentProviders array may contain the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
name String The CAB-assigned ID of the payment provider, e.g. mtn-rwanda. This can be used as the provider ID in calls to /api/pay and /api/validate. Required.
supportedCurrencies Array If present, this field contains a list of ISO 4217 currency codes as strings. These are the only currencies that this payment provider supports. If this field is not present, the payment provider has no currency restrictions.
banks Array If present, this field contains a list of banks the provider supports. If this field is not present, the provider does not support bank payments.
recipientDocumentTypes Array If present, this field contains a list of valid values for the documentType field in /api/pay and /api/validate transactions for this provider.
senderDocumentTypes Array If present, this field contains a list of valid values for the documentType field in the sender object in /api/pay and /api/validate transactions for this provider.

Each element of the banks array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
name String The human-readable name of this bank. Required.
country String(2) The bank's two-letter ISO-3166-1 country code. Required.
bic String(11) An 8- or 11-character SWIFT/BIC for the bank, if the bank has a BIC.
bankCode String(50) Country-specific national code for the bank. This is also known as the "sort code" or "routing code."
branchCode String(50) If required in the bank's country, the national branch code for this branch of the bank.

/api/reverse

Requests reversal (refund) of a previously completed transaction. Reversal frequently requires the payment provider to manually review the request, so this can take a while to complete. Reversals are typically at the discretion of the payment provider and not all transactions may be reversed.

If successful, the amount reversed (minus any applicable fees) is credited to the same wallet that the original payment was made from.

A reversal request is itself a transaction and its progress is reported using the same mechanisms (callbacks and/or polling /api/transactionstatus) as other kinds of transactions.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactions Array An array of reversal request objects. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String(100) A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. This is the ID of the reversal. Required.
transactionIdToReverse String The ID of the original successful transaction that should be reversed. Required.
reason String(1000) A human-readable description of the reason for the reversal. This will be transmitted to the payment provider and may be helpful if the provider reviews reversal requests manually.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String(50) The client ID specified in the request. Required.
requestId String(100) Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of JSON objects describing the results of the operation. Required.

Each element of the transactions array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactionId String(100) The ID of the reversal transaction. Required.
transactionType String The string reverse. Required.
transactionIdToReverse String The ID of the transaction whose reversal was requested. Required.
statusType String One of pending, succeeded, or failed. This refers to the status of the reversal, not the original transaction. Required.
statusCode Integer Numeric code indicating the current status of the reversal. See the "Transaction Status Codes" section. This refers to the status of the reversal, not the original transaction. Required.
statusDescription String A human-readable description of the current status of the reversal. Required.
finished Boolean A boolean value indicating whether this reversal is now finished (either successfully or not as indicated by statusCode). No further updates for a finished reversal will be sent. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect when autodetection was requested but wasn't successful.
reversedAmount (deprecated) Decimal If the reversal was successful, the amount of money that was returned. This may be less than the amount of the original transaction. This field is deprecated. Use "amountReceived" instead.
amountReceived Decimal If the reversal was successful, the amount of money that was returned. This may be less than the amount of the original transaction. This field replaces the deprecated "reversedAmount" field.
reversedCurrency String ISO 4217 currency code of the amount of the reversal, if successful.
feePaid Decimal Amount of the fee paid to process the reversal, if any.
feeCurrency String ISO 4217 currency code of the fee amount.
providerTransactionId String The provider-generated ID for this reversal, if any.
reason String(1000) If available, a human-readable reason for the result of the reversal.
reversedTime String If available, the date and time the provider indicated the reversal was completed, in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). Not all providers indicate the time of completion of reversals.
walletUpdate Object If the reversal succeeded, a JSON object describing the effect on the wallet balance.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String(100) The ID of the affected wallet. Required.
walletCurrency String(3) ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet before the reversal was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet after the reversal was applied. Required.

/api/transactionstatus

Queries the status of transactions. This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

This is most often used in cases where the client can't receive callback requests from the gateway for whatever reason. Callbacks are generally the preferable approach when possible.

Banking transactions that are not originated in the gateway can only be retrieved using this polling request. These transactions are currently not accessible via callback requests.

A few examples:

  • Poll for the status of a pending request by specifying the request's transaction IDs in the transactionIds field.

  • Poll for newly-arrived non-API-initiated transactions (e.g. recipient-initiated reversals and banking transactions) by specifying startTime.

  • Poll for new changes in transaction status across all requests by setting useUpdatedTime to true, endTime to the current time minus a few seconds to account for any clock skew between your server and the payment gateway, and startTime to the value of endTime that was passed to the previous request. (Note that startTime is inclusive and endTime is exclusive, so you won't get duplicate results.)

The results are sorted by the time the payment gateway started processing the transactions unless useUpdatedTime is true, in which case they are sorted by the time of the most recent status change.

Input Fields

Field Type Description Default
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
startTime String Search for transactions whose time (as directed by useUpdatedTime) is at or after a specific time. This must be a timestamp in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). Current time minus 30 days unless transactionIds or originalRequestIds is nonempty, in which case no start time filter is applied by default
endTime String Search for transactions whose time (as directed by useUpdatedTime) is before a specific time. This must be a timestamp in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). startTime plus 30 days unless transactionIds or originalRequestIds is nonempty, in which case no end time filter is applied by default
useUpdatedTime Boolean If true, transactions are matched and sorted based on the time of the most recent status update. If false, transactions are matched and sorted based on the time the gateway started processing them, usually the right choice unless you're polling for updates on long-running transactions. false
sinceTransactionId String Search for transactions that would appear after the specified ID in search results. Results are sorted by time according to the value of the useUpdatedTime field. Combined with maxResults, this may be used to page through a large result set. It may also be used to poll for newly-arrived reversal transactions. Start with the first transaction that matches the other search criteria
providers Array Limit results to transactions from specific payment providers. This is an array of strings, each of which must be the CAB-assigned ID of a provider, e.g., mtn-rwanda.
statusCodes Array Limit results to transactions with specific status codes. This is a list of integers, each of which must be a valid status code as defined in the "Transaction Status Codes" section of this documentation.
statusTypes Array Limit results to transactions of specific status types. This is a list of strings, each of which must be one of pending, succeeded, or failed.
transactionTypes Array Limit results to transactions of specific types. This is an array of strings, each of which must be one of lookup, pay, reverse, or validate.
originalRequestIds Array Search for transactions that were sent to the payment gateway in specific API requests. This is an array of strings as supplied by the client in the requestId fields of previous requests. If search criteria are specified, they act as filters on the list of transactions in these requests. If this is specified, the results will not be filtered by time by default, so you can use this to fetch the statuses of a particular request's transactions without needing to know when it was sent.
transactionIds Array An array of string transaction IDs, either as supplied by the client in earlier API requests or as generated by the gateway for non-client-initiated operations. If search criteria are specified, they act as filters on this list of transactions.
walletIds Array An array of string wallet IDs. Limit the results to only transactions associated with those wallets specified in the array.
maxResults Integer Limit the results to a certain number of transactions. Maximum allowed value is 10000; larger values will be ignored. 10000

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactions Array An array of objects with information about the requested transactions. Required.
finished Boolean If true, this response contains results for all transactions matching the search criteria. If false, this response contains the number of results specified in the maxResults field of the request, but there are additional transactions matching the criteria. Required.

Gateway Transactions

For gateway transactions, each element in the transactions array has the same fields as would be present in a callback request for the transaction. Since this can vary depending on the specific type of transaction, the full set of field combinations isn’t listed here (refer to the callback formats for the API requests that initiate new transactions) but each entry in the array will contain the following fields which are present in the callbacks for all transactions:

Field Type Description
transactionId String(100) Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String One of lookup, pay, reverse, or validate for transactions that exist, or null if the request specified a nonexistent transaction ID. Additional types may be added later. Required..
statusType String One of pending, succeeded, or failed. Required.
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.

In addition, the following may be present:

Field Type Description
relatedTransactionIds Array If subsequent transactions are related to this one, an array of their transaction IDs. Currently the only transactions that can appear here are reversal requests. To find out the status of the related transactions, query them by ID.
foreignExchange Object For cross-currency payments, confirmation of the attributes of the underlying FX trade

The foreignExchange field is a JSON object with the following fields. This will only be present for cross-currency payments. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
sourceCurrencyAmount Decimal The amount to be debited for the payment, in source currency. Required.
sourceCurrency String(3) ISO 4217 currency code of the amount to be debited for the payment. Required.
linkedFxTradeDetails Object Attributes relating to the underlying FX trade. The contents of this object will be identical across all transactions in the request. Required.

The linkedFxTradeDetails field is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
fxTradeId String ID number for the underlying FX trade. Used to easily identify the trade to CAB support in case of issues. Required.
sourceCurrency String(3) ISO 4217 currency code of the amount to be debited for the request. Required.
sourceCurrencyAmount Decimal Amount which will be debited for the request to pay for the FX trade. Required.
destinationCurrency String(3) ISO 4217 currency code of the currency that the recipient will receive for the FX trade. Required.
destinationCurrencyAmount Decimal Amount, in detination currency, which the recipient will receive for the request for the FX trade. Required.
typeOfAmountSpecified String Indication of which amount (source or destination currency value) was originally specified by the client. Required.
fxRate Decimal(30) FX rate applied to the FX transaction. Always given in units of destination currency per unit of source currency; ie the rate is always calculated as (destinationCurrencyAmount / sourceCurrencyAmount). Multiplying the sourceCurrencyAmount by fxRate will give the destinationCurrencyAmount. Given in high precision to avoid rounding errors; additional decimal units beyond currency precision levels should be ignored. Required.
tenor String Tenor applied to the FX trade. Note that this may not be the same as the tenor originally requested, if the tenor requested was not possible due to missing cutoff times. May be either spot, tomorrow, or today. Required.
fxValueDate String Value date applied to the FX trade. This is the date, in London time, on which the source currency will be debited from your account, and the destination currency will be credited. Calculated based on the requested tenor and FX market open days / holidays. Format YYYY-MM-DD. Required.
fxTransactionTime String Datetime on which the FX trade was booked, in format YYYY-MM-DDThh:mm:ss.sssZ. Required.

Banking Transactions

For banking transactions there are a specific set of elements that can be returned as part of the transaction status. As there is currently no callback support for banking transactions, the full set of possible elements is defined below. Each entry in the array may contain the following fields for each transaction:

Field Type Description
transactionId String(100) The generated unique id of this transaction, derived from the system that it originated. Required.
transactionType String One of pay, reverse, fee, feeReversal, moneyMarketMovement, moneyMarketMovementReversal, tradeFinance, tradeFinanceReversal, interest, interestReversal, fx, fxReversal, other, or otherReversal for transactions that exist, or null if the request specified a nonexistent transaction ID. Additional types may be added later. Required..
statusType String One of pending, succeeded, or failed. For banking transactions the value will normally be succeeded. Required.
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). Required.
timestamp String Timestamp of the transaction in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
amountPaid Decimal For a debit transaction, the amount of this transaction in the currency of the account. Contains a positive decimal that equates to the amount that was debited from the account. Not present for credit transactions.
amountReceived Decimal For a credit transaction, the amount of this transaction in the currency of the account. Contains a positive decimal that equates to the amount that was credited to the account. Not present for debit transactions.
currency String(3) ISO 4217 currency code of the account currency. The currency in which amountPaid is specified. Required.
isReversal Boolean Whether this transaction represents a reversal or not. Required.
additionalDetails String Additional details related to the transaction.
exchangeRate Decimal If the transaction has a foreign currency exchange then the exchange rate applied is given.
inboundReference String The inbound reference associated with the transaction.
name String The beneficiary name associated with the transaction.
narrative String The narrative description for the transaction.
orderingCustomer String The customer name that ordered the transaction.
providerTransactionId String The transaction reference.
transactionAmount Decimal The amount in the currency of the transaction.
transactionCurrency String(3) ISO 4217 currency code associated with the transaction amount.
reason String A description of the purpose of the payment (remittance information).
paymentValueDate String Date on which the payment was (or will be) made in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ).
walletUpdate Object A JSON object describing the effect on the wallet balance.

The optional walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String(100) The ID of the affected wallet, if any. Required.
walletCurrency String(3) ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet before the transaction was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet after the transaction was applied. Required.

/api/validate

Validates a list of proposed transactions. Will check if the recipient account passes screening. May verify that information about recipients is accurate, and return corrected information when available from the underlying payment provider. May confirm that there is money available to cover the requested payments. The specific validation steps will vary depending on the capabilities of the provider.

Input Fields

Field Type Description
clientId String(50) Identifies the client. Required.
requestId String(100) Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
transactions Array The transactions to process. A "transaction" here refers to verifying a recipient’s information, not transferring money. Required.

Each element of the transactions array has the following fields. This is identical to the transaction structure of the /api/pay request except that some fields which are required in that request are optional here.

Field Type Description
transactionId String(100) A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String(100) The provider-assigned ID of the recipient, e.g., a phone number in the case of mobile money providers. Required.
name String The recipient’s full name. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy. Required.
amount Decimal The amount of money to transfer to the recipient.
currency String(3) ISO 4217 currency code.
payerAccountId String The ID of the account that will act as the source of the payment.
recipientBank Object If validating a payment to a bank account, information about the bank that holds the recipient's account.
reference String An identifier for this transaction. Not required to be unique. Recipients will not see this.
recipientId String A unique identifier for this recipient.
clientCustomerId String If the request is being made on behalf of a customer of the client, that customer's unique ID.
walletId String(100) Which wallet to validate against. Be aware that wallets are often tied to payment providers; specifying a wallet ID that isn't valid for this validation request's provider will result in an error. If this field isn't present, the payment gateway will select the appropriate main wallet for the payment provider.
reason String(1000) A description of the purpose of the payment. Required for validation of bank payments.
message String Message that would be included with the payment, if supported by the provider. The gateway will validate that the message would not be rejected if it was included with a payment request; no message is sent to the recipient when validating payments.
nameParts Array An array of individual name parts. May contain empty strings as elements to maintain consistency across recipients, e.g., if a country’s name format is "First Middle Last" and someone has no middle name, this could be, ["John", "", "Smith"]. If not present and the payment provider requires names to be split into separate parts, the gateway will attempt to parse the value of name.
trusteeName String The name of a person or organization who will accept the funds on the recipient’s behalf. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
aliases Array Additional names that the recipient or trustee is known by. These names will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
phone String The recipient’s telephone number.
address String The recipient’s street address or post office box number. Required for bank transactions.
address2 String Additional information about the recipient’s street address.
city String The recipient’s city or town.
province String The recipient’s province or state.
postalCode String The recipient’s postal code.
country String(2) The recipient’s two-letter ISO-3166-1 country code. Required for bank transactions.
birthDate String The recipient’s birthdate in ISO-8601 (YYYY-MM-DD) format.
purposeCode String Regulatory-defined purpose code for the payment. Required for specific jurisdictions and payments types only.
documentType String(20) The type of document being used in the documentNumber field. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
documentNumber String(50) The identifier of an identity document for this recipient. For example, a passport or national ID number. If this field is present, documentType must also be present. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
sender Object Details of the transaction's sender, if applicable. See terminology and payment flow for details. If applicable, must be supplied.
intermediary Object Details of the ordering institution, if applicable. See terminology and payment flow for details. If applicable, must be supplied.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry requests that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt the request if the initial attempt fails.
swiftParams Object Additional parameters relating to SWIFT payments, not covered by the fields above, for more advanced SWIFT users. Not required in most cases. Usage described in more detail in provider guide's swiftParams section.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

The optional recipientBank field is a JSON object with the following fields. For non-bank validations, the field should not be included in the transaction data.

Field Type Description
bic String(11) SWIFT/BIC identifier of the recipient's bank. This must be an 8-character bank code with an optional 3-character branch suffix. Either this or bankCode must be specified.
bankCode String(50) Country-specific national code for the bank. This is also known as the "sort code" or "routing code."
branchCode String(50) If required in the recipient's country, the country-specific identifier for the branch that holds the recipient's account. This is ignored if bankCode is not specified.

The optional sender field inside a transaction object contains an object with the following fields.

Field Type Description
customerIdentificationNumber String A client-assigned identifier for this individual sender. For example, if you have a unique user ID for each sender in your application, you can use that user ID as the value for this field. If you ever need to request individual sender data that you've transmitted to the gateway, this identifier will be used to look up the relevant sender details. Required.
accountNumber String The sender's account number associated with the validation request. This should be a unique identifier that will enable you to associate a payment with that individual. If your system doesn't have the notion of an account number that's distinct from a customer identification number, you may use the same value as the customerIdentificationNumber field. Required.
name String The sender's full name. Required.
address String The sender's street address or post office box number. Required.
country String(2) The sender's two-letter ISO-3166-1 country code. Required.
address2 String Additional information about the sender's street address.
city String The sender's city or town.
province String The sender's province or state.
postalCode String The sender's postal code.
birthDate String The sender's birthdate in ISO-8601 (YYYY-MM-DD) format.
phone String The sender's telephone number including country code.
documentType String(20) The type of document being used in the documentNumber field. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.
documentNumber String(50) The identifier of an identity document for this sender. For example, a passport or national ID number. If this field is present, documentType must also be present. Valid document types can vary by provider and can be queried using the /api/paymentproviders endpoint.

The optional intermediary field is a JSON object with the following fields.

Field Type Description
bic String(11) The intermediary institution's BIC identifier. This must be an 8-character bank code with an optional 3-character branch suffix
partyIdentifier String Unique identifier for the intermediary institution. Typically their account number on the client system. Required if BIC not present.
name String The intermediary institution's full name. Required if BIC not present.
address String The intermediary institution's street address or post office box number. Required if BIC not present.
address2 String Additional information about the intermediary institution's street address.
city String The intermediary institution's city or town.
province String The intermediary institution's province or state.
country String(2) The intermediary institution's two-letter ISO-3166-1 country code. Required if BIC not present.
postalCode String The intermediary institution's postal code.

Callback Fields

Field Type Description
clientId String(50) The client ID specified in the request. Required.
requestId String(100) Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String(100) Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string validate. Required.
statusType String One of pending, succeeded, or failed. Required.
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String(40) The CAB-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.
providerTransactionId String The provider-generated ID for this transaction, if any.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.

Example Request Flow

From client:

POST /api/pay HTTP/1.1
API-Version: 1.0
Content-Type: application/json; charset=UTF-8
Host: payment-api.thesegovia.com
Key-ID: xxxxxxxxxxxx
Request-Signature: ecdsa=(base64 string)

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "callbackArgs": {
    "reference": 29489213
  },
  "transactions": [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "provider": "mtn-rwanda",
      "recipientAccountId": "250789999999",
      "amount": 125,
      "currency": "RWF",
      "name": "Paul Niehaus" },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "provider": "airtel-ghana",
      "recipientAccountId": "233888888888",
      "amount": 240,
      "currency": "GHS",
      "name": "Michael Faye" }]}

Response from gateway:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=UTF-8

{ "message": "Request Received" }

Request from gateway with informational status update. One transaction has been sent to the payment provider and the other is queued to be sent.

POST /callback/result HTTP/1.1
API-Version: 1.0
Content-Type: application/json; charset=UTF-8
Key-ID: xxxxxxxxxxxx
Request-Signature: ecdsa=(base64 string)

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:26.418Z",
  "callbackArgs": {
    "reference": 29489213
  },
  "transactions": [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 110,
      "statusDescription": "Waiting for a response from the provider.",
      "finished": false },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 100,
      "statusDescription": "The gateway has received the transaction.",
      "finished": false }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Request from gateway with informational status update. The second transaction has been sent to the payment provider. Note the first transaction is not included here since its status hasn’t changed:

POST /callback/result HTTP/1.1
API-Version: 1.0
Content-Type: application/json; charset=UTF-8
Key-ID: xxxxxxxxxxxx
Request-Signature: ecdsa=(base64 string)

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:37.110Z",
  "callbackArgs": {
    "reference": 29489213
  },
  "results": [
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 110,
      "statusDescription": "Waiting for a response from the provider.",
      "finished": false }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Request from gateway with final status updates for both transactions:

POST /callback/result HTTP/1.1
API-Version: 1.0
Content-Type: application/json; charset=UTF-8
Key-ID: xxxxxxxxxxxx
Request-Signature: ecdsa=(base64 string)

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:39.767Z",
  "callbackArgs": {
    "reference": 29489213
  },
  results: [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "transactionType": "pay",
      "amountPaid": 125,
      "currency": "RWF",
      "finished": true,
      "statusType": "succeeded",
      "statusCode": 200,
      "statusDescription": "Succeeded with provider transaction ID ABCDEFG",
      "providerTransactionId": "ABCDEFG",
      "feePaid": 5,
      "feeCurrency", "RWF",
      "datePaid": "2016-03-12T14:52:20.303Z"
    },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "finished": true,
      "statusType", "failed",
      "statusCode": 420,
      "statusDescription": "Recipient 233888888888 not found" }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Transaction Status Codes

Transaction status is represented in three fields in the API.

statusType is a high-level categorization of the general state of the transaction. If all your application needs to know is whether a transaction is pending, successful, or failed, this field is all you need to examine.

statusCode is an enumerated integer value that contains more detail about what's going on with the transaction. The list of status codes is subject to future expansion, so if you're taking different actions based on specific conditions, it's a good idea to make sure your application falls back to reasonable default behaviors based on the status type. A given status code will always have the same status type.

statusDescription is a human-readable description of the transaction's status. In many cases this will simply be a description of the status code, but when there's additional relevant information (e.g., an error message from a payment provider) it may be included in the description.

As described earlier in this document, a transaction may progress through any number of informational statuses (e.g., "Transmitted," "Provider In Progress").

It is important to note that these status codes are returned as fields in JSON data structures, and there may be different status codes for different transactions listed in a single JSON structure. Although some transaction status codes are modeled after HTTP status codes, that should be considered a mnemonic aid only; these are not the HTTP response codes the gateway returns in response to client requests. See the "Example Request Flow" section for a demonstration of the distinction between HTTP response codes and transaction status codes.

Although some of the status codes for similar conditions have similar numeric values, your application should avoid assuming that certain numeric ranges of status codes have semantic meanings. Future additions to the list of status codes may violate that assumption.

Status Types

The statusType field may have one of the following values.

Value Description
pending The transaction is in progress. All informational status codes have this type.
succeeded The transaction was completed successfully.
failed The transaction failed or was rejected.

Pending Status Codes

Status codes with "pending" types indicate that the request is still ongoing (and thus the client can expect future results). A client may safely ignore all these status codes if it doesn't need to present progress information to a user. The gateway may issue any number of informational status updates, or none, over the course of handling a transaction if callbacks are enabled for the client or a callback URL was included in the request that initiated the transaction.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

100 In Process

The gateway has received the transaction.

102 Awaiting Approval

The gateway is awaiting approval to process the transaction. Transactions may be approved using the payment gateway's web interface.

103 Awaiting Funding

There are insufficient funds to process the transaction. It is being held until sufficient funds are available to cover all the transactions in the request. See the Wallets page for more information about wallet balances.

104 Awaiting Scheduled Time

The transaction's request specified a scheduled start time, and that time hasn't arrived yet.

106 Processing Funds

The gateway is waiting for an automatic funding process to complete.

110 Transmitted

The transaction has been transmitted to the underlying provider and the gateway is awaiting a response.

112 Held For Review

The transaction is awaiting review by CAB's compliance team.

115 Retransmitted

The gateway needed to retransmit the transaction, e.g., because the provider indicated there was a transient error.

119 Transmission Failed

The gateway failed to send the transaction to the provider, e.g., because of network connectivity problems, and will retry later. As with all 1xx status codes, no client action is required.

120 Provider In Progress

The provider has accepted, and has started processing, the transaction.

129 Provider Stalled

The provider has indicated that the transaction cannot be processed immediately, but the transaction is still queued for processing on the provider’s side.

130 Pending FX

The cross-currency transaction is waiting for an FX deal to be booked, to buy the payment currency

150 Transaction Processed

The provider has indicated that it is finished processing the transaction, but has not yet returned final results to the gateway.

180 Status Unknown

The gateway is currently unable to determine the status of the transaction, e.g., because a payment provider failed to indicate whether or not the transaction succeeded. Depending on what happened, the gateway may be able to automatically determine the status at a later time. If this status persists, please contact CAB support.

189 Rejected By Provider But Will Retry

The provider returned an error response indicating it was currently unable to process the transaction. The gateway will automatically retry the transaction.

190 Cancellation Requested

The gateway has been asked to cancel the transaction, but has not yet requested the cancellation from the provider.

191 Cancellation In Progress

The provider has been asked to cancel the transaction, but has not yet confirmed the cancellation.

199 Cancellation Rejected

The provider was unable to cancel the transaction; it will be processed as originally requested.

"Succeeded" Status Codes

Status codes with "succeeded" types indicate that a transaction completed as requested. A succeeded status code indicates that the gateway considers the transaction finished and will not send any subsequent results.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

200 Complete

The transaction completed exactly as specified and there were no warnings from the provider.

201 Delivered

The transaction instructions have been delivered to the provider, but the provider does not have the ability to acknowledge successful receipt. The client may be able to verify delivery using some other method including manual intervention, but the gateway has taken the transaction as close to completion as it can. Most providers are able to confirm receipt, so in practice this status code should be rare.

2021 Unverified Account

The lookup was successful, but the provider hasn't fully verified the recipient account (typically due to missing KYC). Payments to this account will fail.

2022 Restricted Account

The lookup was successful, but the provider has placed a restriction on the account (typically due to missing KYC). Payments to this account might fail.

2023 Account Cannot Receive Payments

The lookup was successful, but the account cannot receive payments (typically a mobile number that is not registered for mobile money).

"Failed" Status Codes

Status codes with "failed" types indicate that the transaction was unsuccessful. A failed code indicates that the gateway considers the transaction finished and will not send any subsequent results; the client must transmit a new transaction to the gateway if it wishes to retry the operation.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

290 Cancelled

The transaction was successfully cancelled at the request of the client.

303 The Foreign Exchange Trade Request Failed

The FX deal could not be booked and the transactions will not be released for processing

304 The Requested Foreign Exchange Currency Combination Is Not Supported

The currency pair submitted by the client is not permitted; speak to your representative if you believe you are receiving this incorrectly.

305 The Foreign Exchange Trade Failed Due To An Internal Error

An internal error caused the FX trade to fail. This may be retryable; consult your representative.

306 The Foreign Exchange Trade Request Failed Due To It Being Outside Trading Hours

The request was submitted outside of the supported trading hours and was rejected.

310 Recipient Information Mismatch

The supplied recipient information (name, address, etc.) did not match the provider’s records.

311 Missing Recipient Information

The transaction didn't include enough information about the recipient.

312 Transaction Failed Screening

The transaction has failed screening due to internal policy restrictions. Please contact CAB at pg.operations@crownagentsbank.com if you have any questions.

313 Missing Sender Information

The transaction didn't include enough information about the sender.

314 Funds Held for Compliance

The transaction has been blocked due to internal policy restrictions, and the funds involved are being held for compliance reasons. Please contact CAB at pg.operations@crownagentsbank.com for additional information.

319 Transmission Failed Permanently

The gateway failed to send the transaction to the provider, and will not retry.

320 Operation Not Supported By Provider

The requested operation is not supported by the payment provider.

321 Currency Not Supported By Provider

The request specified a currency that isn’t supported by the payment provider.

322 Amount Precision Not Supported By Provider

The request specified an amount with a precision that isn’t supported by the payment provider, e.g., an amount in cents when the provider only accepts whole US dollar amounts.

330 Insufficient Funds

The payer account didn’t have enough funds to cover the requested payment.

3301 Wallet Is Below Minimum Balance

The wallet's available balance is below the minimum balance, and thus no new payments funding operations may be performed.

3302 Would Exceed Wallet Negative Balance Limit

The requested transaction(s) would cause the wallet's balance to fall below its negative balance limit.

331 Payer Accounts Not Permitted

The transaction details included a payer account ID for a payment provider that doesn't support selecting specific payer accounts.

332 No Payer Account Specified

The transaction details didn't include a payer account ID for a payment provider that requires selecting specific payer accounts.

340 Transaction Too Small

The transaction amount was smaller than the minimum allowed size for this provider.

341 Transaction Too Large

The transaction amount was larger than the maximum allowed size for this provider.

342 Would Exceed Recipient Maximum Balance

The requested payment would cause the recipient's account to exceed its maximum balance. You may wish to ask the recipient to withdraw money from their account before you retry the payment. Note that this limit is imposed by the provider. In some cases, recipients can increase their maximum balance by making a request to their payment provider.

350 Timed Out, Cancelled

The provider failed to process the transaction in the amount of time allowed (this can vary by provider) and the transaction has been discarded. When this status code is returned, the gateway will have cancelled the transaction with the provider and no further action is required.

359 Timed Out, Not Cancelled

The provider failed to process the transaction in the amount of time allowed (this can vary by provider) and the transaction has been discarded. This status code indicates that the gateway was unable to confirm that the provider cancelled the transaction; manual intervention may be required.

361 Duplicate Payment Rejected by Provider

The provider rejected the transaction as a duplicate payment. Retrying the payment at a later time or with a slightly different amount may allow the payment to be processed.

370 Recipient Account Locked

The provider rejected the transaction because the recipient's account is locked or frozen and therefore can't receive payments.

371 Recipient Account Not Activated

The provider rejected the transaction because the recipient's account is not activated, or otherwise not configured to receive payments. For mobile money providers, this generally means that the recipient has a valid account with the provider but has not activated its mobile money functionality.

380 Invalid BIC

The supplied BIC format was valid, but it did not exist within the BIC Directory. The BIC that failed validation is included in the description.

381 Invalid BIC Format

The supplied BIC format was invalid. The BIC that failed validation is included in the description.

399 Rejected by Provider

The provider has refused to complete the transaction for a reason not covered by a more specific status code. The description included alongside the status code may include additional details.

400 Bad Request

The gateway couldn’t decode the transaction.

401 Unknown Client ID

The supplied client ID was invalid.

402 Unauthorized

The client attempted to initiate a transaction for which it didn’t have permission.

404 Transaction Not Found

The client requested the status of a transaction that isn’t known to the gateway. This is not a real status code that an actual transaction can have; it's only ever returned by /api/transactionstatus to indicate that the transaction being queried doesn't exist.

4041 Target Transaction Not Found

This transaction attempted to refer to another transaction, and the other transaction didn't exist. This is distinct from status code 404 in that the transaction with this status exists, but failed because another transaction also needed to exist. For example, a reversal transaction might have this status if it is an attempt to reverse a nonexistent transaction.

405 Payment Provider Not Found

The client specified a payment provider that isn’t known to the gateway.

406 Provider Autodetection Failed

The client specified that payment provider should be automatically inferred by the gateway from looking at the recipient account ID (which should be a phone number with country code), but the gateway cannot find a provider for the recipient.

407 Provider Not Available

The requested payment provider is temporarily unavailable. This can be due to a number of situations, for example, the provider may be undergoing scheduled maintenance.

410 Missing Fields

Required fields were missing.

420 Recipient Not Found

The provider doesn’t recognize the requested recipient (typically because the account number is wrong).

4201 Recipient Cannot Receive Payments

The provider recognized the requested recipient, but the recipient cannot receive payments (typically a mobile number that is not registered for mobile money).

4202 Recipient Not Verified

The provider recognized the requested recipient, but the recipient is not fully verified (typically an account which is missing KYC).

421 Payer Not Found

The provider doesn't recognize the requested payer (typically because the account number is wrong).

430 Operation Not Valid

This transaction's operation wasn't valid.

4301 Target Transaction Not Successful

This transaction attempted to perform an operation that requires a successful transaction as its target, and the specified target transaction wasn't successful. For example, an attempt to reverse a failed payment would result in this status.

4302 Transaction Type Not Reversible

This transaction attempted to reverse a transaction of a type that is incapable of being reversed, such as a validate transaction.

4303 Transaction Already Reversed

The transaction whose reversal is being requested by this transaction has already been successfully reversed.

4304 Reversal Already Requested

There is already a pending reversal request for the transaction whose reversal this transaction is requesting.

4305 Too Late to Reverse Transaction

The transaction is no longer able to be reversed. For example, if the recipient has already spent the money from a payment, a provider might refuse to reverse the payment.

4306 Transaction Not Holding Funds

This transaction attempted to release funds held by a payment that terminated in status 314 Funds Held for Compliance), but the target payment did not terminate in that status. This status only applies to reversal transactions, never to payments.

440 Wallet Not Found

The requested operation specified a wallet that doesn't exist.

500 Internal Error

Catch-all error code. An internal error occurred in the gateway that prevented the transaction from being successfully completed. The gateway will not automatically retry the transaction.