Send a Cross-Border Payment

Each currency zone has its own rules and norms for international transfers, so please see the Cross-border-playbook.pdf for each country you may be trying to send a cross-border payment to.

There are 3 steps to using the Cross-Border APIs:‍

1. Create a contact for the recipient with a Cross-Border sub-object
2. Get a quote for the destinationCurrency
3. Send the crossBorder payment within 15 minutes of the quote

Step 1: Create a cross-border contact

Before you can send a cross-border payment, you need to create a contact with a Cross-Border sub-object. If the contact already exists, you can skip to step 2.

ENDPOINT

1. POST /v1/contact

REQUEST

1. {
2.   "accountId": "{{accountId}}",
3.   "name": "CrossBorder Contact",
4.   "email": "crossborder@solidfi.com",
5.   "phone": "+18185551212",
6.   "crossBorder": {
7.     "beneficiaryType": "person",
8.     "accountNumber": "12379827892221",
9.     "accountType": "saving",
10.     "bankName": "HDFC",
11.     "bankCode": "0128",
12.     "beneficiaryRelationship": "Self",
13.     "beneficiaryIdentificationType": "Aadhaar",
14.     "beneficiaryIdentificationValue": "A12112121",
15.     "bankIdentifierType1": "ifsc",
16.     "bankIdentifierCode1": "HDFC0000128",
17.     "bankIdentifierType2": "",
18.     "bankIdentifierCode2": "",
19.     "address": {
20.       "addressType": "crossBorder",
21.       "line1": "HDFCBank",
22.       "line2": "",
23.       "city": "CHENNAI",
24.       "state": "TamilNadu",
25.       "country": "IN",
26.       "postalCode": "600002"
27.     }
28.   }
29. }

RESPONSE

1. {
2.   "id": "con-aa2c6463-566f-41b0-8a45-96009a24af58",
3.   "accountId": "acc-cdc4ca0a-2f1b-4c0b-9964-2339268c2d7b",
4.   "name": "CrossBorder Contact",
5.   "label": "CrossBorder Contact",
6.   "email": "crossborder@solidfi.com",
7.   "phone": "+18185551212",
8.   "status": "active",
9.   "type": "others",
10.   "programId": "prg-ddb08641-6565-465d-ba94-ed199497299f",
11.   "createdAt": "2022-12-11T19:41:04Z",
12.   "modifiedAt": "2022-12-11T19:41:04Z",
13.   "intrabank": null,
14.   "ach": null,
15.   "wire": null,
16.   "check": null,
17.   "card": null,
18.   "debitCard": {
19.     "cardNumber": "",
20.     "last4": "",
21.     "expiryMonth": "",
22.     "expiryYear": "",
23.     "address": null,
24.     "pull": null,
25.     "push": null,
26.     "usageType": "both"
27.   },
28.   "crossBorder": {
29.     "beneficiaryType": "person",
30.     "address": {
31.       "addressType": "crossBorder",
32.       "line1": "HDFCBank",
33.       "line2": "",
34.       "city": "CHENNAI",
35.       "state": "TamilNadu",
36.       "country": "IN",
37.       "postalCode": "600002"
38.     },
39.     "accountNumber": "93879827892221",
40.     "accountType": "saving",
41.     "bankName": "HDFC",
42.     "bankCode": "0128",
43.     "bankIdentifierType1": "ifsc",
44.     "bankIdentifierCode1": "HDFC0000128",
45.     "bankIdentifierType2": "",
46.     "bankIdentifierCode2": "",
47.     "beneficiaryRelationship": "Self",
48.     "beneficiaryIdentificationType": "Aadhaar",
49.     "beneficiaryIdentificationValue": "A12112121"
50.   },
51.   "metadata": null
52. }

‍
‍Step 2: Get a quote for the destination currency

You can request a quote by specifying the destinationCurrency and the destinationAmount.

REQUEST

1. GET /v1/send/crossborder/quote?destinationCurrency=INR&destinationAmount=100

Where:
- destinationCurrency = one of the currencies supported (ex: GBP)
- destinationAmount = amount of the destinationCurrency (ex: 100.00)

RESPONSE

1. {
2.   "id": "cbq-0f0e2331-8bb1-474b-8ac6-641566a5b14a",
3.   "sourceCurrency": "USD",
4.   "sourceAmount": "1.21",
5.   "destinationCurrency": "INR",
6.   "destinationAmount": "100.00",
7.   "conversionRate": "82.339320",
8.   "expires": "2022-12-12T17:43:11Z"
9. }

In this example: To send 100 INR, the sourceAmount is USD 1.21.
In the quote API, you also get the market price for 1 quantity, in this example, 1 USD = 82.339320 INR

Step 3: Send the cross-border payment
In Step 1, you get a quoteId that is valid for 15 minutes. You can execute the Send Cross-Border inside the 15 minutes, else it times out and you'd need to request a new quote. In the request object, pass:
- contactId
- quoteId
- source accountId
- description
- purposeCode - see list of codes here
- title

ENDPOINT

1. POST /v1/send/crossborder

REQUEST

1. {
2.   "accountId": "{{accountId}}",
3.   "contactId": "{{contactId}}",
4.   "quoteId": "{{quoteId}}",
5.   "description": "Mandatory description",
6.   "purposeCode": "IR001",
7.   "title": "Optional transaction title"
8. }

RESPONSE

1. {
2.   "id": "tra-71aa3bd2-9d62-49bc-b664-e26b78a9717a",
3.   "bankName": "HDFC",
4.   "accountId": "acc-cdc4ca0a-2f1b-4c0b-9964-2339268c2d7b",
5.   "contactId": "con-aa2c6463-566f-41b0-8a45-96009a24af58",
6.   "name": "CrossBorderContact",
7.   "accountNumber": "93879827892221",
8.   "routingNumber": "",
9.   "address": {
10.     "addressType": "crossBorder",
11.     "line1": "HDFCBank",
12.     "line2": "",
13.     "city": "CHENNAI",
14.     "state": "TamilNadu",
15.     "country": "IN",
16.     "postalCode": "600002"
17.   },
18.   "amount": "1.21",
19.   "status": "pending",
20.   "description": "Mandatory description",
21.   "txnType": "debit",
22.   "transferType": "crossBorder",
23.   "transferSubType": "originated",
24.   "createdAt": "2022-12-12T21:25:34Z",
25.   "modifiedAt": "2022-12-12T21:25:34Z",
26.   "transferredAt": "2022-12-12T21:25:34Z",
27.   "accountType": "",
28.   "iban": "",
29.   "valid": "",
30.   "parentTransferId": "",
31.   "reviewCode": "",
32.   "reviewMessage": "",
33.   "type": "",
34.   "metadata": null,
35.   "title": "Optional transaction title",
36.   "card": null,
37.   "destinationAmount": "100.00",
38.   "destinationCurrency": "INR",
39.   "purposeCode": "IR001",
40.   "bin": ""
41. }