Beneficiaries
A beneficiary is defined as a legal entity with an identity or a name to whom a client may transfer money to. There can be two types of identities defined as beneficiaries in the IF Platform.
Individual: This type of beneficiary simply means a real person.
Corporate: This type of beneficiary means a corporate entity such as a company, charity, NGO or otherwise…
There can also be beneficiaries without an individual or corporate identity. They are represented with a full name and their type of being individual or corporate is unknown.
An example of a beneficiary object without associated bank accounts is as follows:
{
"clientId": "3f0dceb7-9727-48c9-a2dc-5a13749d8993",
"identity": {
"type": "corporate",
"legalName": "Example Technologies Limited",
"identifications": [
{
"type": "registration-number",
"identificationNumber": "12345678",
"issuingCountry": "GB",
"issueDate": "2022-01-01",
"expirationDate": "2023-01-01"
}
]
},
"contact": {
"phone": "+905551234567",
"email": "[email protected]",
"address": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
}
}
}
{
"clientId": "2319f2e5-976b-4db4-8dfc-2f23fde1f703",
"fullName": "Exatern Technologies Limited",
"contact": {
"address": {
"country": "GB",
"region": "London",
"postalCode": "12345",
"city": "London",
"street": "122B Baker street",
"houseNumber": null,
"refinement": null
}
}
}
If country of an address is US, CA or MX, region must be sent as alpha-2 (ISO 3166-2) code of the state. For other countries, region is a free text field.
Create Beneficiary
POST /beneficiaries
There are 2 different workflows to create a Beneficiary.
1. DIRECT :
A beneficiary can be created with at least one bank account (and up to three) as follows:
{
"workflow": {
"code": "direct"
},
"data": {
"beneficiary": {
"clientId": "3f0dceb7-9727-48c9-a2dc-5a13749d8993",
"identity": {
"type": "corporate",
"legalName": "Example Technologies Limited"
},
"contact": {
"phone": "+905551234567",
"email": "[email protected]",
"address": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
}
},
"bankAccounts": [
{
"country": "GB",
"currency": "GBP",
"accountNumber": "12345678",
"iban": "GB12AB01234567890",
"routingCodes": {
"bic": "ABCDGBBK",
"sort-code": "123456"
}
}
]
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "direct"
},
"data": {
"beneficiary": {
"clientId": "2319f2e5-976b-4db4-8dfc-2f23fde1f703",
"fullName": "Exatern Technologies Limited",
"contact": {
"address": {
"country": "GB",
"region": "London",
"postalCode": "12345",
"city": "London",
"street": "122B Baker street",
"houseNumber": null,
"refinement": null
}
},
"bankAccounts": [
{
"country": "GB",
"currency": "EUR",
"iban": "GB29NWBK60161331926819",
"routingCodes": {
"bic": "YAPIGBIS"
}
}
]
}
},
"connect": {},
"metadata": {}
}
2. MIGRATION :
A beneficiary can be migrated from an external system.
Required parameters :
- workflow.code --> Should be 'migration'
- data.sourceId --> Beneficiary Id of the beneficiary to migrate.
- data.beneficiary.clientId --> ClientId of the beneficiary
- connect.type
- connect.serviceProvider
{
"workflow": {
"code": "migration"
},
"data": {
"sourceId": "6099548d-78d1-4992-82e6-826204fb3d4c",
"beneficiary": {
"clientId": "68354191-b5aa-412f-9303-a467392adbc5"
}
},
"connect": {
"type": "explicit",
"serviceProvider": "railsbank"
},
"metadata": {}
}
Update Beneficiary
PATCH /beneficiaries/{beneficiaryId}
Beneficiary information can be updated via this operation. However, one must use the Beneficiary Bank Accounts operation in order to alter/edit/update Bank Account Information. Trying to change bank account information from here will result in error 4xx codes with the necessary error response information.
{
"workflow": {
"code": "direct"
},
"data": {
"identity": {
"type": "corporate",
"country": null,
"identifications": null,
"legalName": "Exatern Limited",
"incorporationDate": null,
"corporationType": null
}
},
"connect": {},
"metadata": {}
}
List Beneficiaries
GET /beneficiaries
The complete list of parameters can be found in the technical reference documentation
Request Parameters:
Parameter | Description |
---|---|
data.beneficiary.clientId | Client Id |
data.beneficiary.country | Country |
data.beneficiary.type | Legal Entity Type |
metadata.include | data.beneficiary.bankAccounts: Includes the beneficiary's bank accounts |
Updated 15 days ago