International Payments APIs
Cross River offers a set of APIs to enable cross border money movement for International Payments.
International Payments APIs are found in the international module of our COS sandbox.
Get started with Cross River APIs.
This table presents APIs that we describe in detail.
| Action |
API Call |
Description |
|---|---|---|
|
|
Returns the estimated cost of sending an international payment, including the exchange rate |
|
|
|
Returns country-specific fields you need to submit when requesting a quote |
|
|
|
Requests an executable payment quote for sending either USD or foreign currency before actually sending funds |
|
|
|
Executes a payment quote to send funds internationally |
Get an 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 in COS.
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.
Query attributes
|
accountNumber string Required Account number of the sending CR account |
|
currency string Required Currency the customer is converting funds into. 3-letter ISO currency code. |
|
fromAmount integer Conditional The amount in USD to be transferred. Leave blank if you provide a |
|
toAmount integer Conditional The amount in the specified Leave blank if you provide a |
|
conversionFeeBps integer Optional 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 integer Optional 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 integer Optional 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. |
Response attributes
|
accountNumber string Account number of the sending CR account |
|
currency string Currency the customer is converting funds into. 3-letter ISO currency code. |
|
fromAmount integer The amount in USD to be transferred. Leave blank if you provide a |
|
toAmount integer The amount in the specified Leave blank if you provide a |
|
exchangeRate string The estimated conversion rate between the dollar amount and the foreign currency |
|
regularTransactionFeeAmount 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 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. |
Sample request
https://sandbox.crbcos.com/International/v1/estimates?request.accountNumber=2294111782&request.currency=EUR&request.fromAmount=1000{
"accountNumber": "2294111782",
"currency": "eur",
"fromAmount": 1000,
"toAmount": 851,
"exchangeRate": "1.1749",
"regularTransactionFeeAmount": 600,
"priorityTransactionFeeAmount": 900
} Get a list of fields required to request a quote
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.
Query parameters
|
currency string Required Currency the customer is converting funds into. 3-letter ISO currency code. |
|
beneficiaryCountry string Required 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 string Required Two-letter code for the country where the beneficiary's bank account is held |
|
entityType string Optional Legal status of the entity, whether beneficiary or originator:
The default value is individual. |
|
priority boolean Optional True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false. |
Response attributes
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.
|
firstName string First name of the beneficiary of the funds. Required if |
|
lastName string Last name of the beneficiary of the funds. Required if |
|
companyName string Name of the beneficiary company. Required if |
|
currency string Currency the customer is converting funds into. 3-letter ISO currency code. |
|
address string Complete beneficiary street address. |
|
city string Beneficiary city. |
|
stateProvince string Beneficiary state or province |
|
postalCode string Beneficiary postal or ZIP code. |
|
countryCode 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. |
|
routingCodeType1 string Local payment routing system type. If supplied, you must also give the actual code for
|
|
routingCodeValue1 string Routing code of the routing code typeRequired if you supply a value for |
|
routingCodeType2 string Sometimes certain corridors will require 2 routing codes. In that case, use this attribute for the second code type. If supplied, you must also give the actual code for
|
|
routingCodeValue2 string Routing code of the routing code typeRequired if you supplied a value for |
|
bicSwift string BIC/SWIFT code of the beneficiary FI |
|
iban string IBAN number of the beneficiary FI |
|
bankName string Name of the beneficiary's bank |
|
bankCountry string Two-letter code for the country where the beneficiary's bank account is held |
|
bankAddress string Street address of the Beneficiary's bank |
|
bankAccountType string Beneficiary bank account type:
|
|
entityType string Legal status of the entity, whether beneficiary or originator:
The default value is individual. |
|
priority boolean True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false. |
Sample request
curl -X GET
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/International/v1/meta/quote-requirements?filter.currency=EUR&filter.beneficiaryCountry=fr&filter.bankCountry=fr&filter.entityType=Individual&filter.priority=false'Sample response
{
"firstName": "^.{1,255}",
"lastName": "^.{1,255}",
"currency": "EUR",
"address": "^.{1,255}",
"city": "^.{1,255}",
"postalCode": "^.{1,12}$",
"country": "fr",
"iban": "([A-Z0-9]\\s*){15,34}",
"bankCountry": "fr",
"bankAccountType": "Checking",
"entityType": "Individual",
"priority": false
}Request a payment quote for sending funds internationally
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.
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.
Request attributes
|
currency string Optional Currency the customer is converting funds into. 3-letter ISO currency code. |
|||||||||||
|
accountNumber string Required Account number of the sending CR account |
|||||||||||
|
fromAmount integer Conditional The amount in USD to be transferred. Leave blank if you provide a |
|||||||||||
|
toAmount integer Conditional The amount in the specified Leave blank if you provide a |
|||||||||||
|
beneficiary object Conditional The individual or company who gets the payment  child attributes
|
|||||||||||
|
beneficiaryFi object Optional Details of the beneficiary's financial institution (where the payment goes) child attributes
|
|||||||||||
|
priority boolean Optional True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false. |
|||||||||||
|
conversionFeeBps integer Optional 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 integer Optional The requested flat fee amount for the transaction in USD earned by the COS partner into their specified account |
Response attributes
|
id string The quote ID. You must use this GUID format ID when you originate a payment. |
|||||||||||
|
accountNumber string Account number of the sending CR account |
|||||||||||
|
currency string Currency the customer is converting funds into. 3-letter ISO currency code. |
|||||||||||
|
beneficiary object The individual or company who gets the payment child attributes
|
|||||||||||
|
beneficiaryFi object Details of the beneficiary's financial institution (where the payment goes) child attributes
|
|||||||||||
|
fromAmount integer The amount in USD to be transferred |
|||||||||||
|
toAmount integer The amount in the specified |
|||||||||||
|
transactionFee integer Total fee. A combination of the fee charged by CR and that earned by the requesting partner, debited from the originating account |
|||||||||||
|
conversionRate number The executable conversion rate between the dollar amount and the foreign currency. The conversion rate is typically valid for only 30 seconds. |
|||||||||||
|
expiresAt string Date and time of quote expiration. Payment must be executed by the expiration to be accepted. The date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] |
|||||||||||
|
status string Status of the quote:
|
|||||||||||
|
priority boolean True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false. |
Sample request
https://sandbox.crbcos.com/International/v1/quotes
{
"currency": "eur",
"accountNumber": "2294111782",
"fromAmount": 1000,
"toAmount": 0,
"beneficiary": {
"firstName": "Stephen",
"lastName": "Larson",
"email": "stephen.larson@gmail.com",
"birthDate": "2020-07-31",
"address": "2406 Killarney Way",
"city": "Paris",
"stateProvince": "FS",
"postalCode": "32309",
"countryCode": "FR",
"entityType": "Individual",
},
"beneficiaryFi": {
"bankName": "BNP Paribas",
"bankCountry": "fr",
"bankAddress": "20 Boulevard des Italiens Paris, France",
"bankAccountType": "Checking",
"routingCodeType1": "Aba",
"routingCodeValue1": "123456789",
"routingCodeType2": "BankCode",
"routingCodeValue2": "312322",
"bicSwift": "SMCOGB2LXXX",
"iban": "GB33BUKB20201555555555",
},
"priority": true,
}{
"id": "db41e69f-29fa-41ea-973c-b0cf01721474",
"accountNumber": "2294111782",
"currency": "eur",
"beneficiary": {
"firstName": "Stephen",
"lastName": "Larson",
"email": "stephen.larson@gmail.com",
"birthDate": "2020-07-31T00:00:00-04:00",
"address": "2406 Killarney Way",
"city": "Paris",
"stateProvince": "FS",
"postalCode": "32309",
"countryCode": "FR",
"entityType": "Individual",
},
"beneficiaryFi": {
"bankName": "BNP Paribas",
"bankCountry": "FR",
"bankAddress": "20 Boulevard des Italiens Paris, France",
"bankAccountType": "Checking",
"routingCodeType1": "Aba",
"routingCodeValue1": "123456789",
"routingCodeType2": "BankCode",
"routingCodeValue2": "312322",
"bicSwift": "SMCOGB2L",
"iban": "GB33BUKB20201555555555",
},
"fromAmount": 1000,
"toAmount": 851,
"transactionFee": 900,
"conversionRate": 1.1749,
"expiresAt": "2023-12-05T17:28:25.4296297-05:00",
"status": "Created",
"priority": true
}Originate a international 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.
Request attributes
|
quoteId string Required 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 string Optional Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes. |
|
id string Payment ID. This ID first appears as the value for this attribute in the response to the originate a payment call. This ID is in GUID format. |
|||||||||||
|
partnerId string Your ID in the CR system. This ID is in GUID format. |
|||||||||||
|
productId string ID in GUID format of your specific product type on which the account is based. Provided by CR. |
|||||||||||
|
quoteId string The ID of the quote used to execute the money transfer, found in the This ID is in GUID format. |
|||||||||||
|
fromCurrency string Currency the payment is sent in |
|||||||||||
|
toCurrency string Currency the payment is received in |
|||||||||||
|
fromAmount integer The amount in USD to be transferred |
|||||||||||
|
toAmount integer The amount in the specified |
|||||||||||
|
accountNumber string Account number of the sending CR account |
|||||||||||
|
originator object The individual or company sending the payment child attributes
|
|||||||||||
|
beneficiary object The individual or company who gets the payment child attributes
|
|||||||||||
|
beneficiaryFi object Details of the beneficiary's financial institution (where the payment goes) child attributes
|
|||||||||||
|
status string Status of the payment object
|
|||||||||||
|
reason string Reason for sending the payment |
|||||||||||
|
clientIdentifier 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. |
|||||||||||
|
paymentDate string The date and time of anticipated payment delivery, in the format: yyyy-mm-ddThh:mm:ss[.mmm]. Payment delivery times cannot be guaranteed. |
|||||||||||
|
paymentType string Tell you whether this is an original transfer or return payment:
|
|||||||||||
|
priority boolean True if the transfer is via SWIFT. Otherwise false. If you don't supply a value, the default is false. |
|||||||||||
|
feeAmount integer Transaction fee amount |
|||||||||||
|
feeCurrency string Currency used for the fee |
|||||||||||
|
source string The source of the request to send a cross border payment:
|
|||||||||||
|
canceledAt string Date and time the payment was canceled. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] |
|||||||||||
|
processedAt string Date and time the payment was processed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] |
|||||||||||
|
completedAt string Date and time the payment completed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] |
|||||||||||
|
createdAt string Date and time the payment was created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] |
|||||||||||
|
lastModifiedAt string Internal CR value. Date and time the database entry was last modified. |
Sample request
https://sandbox.crbcos.com/International/v1/payments
{
"quoteId": "db41e69f-29fa-41ea-973c-b0cf01721474"
}{
"id": "92086a97-fdbf-4cfb-a431-b0cf0172c999",
"partnerId": "6f3e87df-e1ef-4cbf-ad89-b07c010df73d",
"productId": "82d5af92-b7e0-4ad7-8c19-b07c01106247",
"quoteId": "61ed7efd-8bd4-481a-9507-b0cf0172b309",
"fromCurrency": "usd",
"toCurrency": "eur",
"fromAmount": 1000,
"toAmount": 851,
"accountNumber": "2294111782",
"originator": {
"firstName": "Sara",
"lastName": "Kim",
"address": "250 Kuhn Highway",
"city": "Grover",
"stateProvince": "NC",
"postalCode": "28073",
"countryCode": "US",
"entityType": "Individual",
},
"beneficiary": {
"firstName": "Stephen",
"lastName": "Larson",
"email": "stephen.larson@gmail.com",
"birthDate": "2020-07-31",
"address": "2406 Killarney Way",
"city": "Paris",
"stateProvince": "FS",
"postalCode": "32309",
"countryCode": "FR",
"entityType": "Individual",
},
"beneficiaryFi": {
"bankName": "BNP Paribas",
"bankCountry": "fr",
"bankAddress": "20 Boulevard des Italiens Paris, France",
"bankAccountType": "Checking",
"routingCodeType1": "Aba",
"routingCodeValue1": "123456789",
"routingCodeType2": "BankCode",
"routingCodeValue2": "312322",
"bicSwift": "SMCOGB2LXXX",
"iban": "GB33BUKB20201555555555",
},
"status": "Created",
"paymentType": "Transfer",
"priority": true,
"feeAmount": 900,
"feeCurrency": "usd",
"createdAt": "2023-12-05T17:29:59.756747-05:00",
"lastModifiedAt": "2023-12-05T17:29:59.7723955-05:00"
}
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
International Payments (cross border money movement) overview
Tutorials
How to send an international payment
