Beneficiaries

A beneficiary is defined as any legal entity to whom a client may transfer money to. There can be two types of clients defined as entities 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…

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"
      }
    ]
  },
  "address": {
    "country": "GB",
    "state": "London",
    "postalCode": "12345",
    "city": "London",
    "firstLine": "122B Baker street",
    "secondLine": null
  }
}

Create Beneficiary

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",
                    "state": "London",
                    "postalCode": "12345",
                    "city": "London",
                    "firstLine": "122B Baker street",
                    "secondLine": null
                }
            },
            "address": {
                "country": "GB",
                "state": "London",
                "postalCode": "12345",
                "city": "London",
                "firstLine": "122B Baker street",
                "secondLine": null
            },
            "bankAccounts": [{
                "country": "GB",
                "currency": "GBP",
                "accountNumber": "12345678",
                "iban": "GB12AB01234567890",
                "routingCodes": {
                    "bic": "ABCDGBBK",
                    "sort-code": "123456"
                }
            }]
        }
    },
    "connect": {},
    "metadata": {}
}
  • 2) MIGRATION :
    A beneficiary can be migrated from an external system.

Required parameters :

  • workflow.code
  • data.sourceId
  • data.beneficiary.clientId
  • 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

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,
            "identificationNumbers": null,
            "legalName": "Exatern Limited",
            "incorporationDate": null,
            "corporationType": null
        },
        "address": {
            "country": "TR",
            "state": null,
            "postalCode": "340001",
            "city": "Istanbul",
            "firstLine": "Kadıkoy",
            "secondLine": ""
        }
    },
    "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