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 if you are new to international payments we recommend you read the international payments docid\ pv8ywj6zissrmd7jzeoc2 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 basics docid\ hjr4y6ml96zuyj6trytom for this tutorial you'll need to understand these terms the tutorial uses these api endpoints api description international payments docid\ tacjkajzy5xggqjlmvd1i returns the estimated cost of sending an international payment, including the exchange rate international payments docid\ tacjkajzy5xggqjlmvd1i returns a list of country specific fields you need to submit when requesting a quote international payments docid\ tacjkajzy5xggqjlmvd1i requests an executable payment quote for sending either usd or foreign currency before actually sending funds international payments docid\ tacjkajzy5xggqjlmvd1i executes a payment quote to send funds internationally before you begin make sure you have bank rails docid\ kbym9o05dwmdjsf8k7lzi 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 banking and payments docid\ dgnysfx9f7pnesmuxnwsp 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 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 international payments docid\ tacjkajzy5xggqjlmvd1i 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 ) import you must have a value for either a fromamount or a toamount , but not both sample request 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 sample response { "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 international payments docid\ tacjkajzy5xggqjlmvd1i 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) sample request 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 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" true } to request an international payment quote call international payments docid\ tacjkajzy5xggqjlmvd1i for this call, you must supply values for the fields returned in the the get /international/v1/meta/quote requirements call 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, } 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 { "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 international payments docid\ tacjkajzy5xggqjlmvd1i 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 sample request 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 sample response { "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 sample international payment sent event { "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 } ] }