---
title: "Create Beneficiary Payment Detail"
method: POST
path: "/beneficiaries/{beneficiaryId}/payment-details"
tags: ["Beneficiaries"]
---

# Create Beneficiary Payment Detail

`POST /beneficiaries/{beneficiaryId}/payment-details`

## Request

- Base URL: `https://partner-api.getpliant.com/api`
- URL: `https://partner-api.getpliant.com/api/beneficiaries/{beneficiaryId}/payment-details`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/getpliant/apis/pliant-customer-api/docs/beneficiaries/:beneficiaryId/payment-details/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new payment detail for a beneficiary. 

Payment details contain the banking information required to process transfers to the beneficiary. You can create multiple payment details for different currencies or banking methods.

## Path parameters

- `beneficiaryId` string, uuid, required

## Request body

- object
  - `bankCountry` string, required: The country where the bank is located in ISO 3166-1 alpha-2 format (e.g., `DE` for Germany, `US` for United States).
  - `bankAccountCurrency` string, required: The currency of the bank account in ISO 4217 format. For `EUR`, `SEK`, `DKK`, `AED`, `CZK`, `HUF`, `NOK`, `PLN`, `RON` accounts, `accountDetail` must include `iban` and `bic`. For `GBP` and `USD` accounts, see `accountDetail`: local account details for `GB` and `US` banks, otherwise `iban` and `bic`.
  - `bankAccountType` 'LOCAL' | 'INTERNATIONAL', nullable: The type of bank account. The type can only be set when it makes sense in the `bankCountry` - currently only in `GB`. It will be ignored for other countries. It can be one of the following values: - `LOCAL`: A local bank account within the same country. - `INTERNATIONAL`: An international bank account for cross-border transfers.
  - `accountDetail` object, required: The account details. Which properties are required depends on the `bankAccountCurrency`, `bankCountry`, and the identifiers provided: * `bankAccountCurrency` is one of `EUR`, `SEK`, `DKK`, `AED`, `CZK`, `HUF`, `NOK`, `PLN`, `RON` → `iban` & `bic` * `bankAccountCurrency` is `GBP`: * `bankCountry` is `GB` and `sortCode` provided → `accountNumber` & `sortCode` * otherwise → `iban` & `bic` * `bankAccountCurrency` is `USD`: * `bankCountry` is `US` and `routingNumber` provided → `accountNumber` & `routingNumber` * otherwise → `iban` & `bic` Other currencies are not supported. In the future other rules may apply. `iban` cannot be combined with `accountNumber`, `sortCode`, or `routingNumber`. `sortCode` and `routingNumber` cannot both be provided.
    - `accountHolderName` string, required: The full name of the account holder.
    - `bankName` string, required: The name of the bank where the account is held.
    - `iban` string, nullable: The International Bank Account Number (IBAN) for the account. Used primarily for European bank accounts.
    - `bic` string, nullable: The Bank Identifier Code (BIC) or SWIFT code for the bank. Used for international transfers.
    - `accountNumber` string, nullable: The local bank account number. Used for UK local GBP accounts (8 digits, together with `sortCode`) and US local USD accounts (together with `routingNumber`).
    - `sortCode` string, nullable: The 6-digit sort code of the bank account. Used for UK local GBP accounts (together with `accountNumber`). Not used for US routing numbers.
    - `routingNumber` string, nullable: The 9-digit ABA routing number of the bank. It must pass the ABA checksum. Used for US local USD accounts (together with `accountNumber`). Cannot be combined with `iban` or `sortCode`.

## Response `200`

Ok

- object
  - `id` string, uuid: The unique identifier of the beneficiary payment detail.
  - `bankCountry` string: The country where the bank is located in ISO 3166-1 alpha-2 format (e.g., `DE` for Germany, `US` for United States).
  - `bankAccountCurrency` string: The currency of the bank account in ISO 4217 format. For `EUR`, `SEK`, `DKK`, `AED`, `CZK`, `HUF`, `NOK`, `PLN`, `RON` accounts, `accountDetail` must include `iban` and `bic`. For `GBP` and `USD` accounts, see `accountDetail`: local account details for `GB` and `US` banks, otherwise `iban` and `bic`.
  - `bankAccountType` 'LOCAL' | 'INTERNATIONAL', nullable: The type of bank account. The type can only be set when it makes sense in the `bankCountry` - currently only in `GB`. It will be ignored for other countries. It can be one of the following values: - `LOCAL`: A local bank account within the same country. - `INTERNATIONAL`: An international bank account for cross-border transfers.
  - `accountDetail` AccountDetail (unresolved $ref)

## Other responses

- `400` (unresolved $ref)
- `401` (unresolved $ref)
- `403` (unresolved $ref)
- `404` (unresolved $ref)
- `409` (unresolved $ref)
- `429` (unresolved $ref)
- `500` (unresolved $ref)

## Changes

- **2026-11-03** `a4fbf7d068b4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getpliant/apis/pliant-customer-api/changes/beneficiaries/:beneficiaryId/payment-details/post.md)

---

[API](https://skmtc.dev/getpliant/apis/pliant-customer-api.md) - [All operations](https://skmtc.dev/getpliant/apis/pliant-customer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpliant/apis/pliant-customer-api/revisions/a4fbf7d068b4?raw)