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

Create Beneficiary

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": {}
}

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