Beneficiaries

A beneficiary is defined as a legal entity with an identity or a name to whom a client may transfer money to. Two types of identities can be 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": "individual",
    "givenName": "John",
    "fullName": "Smith",
    "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": "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 the country of an address is US, CA, or MX, the region must be sent as alpha-2 (ISO 3166-2) code of the state. For other countries, the 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": {
            "legalName": "Exatern Limited"
        }
    },
    "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

{
    "workflow": {},
    "data": {
        "beneficiaries": [
            {
                "id": "e28dc22b-e883-4279-828e-8c345d1a401f",
                "clientId": "305fb520-6680-4c10-aac4-4cc4b0b723e9",
                "identity": {
                    "type": "individual",
                    "country": null,
                    "identifications": null,
                    "givenName": "John",
                    "familyName": "Doe",
                    "birthDate": "2000-09-02"
                },
                "contact": {
                    "phone": null,
                    "email": null,
                    "address": {
                        "country": "GB",
                        "postalCode": "34840",
                        "city": "London",
                        "street": "Freedom",
                        "houseNumber": "12"
                    }
                },
                "address": {
                    "country": "GB",
                    "postalCode": "34840",
                    "city": "London",
                    "street": "Freedom",
                    "houseNumber": "12"
                },
                "title": "John Doe",
                "fullName": "John Doe"
            }
        ]
    },
    "connect": {},
    "metadata": {
        "page": {
            "size": 1,
            "number": 0,
            "totalElements": 282,
            "totalPages": 282
        }
    }
}

Get a Beneficiary

GET /beneficiaries/{beneficiaryId}

Request Parameters:

parameter	description
metadata.include	data.beneficiary.bankAccounts: Includes the beneficiary's bank accounts

{
    "workflow": {},
    "data": {
        "beneficiary": {
            "id": "2a8f4270-efcc-4f49-b2e1-b1b7f80af759",
            "clientId": "5d7e843b-e2a7-4f89-8086-ce4ed1a596cf",
            "identity": {
                "type": "individual",
                "country": "GB",
                "identifications": null,
                "givenName": "John",
                "familyName": "Doe",
                "birthDate": "2000-09-02"
            },
            "contact": {
                "phone": null,
                "email": null,
                "address": {
                    "country": "GB",
                    "city": "London",
                    "street": "London St"
                }
            },
            "address": {
                "country": "GB",
                "city": "London",
                "street": "London St"
            },
            "title": "John Doe",
            "fullName": "John Doe"
        }
    },
    "connect": {},
    "metadata": {}
}