This page contains additional information about using specific providers 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