--- title: International payments slug: tutorials/api/international-payments docTags: createdAt: 2025-08-24T12:25:50.719Z --- ## What you will learn ✅ 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 ✅ Send a payment :::hint{type="info"} If you are new to International Payments we recommend you read [International payments](docId:3EvRgfMqC_15mbLV_j3cp) before starting this tutorial. This tutorial assumes you have a knowledge of APIs and how they work. For more information on sending API calls, refer to [API basics](docId\:zg9CjGPbh9nMHCoit5W3a). ::: The tutorial uses these API endpoints: | API | Description | | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [GET /international/v1/estimates](docId:13BVdESRAI7mGFGTl8FjF) | Returns the estimated cost of sending an international payment, including the exchange rate | | [GET /international/v1/meta/quote-requirements](docId\:tFujxIwREvywNETqogCv-) | Returns a list of country-specific fields you need to submit when requesting a quote | | [POST /international/v1/quotes](docId\:OnbkGeBIHVb4ihvB1haKL) | Requests an executable payment quote for sending either USD or foreign currency before actually sending funds | | [POST /international/v1/payments ](docId\:eVBwhQlRGZlamLd2hRwVd) | Executes a payment quote to send funds internationally | ## Before you begin Make sure you have: - [API credentials](docId\:wmg-1Fqwq3bj-D3c3HFfs) - Account number of the sending Cross River account - Sending account configured by Cross River to send International Payments - Fees configured by Cross River according to your signed agreement - [Registered](docId\:BN5XtgkJogBe-CtwomCbS) the following webhook event: | Event Name | Description | | ---------------------------- | -------------------------------------------------------------- | | `International.Payment.Sent` | Funds have been sent via a wire payment to the receivers bank. | ## Send an international payment from a Cross River account To send a payment cross border, you must make several API calls: 1. **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. 2. **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. 3. **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 60 seconds. For additional important details refer to [Step 3 on the Send payment page.](docId\:v6X5yKUfI7SEu3gHP7pKW) 4. **Originate the payment**. Include the `quoteId` to use the API to send the payment. :::hint{type="info"} 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 :::::WorkflowBlock ::::WorkflowBlockItem Call the [GET /international/v1/estimates](docId:13BVdESRAI7mGFGTl8FjF) endpoint. For this call, you must supply your Cross River `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 **158560897007**, the currency is Great British Pounds (**GBP**), and the from amount is 10.00 USD (**1000**). :::hint{type="warning"} **IMPORTANT** You must have a value for either a `fromAmount` or a `toAmount`, but not both. ::: :::CodeblockTabs Sample request ```curl curl --location 'https://sandbox.crbcos.com/international/v1/estimates?accountNumber=158560897007¤cy=GBP&fromAmount=1000' \ --data '' ``` ::: :::: ::::WorkflowBlockItem 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 **7.89** GBP at an exchange rate of **0.7889** USD to the GBP. In addition, you can see that a regular transaction costs **1.29** USD while a priority transaction (SWIFT) costs **14.00** USD. :::CodeblockTabs Sample response ```json { "accountNumber": "158560897007", "currency": "gbp", "fromAmount": 1000, "toAmount": 789, "exchangeRate": "0.7889", "regularTransactionFeeAmount": 129, "priorityTransactionFeeAmount": 1400 } ``` ::: :::: ::::: ### To get a list of required fields for a quote :::::WorkflowBlock ::::WorkflowBlockItem 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`: **GBP** (Great Britain Pounds) - `beneficiaryCountry`: **US** (United States) - `bankCountryCode`: **GB** (Great Britain) - `entityType`: **Individual** (what legal entity is receiving the payment) - `priority`: If no value is supplied, the default is false meaning not via SWIFT. :::CodeblockTabs Sample request ```curl curl --location 'https://sandbox.crbcos.com/International/v1/meta/quote-requirements?filter.currency=GBP&filter.beneficiaryCountryCode=US&filter.bankCountryCode=GB&filter.entityType=Individual' \ --data '' ``` ::: :::: ::::WorkflowBlockItem 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 **^(\[^0-9]\{2,255})$**, indicating that regular expression characters are permitted, up to 255 characters maximum. The `bankCountryCode` is **GB**, as provided in the request. Attributes regarding entities and FIs refer to the beneficiary only :::CodeblockTabs Sample response ```json [ { "firstName": "^([^0-9]{2,255})$", "lastName": "^([^0-9]{2,255})$", "currency": "gbp", "address": "^.{1,255}", "city": "^.{1,255}", "postalCode": "^.{1,12}$", "countryCode": "US", "routingCodeType1": "SortCode", "routingCodeValue1": "^\\d{6}$", "bankName": "^.{1,255}", "bankCountryCode": "GB", "receiverAccountNumber": "^\\d{8}$", "entityType": "Individual", "paymentNetwork": "Regular", "priority": false } ] ``` ::: :::: ::::: ### To request an international payment quote :::::WorkflowBlock :::WorkflowBlockItem 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. For additional important details refer to [Step 3 on the Send payment page.](docId\:v6X5yKUfI7SEu3gHP7pKW) ::: ::::WorkflowBlockItem :::CodeblockTabs Sample request ```curl curl --location 'https://sandbox.crbcos.com/International/v1/quotes' \ --data '{ "currency": "gbp", "accountNumber": "158560897007", "fromAmount": "500", "toAmount": "", "beneficiary": { "firstName": "Jon", "lastName": "Smith", "fullName": "JonSmith", "birthDate": "2001-06-18T13:05:09.015Z", "address": "1 Street", "city": "Winfield", "stateProvince": "", "postalCode": "GB12345", "countryCode": "GB", "entityType": "Individual" }, "beneficiaryFi": { "bankName": "Bank UK", "bankCountryCode": "GB", "bankAddress": "1 Avenue", "bankAccountType": "Checking", "routingCodeType1": "SortCode", "routingCodeValue1": "123456789", "routingCodeType2": "aba", "routingCodeValue2": "123456789", "bicSwift": "TGCLGB99", "iban": "GB33BUKB20201555555555" }, "originator": { "entityName": "Cross River Bank", "firstName": "", "lastName": "", "fullName": "Cross River Bank", "address": "885 Teaneck Road", "city": "Teaneck", "state": "NJ", "postalCode": "07666", "countryCode": "US", "entityType": "Company", "birthDate": "2008-06-23", "identificationType": "IncorporationNumber", "identificationValue": "0400170263" }, "priority": true, "purpose": "SRV" }' ``` ::: :::: :::WorkflowBlockItem 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 valid for 60 seconds. In this example, the quote ID is **1b28600b-6fd7-4e0c-bc50-b39b007a0dc2**. ```json { "id": "1b28600b-6fd7-4e0c-bc50-b39b007a0dc2", "accountNumber": "158560897007", "currency": "gbp", "beneficiary": { "firstName": "Jon", "lastName": "Smith", "birthDate": "2001-06-18T00:00:00-04:00", "address": "1 Street", "city": "Winfield", "postalCode": "GB12345", "countryCode": "GB", "entityType": "Individual" }, "beneficiaryFi": { "bankName": "Bank UK", "bankCountryCode": "GB", "bankAddress": "1 Avenue", "bankAccountType": "Checking", "routingCodeType1": "SortCode", "routingCodeValue1": "123456789", "routingCodeType2": "ABA", "routingCodeValue2": "123456789", "bicSwift": "TGCLGB99", "iban": "GB33BUKB20201555555555" }, "originator": { "entityName": "Cross River Bank", "firstName": "", "lastName": "", "address": "885 Teaneck Road", "city": "Teaneck", "state": "NJ", "postalCode": "07666", "countryCode": "US", "entityType": "Company", "birthDate": "2008-06-23", "identificationType": "IncorporationNumber", "identificationValue": "0400170263" }, "fromAmount": 500, "toAmount": 394, "transactionFee": 100, "conversionRate": 0.7889, "estimatedDeliveryDate": "2025-11-20", "expiresAt": "2025-11-20T02:25:23.3897333-05:00", "status": "Created", "priority": true, "paymentNetwork": "Priority", "purpose": "SRV" } ``` ::: ::::: ### To send an international payment :::::WorkflowBlock ::::WorkflowBlockItem 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 **1b28600b-6fd7-4e0c-bc50-b39b007a0dc2**, which we received in the response. You can add a client identifier if you like. :::CodeblockTabs Sample request ```curl curl --location 'https://sandbox.crbcos.com/International/v1/payments' \ --data '{ "quoteId": "1b28600b-6fd7-4e0c-bc50-b39b007a0dc2" }' ``` ::: :::: ::::WorkflowBlockItem 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 **5962aa43-a31e-42e5-950d-b39b007d67d6**. :::CodeblockTabs Sample response ```json { "id": "5962aa43-a31e-42e5-950d-b39b007d67d6", "partnerId": "19222b81-0e1e-452d-a842-b2f1011c16f3", "productId": "57146944-b145-4326-884d-b2f700ecf688", "quoteId": "1333dc9d-ec3d-40f0-8a8e-b39b007d581b", "fromCurrency": "usd", "toCurrency": "gbp", "fromAmount": 500, "toAmount": 394, "accountNumber": "158560897007", "estimatedDeliveryDate": "11/20/2025 12:00:00 AM", "originator": { "entityName": "Cross River Bank", "firstName": "", "lastName": "", "fullName": "Cross River Bank", "address": "885 Teaneck Road", "city": "Teaneck", "state": "NJ", "postalCode": "07666", "countryCode": "US", "entityType": "Company", "birthDate": "2008-06-23", "identificationType": "IncorporationNumber", "identificationValue": "0400170263" }, "beneficiary": { "firstName": "Jon", "lastName": "Smith", "fullName": "Jon Smith", "birthDate": "2001-06-18T00:00:00-04:00", "address": "1 Street", "city": "Winfield", "postalCode": "GB12345", "countryCode": "GB", "entityType": "Individual" }, "beneficiaryFi": { "bankName": "Bank UK", "bankCountryCode": "GB", "bankAddress": "1 Avenue", "bankAccountType": "Checking", "routingCodeType1": "SortCode", "routingCodeValue1": "123456789", "routingCodeType2": "ABA", "routingCodeValue2": "123456789", "bicSwift": "TGCLGB99", "iban": "GB33BUKB20201555555555" }, "status": "Created", "purpose": "SRV", "paymentType": "Transfer", "direction": "Outbound", "priority": true, "feeAmount": 100, "feeCurrency": "usd", "source": "Api", "createdAt": "2025-11-20T02:36:35.2730121-05:00", "lastModifiedAt": "2025-11-20T02:36:35.2730121-05:00", "limitsEligibleOn": "2025-11-20T02:36:35.2730121-05:00" } ``` ::: :::: ::::WorkflowBlockItem When the payment completes an `international.Payment.Sent` webhook event fires. The payment ID (5962aa43-a31e-42e5-950d-b39b007d67d6) provided in the response body of the payment origination request (`id`) appears in the `details` object of the `international.Payment.Sent` event. :::CodeblockTabs Sample International.Payment.Sent event ```json {   "id": "41a037c3-457e-44bb-ab45-b39b007e54a0",   "eventName": "International.Payment.Sent",   "status": "Pending",   "partnerId": "19222b81-0e1e-452d-a842-b2f1011c16f3",   "createdAt": "2024-01-08T18:30:52.247-05:00",   "resources": [     "international/v1/payments/f710a42a-e03a-47b8-a415-b3050061085e"   ],   "details": [     {       "paymentId": "5962aa43-a31e-42e5-950d-b39b007d67d6",       "productId": "57146944-b145-4326-884d-b2f700ecf688",       "quoteId": "f710a42a-e03a-47b8-a415-b3050061085e",       "fromCurrency": "usd",       "toCurrency": "gbp", "fromAmount": 500, "toAmount": 394,       "feeAmount": "100",       "accountNumber": "158560897007",       "status": "Completed",       "reason": null,       "clientIdentifier": null,       "priority": "True",       "payerEntityType": "Individual",       "companyName": null,       "firstName": "Sara",       "lastName": "Kim",       "address": "250 Kuhn Highway",       "city": "Grover",       "stateProvince": "RR",       "postalCode": "28073",       "country": "GB",       "birthDate": null     }   ] } ``` ::: :::: :::::