Bank rails

International Payments

11min

Cross River offers a set of APIs to enable cross border money movement for International Payments.

International Payments APIs are found in the internationalmodule of our COS sandbox.

Get started with Cross River APIs.

This table presents APIs that we describe in detail.

Action

API Call

Description

GET /International/v1/estimates

Returns the estimated cost of sending an international payment, including the exchange rate

GET /International/v1/meta/quote-requirements

Returns country-specific fields you need to submit when requesting a quote

POST /International/v1/quotes

Requests an executable payment quote for sending either USD or foreign currency before actually sending funds

POST /International/v1/payments

Executes a payment quote to send funds internationally



Get exchange rate estimate

Returns an estimate of an exchange rate. The estimate shows the current foreign exchange rate, including spread and the transaction fee. Unlike a quote, no beneficiary data is required and the estimate cannot be executed.

The estimate is not saved.

IMPORTANT You must have a value for either a fromAmount or a toAmount, but not both.

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

GET
Request
Response
Query Parameters
accountNumber
required
String
Account number of the sending CR account
currency
optional
String
Currency the customer is converting funds into. 3-letter ISO currency code.
fromAmount
optional
Integer
The amount in USD to be transferred. Leave blank if you provide a toAmount.
toAmount
optional
Integer
The amount in the specified currency to be received. Leave blank if you provide a fromAmount.
conversionFeeBps
optional
Integer
Requested fee for conversion of the funds using basis points (BPS) added onto the foreign exchange rate and earned by the COS partner into their specified account. The fee is added onto the foreign exchange rate when returned in the response. A basis point is 1/100th of a percent of the funds to be transferred. Partners must be approved to use this attribute to earn conversion fees.
regularTransactionFeeAmount
optional
Integer
Requested fee taken from the sending account for regular payment, earned by the COS partner into their specified account. The regular transaction fee is added onto the platform fee to get the total transaction fee. Partners must be approved to use this attribute to earn transaction fees.
priorityTransactionFeeAmount
optional
Integer
Requested fee taken from the sending account for priority (SWIFT) payment, earned by the COS partner into their specified account. The priority transaction fee is added onto platform fee to get the total Transaction Fee. Partners must be approved to use this attribute to earn transaction fees.


Get list of required fields for quote request

Returns the country-specific fields you need to submit when requesting a quote.

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

The attributes in the response are required for the quote with the parameters defined in the request for this call (except where indicated in the table below). The values provided describe the required responses. For example, for lastName the value is ^.{1,255}, indicating that the regular expression characters are permitted, up to 255 characters maximum. The bankCountry is fr, as provided in the request.

GET
Request
Response
Query Parameters
currency
required
String
Currency the customer is converting funds into. 3-letter ISO currency code.
beneficiaryCountry
required
String
Two-letter ISO country code. For a company entity, the country where it's registered. For an individual, the country where they're based.
bankCountry
required
String
bankCountry
entityType
optional
String
Legal status of the entity, whether beneficiary or originator: - Individual - Company - The default value is individual.
priority
optional
Boolean
True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false.


Request a payment quote

Calls an executable international payment quote that returns the cost of the transfer, including any fees and the exchange rate to a foreign currency.

Many beneficiary details are conditionally optional depending on destination country. Call GET /International/v1/meta/quote-requirements for a list of specific required parameters for your quote.

You need beneficiary details to create a quote. You use the value of the id attribute in the response (the Quote ID) to originate an international transfer. Quotes are typically valid for only 30 seconds.

IMPORTANT You must have a value for either a fromAmount or a toAmount, but not both.

bankCountry is always a required field.

Other attributes may or may not be required depending on the country and other parameters.

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

POST
Request
Response
Body Parameters
currency
optional
String
Currency the customer is converting funds into. 3-letter ISO currency code.
accountNumber
required
String
Account number of the sending CR account
fromAmount
optional
Integer
The amount in USD to be transferred. Leave blank if you provide a toAmount.
toAmount
optional
Integer
The amount in the specified currency to be received. Leave blank if you provide a fromAmount.
beneficiary
optional
Object
The individual or company who gets the payment
beneficiaryFi
optional
Object
Details of the beneficiary's financial institution (where the payment goes)
priority
optional
Boolean
True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false.
conversionFeeBps
optional
Integer
Requested fee for conversion of the funds using basis points (BPS) added onto the foreign exchange rate and earned by the COS partner into their specified account. The fee is added onto the foreign exchange rate when returned in the response. A basis point is 1/100th of a percent of the funds to be transferred. Partners must be approved to use this attribute to earn conversion fees.
transactionFeeAmount
optional
Integer
The requested flat fee amount for the transaction in USD earned by the COS partner into their specified account


Originate a payment

Originates a cross border money transfer.

You must get a quote ID using the Request a payment quote call. The quote ID is returned in the id field in the response to that call.

Quote IDs submitted in request are typically only valid for 30 seconds.

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

Send an international payment
POST
Request
Response
Body Parameters
quoteId
required
String
ID in GUID format received in the response to the quote call. The quote ID is valid for a limited time, typically 30 seconds.
clientIdentifier
optional
String
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.


Associated webhook events

Event Name

Description

International.Hold.Cleared

Hold on payment cleared. Funds sent.

International.Hold.Escalated

Payment on hold and status escalated. Additional actions needed.

International.Payment.Sent

Funds sent via a wire payment to the receiver bank

International.Payment.Canceled

Payment canceled at partner request

International.Payment.Returned

Payment rejected by the receiving bank

Related topics

Tutorials

🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.



Updated 30 Sep 2024
Doc contributor
Doc contributor
Doc contributor
Did this page help you?