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.

Tenor: For cross-currency payments, the delivery / settlement timeframe for the foreign exchange. Can be same day, next day, or 2 FX days. Note that FX days are not always the same as calendar or business days, as they are dependent on local FX- market holidays. See the provider guide for more information.

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

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

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

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:

• API-Version should have the value 1.0.
• Key-ID is described on the Request Signatures page.
• Request-Signature is described on the Request Signatures page.

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:

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.
4. For more details on the payment return callback fields, please see /api/transactionstatus

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 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/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.
foreignExchange	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 foreignExchange 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, TOM, or TOD. See provider guide for more information. Required for cross-currency payments.

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, either this or sourceCurrencyAmount must be specified
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.
recipientTaxId	String(14)	Tax identification number of the recipient.
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.
benIntermediaryAgent	Object	Information which specifies the financial institution through which the transaction must pass to reach the beneficiary.

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.

The optional benIntermediaryAgent field is a JSON object with the following fields. For offshore payments, the field should be included in the transaction data.

Field	Type	Description
bic	String(11)	The beneficiary intermediary agent's BIC identifier. This must be an 8-character bank code with an optional 3-character branch suffix.

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
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/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 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 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, TOM, or TOD. See provider guide for more information. 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.

Reversed payments fields

Payments could result to a 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.

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

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

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/validate

Validates a list of proposed transactions, which may include verifying the accuracy of recipient information, except for bank payments where the account details of the recipient will not be verified. In cases where available, corrected recipient information may be returned from the underlying payment provider. May check the availability of sufficient funds to cover the requested payments. No funds will be deducted from the wallet. 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.
recipientTaxId	String(14)	Tax identification number of the recipient.
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.
benIntermediaryAgent	Object	Information which specifies the financial institution through which the transaction must pass to reach the beneficiary.

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.

The optional benIntermediaryAgent field is a JSON object with the following fields. For offshore payments, the field should be included in the transaction data.

Field	Type	Description
bic	String(11)	The beneficiary intermediary agent's BIC identifier. This must be an 8-character bank code with an optional 3-character branch suffix.

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

140 Provider Is Awaiting The Value Date Before Processing

The gateway has received the transaction but is awaiting the transaction's value date before proceeding.

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.

"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.

301 Approver Rejected The Request

The payment request was rejected. If this was in error, please create a new payment request.

302 Abandoned By Creator

The initiator of the payment request abandoned it.

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 ClientServices@crownagentsbank.com for additional information.

315 Missing Intermediary Information

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

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.

441 Wallet Cannot Be Used With Requested Provider

The requested operation specified a wallet that cannot be used with the requested provider.

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.