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