How to send an international payment

In this tutorial, you'll learn how to

Get an estimate of the exchange rate for a cross border payment

Get a list of fields required to get a valid executable quote for the payment

Request an executable quote

Originate a payment

Deal with returned and rejected payments

Note

If you are new to International Payments we recommend you read the International Payments (cross border money movement) overview before starting this tutorial.

The tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, see the API overview page.

The tutorial uses these API endpoints

API	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 a list of 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

Before you begin

Make sure you have:

API credentials
Account number of the sending CR account
Sending account configured by CR to send International Payments
Fees configured by CR according to your signed agreement

Register the relevant webhook events

To receive the webhook events for this tutorial you need to register each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs.

A basic event object contains a list of resource identifiers used to download details on each event. An extended event object contains more details.

For this tutorial register for these webhook events:

Event Name	Description
International.Payment.Sent	Funds have been sent via a wire payment to the receivers bank.

Send an international payment from a CR account

To send a payment cross border, you must make several API calls:

Get an estimate of the fees and exchange rate.
This call gives a general idea of how much the money transfer will cost the customer. We recommend you call this endpoint but it's not required.
Determine the required fields for getting a quote for a payment to a specific country.
Depending on the country, the required information can differ. It's important to know which values you must supply for the quote call to complete without errors.
Request a quote for the exchange.
This call returns a quoteId that is required to make the actual payment. The quote is usually good for 30 seconds.
Originate the payment.
Include the quoteId to use the API to send the payment.

Note

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

To get an exchange rate estimate

Call GET /International/v1/estimates. For this call, you must supply your CR accountNumber, the desired currency of the received payment, and either amount in USD you plan to send (fromAmount) or the amount in the foreign currency you want sent (toAmount).

In this example, the account number is 2294111782, the currency is Euros (EUR), and the from amount is 10.00 USD (1000).

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

Sample request
```
1
2
3
4
curl -X GET
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
https://sandbox.crbcos.com/International/v1/estimates?request.accountNumber=2294111782&request.currency=EUR&request.fromAmount=1000
```
A successful API call returns a JSON response with the details of the estimate. This estimate is non-binding and only gives you an approximate idea of what the exchange rate will be.

In this example, we provided the fromAmount. The toAmount returned is 8.51 Euros at an exchange rate of 1.1749 USD to the Euro. In addition, you can see that a regular transaction costs 6.00 USD while a priority transaction (SWIFT) costs 9.00 USD.
Copy
Sample response
```
1
2
3
4
5
6
7
8
9
{
  "accountNumber": "2294111782",
  "currency": "eur",
  "fromAmount": 1000,
  "toAmount": 851,
  "exchangeRate": "1.1749",
  "regularTransactionFeeAmount": 600,
  "priorityTransactionFeeAmount": 900
}                    
```

To get a list of required fields for a quote

Call GET /International/v1/meta/quote-requirements. For this call, you must supply values for all possible attributes. None are optional.

In this example, we provide the following values:
- currency: EUR (Euros)
- beneficiaryCountry: fr (France)
- bankCountry: fr (France)
- entityType: Individual (what legal entity is receiving the payment)
- priority: true (use SWIFT to transfer the payment)
Copy

Sample request
```
1
https://sandbox.crbcos.com/International/v1/meta/quote-requirements?filter.currency=EUR&filter.beneficiaryCountry=fr&filter.bankCountry=fr&filter.entityType=Individual&filter.priority=true
```
A successful API call returns a JSON response with a list of required fields/attributes you must provide values for when you call POST /International/v1/quotes.

The attributes in the response are required for the quote that will have the parameters as defined in this request. The response values describe the required responses. For example, for lastName the value is ^.{1,255}, indicating that regular expression characters are permitted, up to 255 characters maximum. The bankCountry is fr, as provided in the request. Attributes regarding entities and FIs refer to the beneficiary only.
Copy

Sample response
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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": true
}
                
```

To request an international payment quote

Call POST /International/v1/quotes. For this call, you must supply values for the fields returned in the the GET /International/v1/meta/quote-requirements call.

Copy

Sample request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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,
}

A successful API call returns a JSON response with a quote ID in the id field and information about the exchange rate. You need the quote ID to make the payment. The quote is usually valid for 30 seconds.

In this example, the quote ID is db41e69f-29fa-41ea-973c-b0cf01721474.

Copy

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "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
}

To send an international payment

Call POST /International/v1/payments. For this call, you must supply the quote ID from the id field returned in the the POST /International/v1/quotes call. In this example, the quote ID is db41e69f-29fa-41ea-973c-b0cf01721474, which we received in the response. You can add a client identifier if you like.
Copy

Sample request
```
1
2
3
4
https://sandbox.crbcos.com/International/v1/payments
{
  "quoteId": "db41e69f-29fa-41ea-973c-b0cf01721474"
}
```

A successful API call returns a JSON response with the payment ID in the id field and information about the payment. In this example, the payment ID is 92086a97-fdbf-4cfb-a431-b0cf0172c999.

Copy

Sample response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{
  "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"
}

When the payment completes an international.Payment.Sent webhook event fires.

The payment ID (92086a97-fdbf-4cfb-a431-b0cf0172c999) provided in the response body of the payment origination request (id) appears in the details object of the international.Payment.Sent event.

Copy

Sample International.Payment.Sent event

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
  "id": "965a22ca-7005-4c88-b7c0-b0f1018381da",
  "eventName": "International.Payment.Sent",
  "status": "Pending",
  "partnerId": "e30bfd38-907a-45f1-b5b7-af08014c8e79",
  "createdAt": "2024-01-08T18:30:52.247-05:00",
  "resources": [
    "international/v1/payments/92086a97-fdbf-4cfb-a431-b0cf0172c999"
  ],
  "details": [
    {
      "paymentId": "92086a97-fdbf-4cfb-a431-b0cf0172c999",
      "productId": "82d5af92-b7e0-4ad7-8c19-b07c01106247",
      "quoteId": "61ed7efd-8bd4-481a-9507-b0cf0172b309",
      "fromCurrency": "usd",
      "toCurrency": "eur",
      "fromAmount": "1000",
      "toAmount": "851",
      "feeAmount": "900",
      "accountNumber": "2294111782",
      "status": "Completed",
      "reason": null,
      "clientIdentifier": null,
      "priority": "True",
      "payerEntityType": "Individual",
      "companyName": null,
      "firstName": "Sara",
      "lastName": "Kim",
      "address": "250 Kuhn Highway",
      "city": "Grover",
      "stateProvince": "NC",
      "postalCode": "28073",
      "country": "US",
      "birthDate": null
    }
  ]
}