v1

latestOpenAPI 3.1.02026-07-26290133.2 KB

Create Bank Beneficiary

Creates a new bank beneficiary under an existing parent beneficiary. This endpoint captures the beneficiary’s bank account details, identification data, and country-specific banking information required for payments. Exact required fields can vary depending on the beneficiary’s account country and currency and can be retrieved using the Beneficiary Required Details API.

post/beneficiaries/{parentBeneficiaryId}/bank-beneficiaries

Path parameters

parentBeneficiaryIdstring required

The unique identifier (UUID) of the parent beneficiary under which this bank beneficiary will be created. Obtained from a successful Create Beneficiary request.

Request body

bankAccountCurrencystring required

The three-letter ISO 4217 currency code representing the currency in which the beneficiary’s bank account is denominated e.g. EUR, USD, GBP. Determines how payments are processed for this beneficiary.

paymentTypesstring[] required

An array defining the types of payments the beneficiary can receive e.g. SEPA, SWIFT, FASTER_PAYMENTS. Must align with Supported Payment Types for the specified currency and country.

beneficiaryType'RETAIL' | 'CORPORATE' required

Specifies whether the beneficiary is a CORPORATE (business entity) or RETAIL (individual person). Determines which related identity fields (such as company or personal name) are required.

beneficiaryCountrystring required

The two-letter ISO 3166-1 alpha-2 code representing the country of residence or registration of the beneficiary e.g. GB, DE.

bankAccountCountrystring required

The two-letter ISO 3166-1 alpha-2 country code representing the country where the beneficiary’s bank account is held.

bankAccountTypestring

Specifies the type of the beneficiary’s bank account, such as Current or Savings.

bankNamestring

The official name of the bank where the beneficiary’s account is maintained e.g. HSBC UK, Deutsche Bank.

bankAddressstring

The full street address of the bank branch or office where the account is held.

bankStatestring

The state, province, or region of the bank’s address, where applicable.

bankCitystring

The city or locality where the bank branch is located.

bankPostalCodestring

The postal or ZIP code corresponding to the bank’s address.

bankAccountHolderNamestring required

The exact name appearing on the beneficiary’s bank account. Must match the name registered with the bank to prevent payment rejection.

accountNumberstring

The account number of the beneficiary’s bank account. Used for domestic payments or when IBAN is not available.

ibanstring

The International Bank Account Number IBAN of the beneficiary’s account. Used for payments in regions where IBAN is the standard e.g. SEPA countries.

bicstring

The SWIFT Business Identifier Code BIC of the beneficiary’s bank. Used for international and cross-border payment routing.

companyNamestring

The registered legal name of the company, required when beneficiaryType is CORPORATE. Must match official company registration documents.

beneficiaryFirstNamestring

The given (first) name of the individual beneficiary, required when beneficiaryType is RETAIL. Used for personal identification.

beneficiaryLastNamestring

The surname or family name of the individual beneficiary, required when beneficiaryType is RETAIL. Must match the name on official identification documents.

beneficiaryBirthDatestring

The date of birth of the individual beneficiary, in ISO 8601 YYYY-MM-DD.

beneficiaryAddressLinestring

The primary address line of the beneficiary’s residential or business address.

beneficiaryStatestring

The state, province, or region of the beneficiary’s address, where applicable.

beneficiaryCitystring

The city or locality of the beneficiary’s address.

beneficiaryPostalCodestring

The postal or ZIP code associated with the beneficiary’s address.

phoneNumberstring

A valid telephone number for the beneficiary, including the international dialing code.

friendlyNamestring

A user-friendly label assigned to this bank beneficiary for internal display and management purposes. Used for easy identification within your dashboard or API responses.

taxIdstring

The tax identification number (TIN) or equivalent assigned to the beneficiary by local tax authorities.

metadataobject

Set of key-value pairs that you can attach to the Bank Beneficiary Object. Useful for storing additional, structured information on the Beneficairy. e.g your internal ID of your user etc.<br> e.g `"userId":"ABC1234, "userName":"Boris Johnson"

intermediaryTownNamestring

The town or city where the intermediary bank is located.

intermediaryPostalCodestring

The postal or ZIP code of the intermediary bank’s address.

intermediaryNamestring

The name of the intermediary bank involved in the payment flow, if applicable. Used for payments that require routing through correspondent banks.

intermediaryBankAccountCountrystring

The two-letter ISO 3166-1 alpha-2 country code of the intermediary bank’s location. Used for routing payments involving correspondent institutions.

Response

200

idstring

Example response

{
  "id": "51d1346e-a745-4cd0-9db9-b5bf93367ccd"
}