--- title: "Create Bank Beneficiary" method: POST path: "/beneficiaries/{parentBeneficiaryId}/bank-beneficiaries" --- # Create Bank Beneficiary `POST /beneficiaries/{parentBeneficiaryId}/bank-beneficiaries` ## Request - Base URL: `https://sandbox.openpayd.com/api` - URL: `https://sandbox.openpayd.com/api/beneficiaries/{parentBeneficiaryId}/bank-beneficiaries` - Auth: API key in header `Authorization` 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](ref: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.
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.dev/openpayd/apis/openpayd-api.md) - [All operations](https://skmtc.dev/openpayd/apis/openpayd-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openpayd/apis/openpayd-api/revisions/0f820ef79fab?raw)