---
title: "Create Bank Beneficiary"
method: POST
path: "/beneficiaries/{parentBeneficiaryId}/bank-beneficiaries"
---

# Create Bank Beneficiary

`POST /beneficiaries/{parentBeneficiaryId}/bank-beneficiaries`

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](https://apidocs.openpayd.com/reference/get-beneficiary-required-details) API.

## Path parameters

- `parentBeneficiaryId` string, required

## Request body

- object
  - `bankAccountCurrency` string, required — The three-letter [ISO 4217](https://en.wikipedia.org/wiki/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.
  - `paymentTypes` string[], required — An array defining the types of payments the beneficiary can receive e.g. `SEPA`, `SWIFT`, `FASTER_PAYMENTS`. Must align with [Supported Payment Types](https://apidocs.openpayd.com/docs/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.
  - `beneficiaryCountry` string, required — The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code representing the country of residence or registration of the beneficiary e.g. `GB`, `DE`.
  - `bankAccountCountry` string, required — The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code representing the country where the beneficiary’s bank account is held.
  - `bankAccountType` string — Specifies the type of the beneficiary’s bank account, such as `Current` or `Savings`.
  - `bankName` string — The official name of the bank where the beneficiary’s account is maintained e.g. `HSBC UK`, `Deutsche Bank`.
  - `bankAddress` string — The full street address of the bank branch or office where the account is held.
  - `bankState` string — The state, province, or region of the bank’s address, where applicable.
  - `bankCity` string — The city or locality where the bank branch is located.
  - `bankPostalCode` string — The postal or ZIP code corresponding to the bank’s address.
  - `bankAccountHolderName` string, required — The exact name appearing on the beneficiary’s bank account. Must match the name registered with the bank to prevent payment rejection.
  - `accountNumber` string — The account number of the beneficiary’s bank account. Used for domestic payments or when IBAN is not available.
  - `bankRoutingCodes` object[] — An array containing routing or clearing codes associated with the bank account e.g. `sort code`. Used for country-specific payment routing.
    - `routingCodeKey` 'ABA' | 'BLZ_CODE' | 'BRANCH_CODE' | 'BSB_CODE' | 'SORT_CODE' | 'IFS_CODE' | 'CLABE_CODE' | 'CTN' | 'INTERMEDIARY_BIC' | 'INTERMEDIARY_ABA'
    - `routingCodeValue` string
  - `iban` string — 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`.
  - `bic` string — The SWIFT Business Identifier Code `BIC` of the beneficiary’s bank. Used for international and cross-border payment routing.
  - `companyName` string — The registered legal name of the company, required when `beneficiaryType` is `CORPORATE`. Must match official company registration documents.
  - `beneficiaryFirstName` string — The given (first) name of the individual beneficiary, required when `beneficiaryType` is `RETAIL`. Used for personal identification.
  - `beneficiaryLastName` string — The surname or family name of the individual beneficiary, required when `beneficiaryType` is `RETAIL`. Must match the name on official identification documents.
  - `beneficiaryBirthDate` string — The date of birth of the individual beneficiary, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DD`.
  - `beneficiaryAddressLine` string — The primary address line of the beneficiary’s residential or business address.
  - `beneficiaryState` string — The state, province, or region of the beneficiary’s address, where applicable.
  - `beneficiaryCity` string — The city or locality of the beneficiary’s address.
  - `beneficiaryPostalCode` string — The postal or ZIP code associated with the beneficiary’s address.
  - `phoneNumber` string — A valid telephone number for the beneficiary, including the international dialing code.
  - `friendlyName` string — 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.
  - `taxId` string — The tax identification number (TIN) or equivalent assigned to the beneficiary by local tax authorities.
  - `metadata` object — 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"
  - `intermediaryTownName` string — The town or city where the intermediary bank is located.
  - `intermediaryPostalCode` string — The postal or ZIP code of the intermediary bank’s address.
  - `intermediaryName` string — The name of the intermediary bank involved in the payment flow, if applicable. Used for payments that require routing through correspondent banks.
  - `intermediaryBankAccountCountry` string — The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the intermediary bank’s location. Used for routing payments involving correspondent institutions.

## Response `200`

200

- object
  - `id` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/openpayd/apis/openpayd-authorization.md) · [All operations](https://skmtc.net/openpayd/apis/openpayd-authorization/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openpayd/openpayd-authorization/revisions/354ac572abda/schema)