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. Required.
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(35) 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.
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.

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(35) 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.

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 account
  • currency: 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 currency
  • amount: 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.

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.