> ## Documentation Index > Fetch the complete documentation index at: https://docs.kemycard.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Beneficiary > Saves the bank account of a beneficiary for one of your customers. Only a customer with `verification_level` `verified` or `full` and status `active` can have beneficiaries. `rail` selects the kind of bank account: - **`sepa`** (default): bank account in a SEPA country, paid in EUR by SEPA Instant. The full `iban` is required and must belong to the selected `country`. `state_province` must be a `value` returned by `GET /payouts/countries` for that country. Responses only return the masked IBAN. - **`us`**: bank account in the United States, paid in USD by ACH. Send `account_type`, `account_number`, `routing_number` (9-digit ABA routing number, its check digit is verified), the bank's address (`bank_street`, `bank_city`, `bank_state`, `bank_postal_code`) and the account holder's address in the United States (`street`, `city`, `state_province`, `postal_code`). `bank_state` and `state_province` must be `value` fields returned by `GET /payouts/countries` for `US`. Responses only return the last 4 digits of the account number (`account_number_masked`). A customer can have up to **50** active beneficiaries. The same IBAN, or the same US bank account (routing number and account number), cannot be saved twice for a customer. ## OpenAPI ````yaml POST /payouts/beneficiaries openapi: 3.1.0 info: title: KemyCard API version: '1.0' description: > KemyCard API allows you to issue virtual and physical cards, manage KYC/POA verification, create crypto wallets, virtual bank accounts, purchase gift cards and send payouts to bank accounts (SEPA Instant in EUR, ACH in USD to the United States). Access depends on your plan (see [Plans and Pricing](/getting-started/plans)). The free Découverte plan gives access to virtual cards with the KYC and POA endpoints and to payouts (SEPA and ACH), within monthly limits (25 cards created and 5,000 USD loaded on cards per calendar month, 5,000 USD of payouts per calendar month), 30 requests per minute per API key, 2 allowed IP addresses and 1 active webhook endpoint. Starter, Business and Premium give access to every product with no monthly limit, 100 requests per minute per API key, 10 allowed IP addresses and 10 active webhook endpoints. Plan errors: `402 PLAN_UPGRADE_REQUIRED` (product not included in your plan), `403 PLAN_LIMIT_REACHED` (limit of your plan reached). While one of your ops balances is negative, every request other than `GET` returns `403 ACCOUNT_SUSPENDED_NEGATIVE_BALANCE`. contact: name: KemyCard API Support email: hi@kemycard.com servers: - url: https://api.kemycard.com/v1 description: Production security: - BearerAuth: [] tags: - name: Customers description: Manage your customers - name: Card Products description: Browse the card product catalog - name: Cards description: Issue and manage cards - name: KYC description: Identity verification - name: POA description: Proof of address verification - name: Wallets description: Crypto wallets - name: Virtual Accounts description: Virtual bank accounts - name: Gift Cards description: Gift card catalog and purchases - name: Payouts description: > Payouts to bank accounts: SEPA Instant in EUR (paid from your Payout SEPA balance) and ACH in USD to bank accounts in the United States (paid from your Ops Others balance) - name: Balance description: Operational balances and transaction history - name: Webhooks description: Webhook endpoints and delivery management paths: /payouts/beneficiaries: post: tags: - Payouts summary: Create a beneficiary description: > Saves the bank account of a beneficiary for one of your customers. Only a customer with `verification_level` `verified` or `full` and status `active` can have beneficiaries. `rail` selects the kind of bank account: - **`sepa`** (default): bank account in a SEPA country, paid in EUR by SEPA Instant. The full `iban` is required and must belong to the selected `country`. `state_province` must be a `value` returned by `GET /payouts/countries` for that country. Responses only return the masked IBAN. - **`us`**: bank account in the United States, paid in USD by ACH. Send `account_type`, `account_number`, `routing_number` (9-digit ABA routing number, its check digit is verified), the bank's address (`bank_street`, `bank_city`, `bank_state`, `bank_postal_code`) and the account holder's address in the United States (`street`, `city`, `state_province`, `postal_code`). `bank_state` and `state_province` must be `value` fields returned by `GET /payouts/countries` for `US`. Responses only return the last 4 digits of the account number (`account_number_masked`). A customer can have up to **50** active beneficiaries. The same IBAN, or the same US bank account (routing number and account number), cannot be saved twice for a customer. operationId: createPayoutBeneficiary requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayoutBeneficiaryRequest' examples: sepa: summary: SEPA beneficiary (EUR) value: customer_code: 019abc12-3456-7890-abcd-ef0123456789 type: individual name: JANE DOE bank_name: Test Bank iban: DE89370400440532013000 bic_swift: COBADEFFXXX street: 1 Test Street city: Berlin state_province: BE postal_code: '10115' country: DE us: summary: US beneficiary (ACH, USD) value: customer_code: 019abc12-3456-7890-abcd-ef0123456789 rail: us type: individual name: JOHN SMITH account_type: checking account_number: '123456789012' routing_number: '021000021' bank_name: Test Bank USA bank_street: 1 Bank Plaza bank_city: New York bank_state: new_york bank_postal_code: '10001' street: 10 Main Street city: Austin state_province: texas postal_code: '73301' responses: '201': description: Beneficiary created content: application/json: schema: $ref: '#/components/schemas/PayoutBeneficiarySuccessResponse' '403': $ref: '#/components/responses/AccountSuspended' '404': $ref: '#/components/responses/NotFound' '422': description: > Validation error: missing `customer_code` (`details.missing_fields`), invalid `rail` (`details.allowed`), invalid beneficiary fields (`details.fields`, one message per field), customer not active (`details.customer_status`), customer not verified (`details.required_level`, `details.customer_level`), IBAN already saved (`details.field`: `iban`), US bank account already saved (`details.field`: `account_number`) or 50 beneficiaries reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: sepa: summary: Invalid SEPA beneficiary value: success: false error: code: VALIDATION_ERROR message: Invalid beneficiary. details: fields: iban: The IBAN does not match the selected country. state_province: Please choose the region from the list. us: summary: Invalid US beneficiary value: success: false error: code: VALIDATION_ERROR message: Invalid beneficiary. details: fields: routing_number: >- The routing number (ABA) is not valid. It is the 9-digit number of the US bank. bank_state: Please choose the state from the list. postal_code: The ZIP code must have 5 digits (or 5 + 4 digits). components: schemas: CreatePayoutBeneficiaryRequest: oneOf: - $ref: '#/components/schemas/CreateSepaPayoutBeneficiaryRequest' - $ref: '#/components/schemas/CreateUsPayoutBeneficiaryRequest' PayoutBeneficiarySuccessResponse: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/PayoutBeneficiary' meta: $ref: '#/components/schemas/Meta' ErrorResponse: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string description: > Error code, for example `AUTHENTICATION_REQUIRED`, `AUTHENTICATION_FAILED`, `ACCOUNT_RESTRICTED`, `IP_NOT_ALLOWED`, `PLAN_UPGRADE_REQUIRED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_SUSPENDED_NEGATIVE_BALANCE`, `INSUFFICIENT_BALANCE`, `OPERATION_FAILED`, `FORBIDDEN`, `RESOURCE_NOT_FOUND`, `VALIDATION_ERROR`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`, `wrong_api_host`. See [Error Handling](/guides/error-handling). example: VALIDATION_ERROR message: type: string example: Missing required fields. details: type: object nullable: true meta: $ref: '#/components/schemas/Meta' CreateSepaPayoutBeneficiaryRequest: title: SEPA beneficiary (EUR) type: object required: - customer_code - name - bank_name - iban - bic_swift - street - city - state_province - postal_code - country properties: customer_code: type: string format: uuid description: Code of the customer (`verified` or `full`, status `active`) rail: type: string enum: - sepa default: sepa description: >- `sepa` (default when omitted): bank account in a SEPA country, paid in EUR type: type: string enum: - individual - business default: individual description: '`individual` for a person, `business` for a company' name: type: string maxLength: 140 description: Name of the account holder example: JANE DOE bank_name: type: string maxLength: 140 example: Test Bank iban: type: string description: Full IBAN, spaces allowed. Must belong to `country`. example: DE89370400440532013000 bic_swift: type: string example: COBADEFFXXX street: type: string maxLength: 200 example: 1 Test Street city: type: string maxLength: 100 example: Berlin state_province: type: string description: A `value` returned by `GET /payouts/countries` for this country example: BE postal_code: type: string maxLength: 20 example: '10115' country: type: string description: >- Country of the bank account (ISO 3166-1 alpha-2), one of `GET /payouts/countries` example: DE CreateUsPayoutBeneficiaryRequest: title: US beneficiary (ACH, USD) type: object required: - customer_code - rail - name - account_type - account_number - routing_number - bank_name - bank_street - bank_city - bank_state - bank_postal_code - street - city - state_province - postal_code properties: customer_code: type: string format: uuid description: Code of the customer (`verified` or `full`, status `active`) rail: type: string enum: - us description: '`us`: bank account in the United States, paid in USD by ACH' type: type: string enum: - individual - business default: individual description: '`individual` for a person, `business` for a company' name: type: string maxLength: 140 description: Name of the account holder example: JOHN SMITH account_type: type: string enum: - checking - savings example: checking account_number: type: string description: Account number, 4 to 17 digits (spaces and dashes are removed) example: '123456789012' routing_number: type: string description: >- ABA routing number of the bank, 9 digits. Its check digit is verified. example: '021000021' bank_name: type: string maxLength: 140 example: Test Bank USA bank_street: type: string maxLength: 200 description: Street address of the bank example: 1 Bank Plaza bank_city: type: string maxLength: 100 description: City of the bank example: New York bank_state: type: string description: >- State of the bank, a `value` returned by `GET /payouts/countries` for `US` example: new_york bank_postal_code: type: string description: ZIP code of the bank, 5 digits or 5 + 4 digits (`12345-6789`) example: '10001' street: type: string maxLength: 200 description: Street address of the account holder, in the United States example: 10 Main Street city: type: string maxLength: 100 description: City of the account holder example: Austin state_province: type: string description: >- State of the account holder, a `value` returned by `GET /payouts/countries` for `US` example: texas postal_code: type: string description: >- ZIP code of the account holder, 5 digits or 5 + 4 digits (`12345-6789`) example: '73301' PayoutBeneficiary: oneOf: - $ref: '#/components/schemas/SepaPayoutBeneficiary' - $ref: '#/components/schemas/UsPayoutBeneficiary' Meta: type: object properties: request_id: type: string example: a4f8e2c1b3d97056 mode: type: string enum: - test - live example: test timestamp: type: string format: date-time SepaPayoutBeneficiary: title: SEPA beneficiary type: object properties: code: type: string format: uuid description: Beneficiary code customer_code: type: string format: uuid type: type: string enum: - individual - business name: type: string example: JANE DOE bank_name: type: string example: Test Bank iban_masked: type: string description: Masked IBAN. The full IBAN is never returned. example: DE89 **** 3000 bic_swift: type: string example: COBADEFFXXX address: type: object properties: street: type: string example: 1 Test Street city: type: string example: Berlin state_province: type: string nullable: true example: BE postal_code: type: string example: '10115' country: type: string example: DE rail: type: string enum: - sepa example: sepa created_at: type: string format: date-time UsPayoutBeneficiary: title: US beneficiary (ACH) type: object properties: code: type: string format: uuid description: Beneficiary code customer_code: type: string format: uuid rail: type: string enum: - us example: us type: type: string enum: - individual - business name: type: string example: JOHN SMITH bank_name: type: string example: Test Bank USA account_type: type: string enum: - checking - savings example: checking account_number_masked: type: string description: >- Last 4 digits of the account number. The full account number is never returned. example: '**** 9012' routing_number: type: string example: '021000021' bank_address: type: object description: Address of the bank properties: street: type: string example: 1 Bank Plaza city: type: string example: New York state: type: string example: new_york postal_code: type: string example: '10001' country: type: string example: US address: type: object description: Address of the account holder properties: street: type: string example: 10 Main Street city: type: string example: Austin state_province: type: string example: texas postal_code: type: string example: '73301' country: type: string example: US created_at: type: string format: date-time responses: AccountSuspended: description: >- One of your ops balances is negative; every request other than `GET` is refused until it is topped up content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: ACCOUNT_SUSPENDED_NEGATIVE_BALANCE message: >- Your account is suspended because one of your ops balances is negative. Top up the negative balance to restore access. Read-only requests (GET) remain available. details: negative_balance_since: '2026-10-15T08:00:00+00:00' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: RESOURCE_NOT_FOUND message: Resource not found. details: null securitySchemes: BearerAuth: type: http scheme: bearer description: API key (sk_test_... or sk_live_...) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.