This page contains additional information about using specific providers and types of payment through the Payment Gateway.
Bank payments via SWIFT provider
Character limits and restrictions
As with many payment providers, payments made using the SWIFT provider have their own field length and character set restrictions. For field lengths, see guidance below ("/api/pay field guidance"). The permissable set of characters for use with the SWIFT provider are:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789/-?:().,'+
Please note that whilst allowable characters a colon : or hyphen - should not be passed as the first character in a field.
Payment amount decimals
The SWIFT provider will accept at most 2 decimal places for all currencies. While some global currencies (notably Dinars as used by Jordan, Tunisia, Kuwait, and others) use 3 decimal places, this is not currently supported. Clients should appropriately convert payment instructions to 2 decimal places prior to sending.
Some currencies (e.g. Japanese Yen) are zero-decimal. The SWIFT provider will reject payment requests that contain any decimal places for these currencies. Please consult your representative for more information.
/api/pay field guidance
This section provides additional guidance on payloads for /api/pay to execute bank payments via the SWIFT provider. Only the elements in the transactions array are specified here.
See API Reference for full details on the /api/pay endpoint, including top-level field information.
Note that the field length limits are different to those given in the API Reference. This is because the SWIFT provider has its own limits (see section above). For SWIFT payments, please adhere to these limits.
Transactions array input fields
| Field | Type | Description |
|---|---|---|
transactionId |
String(100) | A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required. |
provider |
String(40) | Should be equal to swift, unless payment is offshore (see below) Required. Offshore Payments: These are payments made in a currency, to a country where that currency is not domiciled. For example, sending EUR to Kenya. Provider should be swift-xx where xx is the 2-digit ISO country code for the currency sent. For instance, use swift-gb for GBP. For currency zones, use any 2-digit ISO country code within the currency zone. E.g. EUR to Singapore use provider value swift-fr. Also see benIntermediaryAgent section for additional offshore payment formatting details. |
recipientAccountId |
String(35) | The recipient's bank account number. For markets which use a given bank account number standard (eg IBAN, NUBAN, etc) the bank account number must conform to that format or the payment will be rejected . Required. |
amount |
Decimal | The amount of money to transfer to the recipient. Required. |
currency |
String(3) | ISO 4217 currency code. Required. |
name |
String(105) | 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 | Information about the bank that holds the recipient's account. Required. |
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(135) | A description of the purpose of the payment. In general this will be the payment reference appearing on the beneficiary's statement. In some cases (on a per-market basis) additional regulatory transaction information must be present in this field. Consult your representative for more information. Required. |
message |
String | Unsupported. Payments containing message will be accepted but the message is not passed on. |
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(35) | The recipient’s street address or post office box number. Required. |
address2 |
String(35) | Additional information about the recipient’s street address. Recommended to be used to split longer address, given 35 char limit. |
city |
String(35) | The recipient’s city or town. Recommended to be used to split longer address, given 35 char limit. |
province |
String(35) | The recipient’s province or state. Recommended to be used to split longer address, given 35 char limit. |
postalCode |
String(31) | The recipient’s postal code. Recommended to be used to split longer address, given 35 char limit. |
country |
String(2) | The recipient’s two-letter ISO-3166-1 country code. Required. |
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 only. Contact your representative for more information. |
documentType |
String(20) | Unsupported. Supporting documentation (type and number) should be passed in the reason field. |
documentNumber |
String(50) | Unsupported. Supporting documentation (type and number) should be passed in the reason field. |
walletId |
String(100) | Which wallet to use for this payment. Be aware that wallets will be 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 | Any additional parameters related to SWIFT payments not covered by the fields above. Shouldn't be needed in most cases. |
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. |
Recipient bank input fields
recipientBank field is a JSON object with the following fields.
| 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. Required. |
bankCode |
String(35) | Country-specific national code for the bank. This is also known as the "sort code" or "routing code". Required in addition to bic for some jurisdictions; contact your representative for more information. |
branchCode |
String(50) | Unsupported. Payments containing branchCode will be accepted but the branch code is not used. |
Sender object input fields and usage
The optional sender field is a JSON object with the following fields. Note that the sender object must be supplied if applicable. See terminology and payment flow for details.
| Field | Type | Description |
|---|---|---|
customerIdentificationNumber |
String(35) | 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(105) | The sender's full name. Required. |
address |
String(35) | 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(35) | Additional information about the sender's street address. Recommended to be used to split longer address, given 35 char limit. |
city |
String(35) | The sender's city or town. Recommended to be used to split longer address, given 35 char limit. |
province |
String(35) | The sender's province or state. Recommended to be used to split longer address, given 35 char limit. |
postalCode |
String(31) | The sender's postal code. Recommended to be used to split longer address, given 35 char limit. |
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) | Unsupported. |
documentNumber |
String(50) | Unsupported. |
Intermediary object input fields and usage
The optional intermediary field is a JSON object with the following fields. Note that the intermediary object must be supplied if applicable. See terminology and payment flow for details. Note that these types of payments must stricly be approved with your representative on a case-by-case basis before usage.
| 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. Either BIC or other descriptors (see below) required. |
partyIdentifier |
String(35) | Unique identifier for the intermediary institution. Typically their account number on the client system. Required if BIC not present. |
name |
String(35) | The intermediary institution's full name. Required if BIC not present. |
address |
String(35) | The intermediary institution's street address or post office box number. Required if BIC not present. |
address2 |
String(35) | Additional information about the intermediary institution's street address. Recommended to be used to split longer address, given 35 char limit. |
city |
String(35) | The intermediary institution's city or town. Recommended to be used to split longer address, given 35 char limit. |
province |
String(35) | The intermediary institution's province or state. Recommended to be used to split longer address, given 35 char limit. |
country |
String(2) | The intermediary institution's two-letter ISO-3166-1 country code. Required if BIC not present. |
postalCode |
String(31) | The intermediary institution's postal code. Recommended to be used to split longer address, given 35 char limit. |
swiftParams object input fields and usage
The optional swiftParams field is a JSON object with the following fields. In general, it should not be used.
| Field | Type | Description |
|---|---|---|
charges |
String(3) | SWIFT charge code to be used. May be OUR (beneficiary receives full principal), BEN (charges deducted from beneficiary's received amount), or SHA (charges shared between sender and receiver). Defaults to OUR (i.e., protects beneficiary principal) if insupplied. Using this field may cause the recipient to not receive the full amount sent. |
benIntermediaryAgent object input fields and usage
The optional benIntermediaryAgent field is a JSON object with the following fields. For offshore payments, the field should be included in the transaction data. Offshore payments are payments made in a currency, to a country where that currency is not domiciled. For example, sending EUR to Kenya.
| 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. Also see guidance on providerfor additional offshore payment formatting details. |
Market-specific requirements
Some bank payment markets have additional requirements. For specifics, contact your representative. There are 3 basic types:
Field overloading: Some markets require additional information (eg beneficiary identification number, payment invoice number, etc) to be passed in the reason field. An example of this is Saudi Arabia: payments to Saudi Arabia should contain supplementary transaction information (eg invoice number) in the reason field.
Additional fields: Some markets require additional fields to properly process the payment, such as purposeCode and bankCode. An example of this is China: Payments to China should contain a purpose of payment code, in purposeCode.
Additional validation: Some markets require data items to meet certain market-specific validation criteria. An example of this is Nigeria: payments to Nigeria must contain beneficiary account numbers in the NUBAN format.
Non-payment functionality
Not all endpoints can be used to interact with payments initiated using the SWIFT provider. In particular:
/api/cancel: Please contact us via email if you wish to cancel an in-flight SWIFT payment. Cancellation is not guaranteed and may incur charges/api/reverse: Please contact us via email if you wish to reverse a SWIFT payment which has been paid. Reversal is not guaranteed and may incur charges
Cross-currency payments
Overview
The Gateway supports sending cross-currency payments; that is, payments which are paid in one currency but debited against your account in another. The /api/pay endpoint is used to achieve this. The formatting instructions are covered there.
This works by booking an FX trade from the "source" currency into the "destination" currency. Payments are then made with the bought destination currency.
Cross-currency payments are supported only for bank payments via the swift provider.
Messaging flow
Same-currency payments are initiated by the client server and then the Payment Gateway will return status updates on the transaction. Cross-currency payments are initiated by the client server, after which the Payment Gateway will return both payment status updates and critical new attributes relating to the underlying FX trade. The client server must ensure to ingest these new attributes to enable your operations team to properly fund, reconcile, and process the payments.
Cross-currency payments proceed as:
1. Request received by the Payment Gateway. Payment(s) in status 100
2. FX trade requested, selling 'source' and buying 'destination' currency. Payment(s) in status 130 (pending FX)
3. When the FX trade is booked successfully, the payment proceeds as normal. Payment(s) in status 106 until they are fully funded, then proceeding as usual
4. At this point, callbacks and polling requests to /api/transactionstatus will return additional required information relating to the underlying FX trade. The client server must ensure to ingest this information to properly fund, reconcile, and process the payments.
Failure to book FX successfully (eg a bad request) will result in failure status 330 (failed due to FX).
Currency and amount specification
For cross-currency payments, the client must always specify two currencies (source and destination) and one amount (either source or destination). These are defined as:
Currencies
sourceCurrency: currency in which the payment will be debited to the client's accountcurrency: destination currency in which the payment will be made
Both values must always be specified for all transactions in the request. Note that all transactions in a cross-currency payment request must have the same value for sourceCurrency, and for currency.
Payment amount
sourceCurrencyAmount: amount of source currency to be sent. If this is specified, your nominated source currency account will be debited for this amount, and the recipient will receive an equivalent amount in the destination currencyamount: destination-currency amount. If this is specified, the recipient will receive this amount, and your nominated source currency account will be debited for an equivalent amount in the source currency
Only one amount may be specified. All transactions in a request must have the same amount-type specified.
Cross-currency payment operations
Value dates & funding
FX trades are booked for a future value date. The number of days until the value date is specified via field tenor in the request, though note that this is dependent on FX working days which are impacted by payment market currency holidays.
- Payments submitted with
tenorTOD will be paid today. - Payments submitted with
tenorTOM will be paid tomorrow. - Payments submitted with
tenorSPOT will be paid in 2 working days.
Clients must ensure that their funding account (in the source currency specified in the initial payment request) is fully funded on the value date, or payments will not be released.
Payments are released when they are fully funded; this may occur before the FX trade's value date if you keep additional float in your destination currency account. If you wish to ensure payments are only ever released on the FX trade's value date (even if the account has additional float), we suggest scheduling the payments using the scheduledTime field.
FX rates
The FX rate received on the trade is returned via field fxRate. Note that not every payment in the request may have the same identical apparent rate due to decimal rounding.
Clients wishing to obtain an indicative FX rate prior to executing a cross-currency payment can obtain this from our live FX rates API. Please speak with your CAB representative to find out more.
Obtaining a binding quote in advance of a cross-currency payment is not currently possible. Our FIX-protocol API can be used to achieve this for wholesale FX booking, which can be combined with our payments API. Please speak with your CAB representative to find out more.
Trade booking
All payments in a request will have a single FX trade booked to cover the total amount, buying the destination currency in exchange for selling source currency. If there is an issue in booking this trade, it will cause all payments in the request to fail.
Individual payments which fail validation checks are removed from the request, and the remainder of the request will proceed without them. For example, in a request for 10 payments to be paid in Bangladeshi Taka (BDT), debiting the client in EUR, if 1 payment has an invalid BIC, the remaining 9 payments will proceed and an FX trade will be booked to cover those 9. If you wish to reinstruct the remaining payment, it should be sent as another request. There is a chance that the rate may have changed during this time.
Bank payments via ACH provider
Payment instruction
You may need to modify payment instructions when using the ACH provider for bank payments.
The permissible character set may vary by recipient market.
Field length restrictions may vary by recipient market.
Talk to your representative for more information on the specific market(s) you are using.
Timing of payments
Some ACH schemes use daily payment cycles. These transactions are batched and settled at specific intervals, resulting in a delay between payment initiation and its actual execution. For these markets, you should be aware of relevant cutoff times as these will determine when recipients receive funds.
Other ACH schemes have instant settlement. In these markets, you will receive real-time feedback on payment status and their arrival into recipients’ accounts.
Talk to your representative for more information on the specific market(s) you are using.
Payment size limits
When using an ACH provider to instruct bank payments, you should be aware that there may be a maximum payment size limit. These limits will vary depending on the specific provider.
Talk to your representative for more information on the specific market(s) you are using.
Non-payment functionality
Not all endpoints can be used to interact with payments initiated using the ACH provider. In particular:
/api/cancel: Please contact us via email if you wish to cancel an in-flight ACH payment. Cancellation is not guaranteed and may incur charges./api/reverse: Please contact us via email if you wish to reverse an ACH payment which has been paid. Reversal is not guaranteed and may incur charges- Fx-payments: FX payments are not currently supported with ACH payments. Please contact us via email if you wish to process an FX payment.