---
title: "Create Beneficiary"
method: POST
path: "/v2/beneficiaries"
tags: ["Beneficiaries"]
---

# Create Beneficiary

`POST /v2/beneficiaries`

Create a new beneficiary account for payments and transfers

## Request body

- union
  - object
    - `customer_id` string, required
    - `country` string, required
    - `currency` string, required
    - `counter_party` 'FIRST_PARTY' | 'THIRD_PARTY' — Indicates whether the beneficiary is a first-party or third-party account. Optional.
    - `account_holder` union, required
      - object
        - `type` 'INDIVIDUAL', required
        - `first_name` string, required
        - `last_name` string, required
        - `email` string, email, required
        - `phone` string, required
      - object
        - `type` 'BUSINESS', required
        - `business_name` string, required
        - `email` string, email, required
        - `phone` string, required
    - `account_holder_address` object, required
      - `street_line_1` string, required
      - `street_line_2` string
      - `city` string, required
      - `state` string, required — State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13).
      - `postcode` string, required
      - `country` string, required
    - `receiver_meta_data` object, required
      - `transaction_purpose_id` integer, required
      - `transaction_purpose_remarks` string
      - `occupation_id` integer
      - `occupation_remarks` string, required
      - `relationship` 'EMPLOYEE' | 'FREELANCER' | 'GIG_WORKER' | 'AFFILIATE' | 'CUSTOMER' | 'FAMILY_MEMBER' | 'FRIEND' | 'SELF' | 'OTHER' | 'SUPPLIER' | 'VENDOR' | 'SERVICE_PROVIDER' | 'MERCHANT' | 'CONTRACTOR' | 'SUBSIDIARY' | 'PARENT_COMPANY' | 'AFFILIATE_BUSINESS' | 'BANK_ACCOUNT' | 'BROKER' | 'EXCHANGE' | 'WALLET', required
      - `relationship_remarks` string
      - `nationality` string, required
      - `govt_id_number` string
      - `govt_id_issue_date` string, date
      - `govt_id_expire_date` string, date
    - `developer_fee` object, required
      - `fixed` number, required
      - `percentage` number, required
    - `deposit_instruction` object, required
      - `currency` 'USDC', required
      - `rail` 'POLYGON', required
    - `refund_instruction` object, required
      - `wallet_address` string, required
      - `currency` 'USDC', required
      - `rail` 'POLYGON', required
    - `settlement_config` object
      - `auto_settlement` boolean, required
    - `bank_account` object, required
      - `bank_name` string, required
      - `number` string, required
      - `scheme` 'LOCAL' | 'SWIFT', required
      - `type` 'CHECKING' | 'SAVINGS' | 'CURRENT', required
    - `bank_routing` object[], required
      - `scheme` 'ACH' | 'BANK_CODE' | 'BANK_IDENTIFIER' | 'BRANCH_CODE' | 'BRANCH_IDENTIFIER' | 'BSB' | 'IBAN' | 'IFSC' | 'SWIFT' | 'TRANSIT_NUMBER' | 'WIRE', required
      - `number` union, required
        - string
        - integer
    - `bank_address` object, required
      - `street_line_1` string, required
      - `street_line_2` string
      - `city` string, required
      - `state` string, required — State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13).
      - `postcode` string, required
      - `country` string, required
  - object
    - `customer_id` string, required
    - `country` string, required
    - `currency` string, required
    - `counter_party` 'FIRST_PARTY' | 'THIRD_PARTY' — Indicates whether the beneficiary is a first-party or third-party account. Optional.
    - `account_holder` union, required
      - object
        - `type` 'INDIVIDUAL', required
        - `first_name` string, required
        - `last_name` string, required
        - `email` string, email, required
        - `phone` string, required
      - object
        - `type` 'BUSINESS', required
        - `business_name` string, required
        - `email` string, email, required
        - `phone` string, required
    - `account_holder_address` object, required
      - `street_line_1` string, required
      - `street_line_2` string
      - `city` string, required
      - `state` string, required — State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13).
      - `postcode` string, required
      - `country` string, required
    - `receiver_meta_data` object, required
      - `transaction_purpose_id` integer, required
      - `transaction_purpose_remarks` string
      - `occupation_id` integer
      - `occupation_remarks` string, required
      - `relationship` 'EMPLOYEE' | 'FREELANCER' | 'GIG_WORKER' | 'AFFILIATE' | 'CUSTOMER' | 'FAMILY_MEMBER' | 'FRIEND' | 'SELF' | 'OTHER' | 'SUPPLIER' | 'VENDOR' | 'SERVICE_PROVIDER' | 'MERCHANT' | 'CONTRACTOR' | 'SUBSIDIARY' | 'PARENT_COMPANY' | 'AFFILIATE_BUSINESS' | 'BANK_ACCOUNT' | 'BROKER' | 'EXCHANGE' | 'WALLET', required
      - `relationship_remarks` string
      - `nationality` string, required
      - `govt_id_number` string
      - `govt_id_issue_date` string, date
      - `govt_id_expire_date` string, date
    - `developer_fee` object, required
      - `fixed` number, required
      - `percentage` number, required
    - `deposit_instruction` object, required
      - `currency` 'USDC', required
      - `rail` 'POLYGON', required
    - `refund_instruction` object, required
      - `wallet_address` string, required
      - `currency` 'USDC', required
      - `rail` 'POLYGON', required
    - `settlement_config` object
      - `auto_settlement` boolean, required
    - `e_wallet` object, required
      - `scheme` string, required
      - `number` string, required

## Response `200`

Beneficiary created successfully

- object
  - `data` object
    - `id` string
    - `status` string

## Other responses

- `400` — Bad Request - Invalid input format
- `401` — Authentication failed due to invalid credentials
- `409` — Conflict - A beneficiary with the same account details already exists
- `422` — Failed due to a formatting error.

---

[API](https://skmtc.net/fin/apis/fin-com-api.md) · [All operations](https://skmtc.net/fin/apis/fin-com-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fin/fin-com-api/revisions/6e69503ee7b8/schema)