3. Recipient
Step by step of how to create a recipient in FXaaS.
📑 Summary
- Objective
- Functionalities
- Recipient Creation Flow
- Data for Creating a Recipient
- Sequence Diagram Flow
Objective
The recipient or beneficiary is the person, natural or legal, who will receive the transfer values abroad. Each recipient is linked to a specific customer, and the recipientId is a parameter required only for outbound transactions.
Functionalities
Through the recipient module, it is possible to:
Recipient Creation Flow
Before creating a recipient, it is necessary to consult the list recipient requirements, according to the country of destination and the currency desired by the customer.
Some examples of the most popular requirement fields:
- USD to the United States
| Field | Description |
|---|---|
| ACH routing number | An ACH routing number is a 9-digit, unique numeric ID assigned to each banking institution in the US. |
| Account | It is the beneficiary's account number. Usually contains 7 to 12 digits, depending on the bank. |
- GPB to the United Kingdom
| Field | Description |
|---|---|
| Swift | Swift code is the number that internationally identifies the bank. |
| IBAN | Standard bank account identification code for international transfers. |
- EUR to Ireland
| Field | Description |
|---|---|
| Swift | Swift code is the number that internationally identifies the bank. |
| IBAN | Standard bank account identification code for international transfers. |
📍 1. Data for Creating a Recipient
To create a recipient, you need to provide the required parameters:
| Field Name | Is required | Description |
|---|---|---|
| recipientName | Yes | Name of the beneficiary, individual or legal. |
| currency | Yes | The currency that will arrive at the recipient's bank account as a three-letter currency code (ISO 4217). |
| country | Yes | Country in which the recipient's bank account is located as a two-letter country code (ISO 3166-1 alpha-2). |
| bankAccount | Yes | An object with all the parameters received from the "list recipient requirements" endpoint. |
| intermediaryBank | No | The SWIFT code of the intermediary bank. |
| externalId | No | An arbitrary string that can be used to identify this customer's bank account. |
| address | Yes | An object with the beneficiary address. |
| purpose | Yes | The purpose of the transactions that will be made with this beneficiary. |
| ffc | No | Field for information such as FFC - For Further Credit or invoice number, when necessary. |
Details on the 'ffc' field
The 'ffc' field has a special feature, being able to be sent both in the recipient and in the creation of the transaction. The logic applied in the API is clear and straightforward:
- If the value is filled in the recipient and empty in the transaction, the recipient's value will be used.
- If the value is filled in both the recipient and the transaction, the transaction value will be used.
- If the value is empty in the recipient and is sent in the transaction, the transaction value is used.
Below you can see an example of a full request for creating a recipient who wants to send EUR to Ireland using an intermediary bank:
curl --request POST \
--url https://fx-sandbox.remessaonline.com.br/v1/api/customers/customerId/recipients \
--header 'Authorization: Bearer {{token}}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-token: {{x-token}}' \
--data '
{
"recipientName": "Lorem Ipsum",
"country": "IE",
"currency": "EUR",
"purpose": "FAMILY_MAINTENANCE",
"bankAccount": {
"swift": "CTTVPTPL",
"iban": "PT50019300001050386994242"
},
"address": {
"addressLine1": "addrres one",
"addressLine2": "address",
"city": "address",
"zipCode": "address",
"country": "IE"
},
"intermediaryBank": {
"bankCodeType": "SWIFT",
"bankCode": "AMXIBRDF"
},
"externalId": "ext-47001397814",
"ffc":"acc-25181746"
}
Recipient Sequence Diagram
Below is the sequence diagram that describes the beneficiary creation process in more detail:
Register recipient flow
Updated 2 months ago