---
title: "Create a Cross-border Beneficiary"
method: POST
path: "/api/b2b/cross-border/requests/beneficiaries"
tags: ["Cross-border Requests"]
---

# Create a Cross-border Beneficiary

`POST /api/b2b/cross-border/requests/beneficiaries`

## Request

- Base URL: `https://api-v2.honeycoin.app`
- URL: `https://api-v2.honeycoin.app/api/b2b/cross-border/requests/beneficiaries`
- Auth: API key in header `Authorization`

Register recipient identity and payout instructions. accountName is derived from personal names or companyName; do not supply it. Reuse data.id as beneficiaryId. Active account numbers must be unique per account. Alipay requires an individual beneficiary.

## Request body

- union: Recipient identity and payout instructions for POST /beneficiaries. Save the returned ID; requests use beneficiaryId.
  - object
    - `type` 'individual', required
    - `idType` 'passport' | 'national-id': Type of the beneficiary identity or registration document. Required for bank payouts; not accepted for Alipay.
    - `idCountry` string: Two-letter uppercase country that issued the beneficiary identity or registration document. Required for bank payouts; not accepted for Alipay.
    - `idNumber` string: Beneficiary personal identity document number. Required for bank payouts; not accepted for Alipay.
    - `payoutDetails` union, required: Payout instructions supplied when registering a beneficiary. The service derives accountName from the recipient name.
      - object
        - `method` 'bank', required
        - `country` string, required
        - `payoutMethod` object, required
          - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
          - `code` string, required: Bank code from the bank directory for country CN.
        - `currency` 'CNY'
      - object
        - `method` 'alipay', required
        - `country` 'CN', required
        - `payoutMethod` object, required
          - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
        - `currency` 'CNY'
    - `firstName` string, required
    - `lastName` string, required
  - object
    - `type` 'business', required
    - `idType` 'business-registration-number', required: Type of the beneficiary identity or registration document.
    - `idCountry` string, required: Two-letter uppercase country that issued the beneficiary identity or registration document.
    - `registrationNumber` string, required: Beneficiary business registration number.
    - `payoutDetails` object, required: Payout instructions supplied when registering a beneficiary. The service derives accountName from the recipient name.
      - `method` 'bank', required
      - `country` string, required
      - `payoutMethod` object, required
        - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
        - `code` string, required: Bank code from the bank directory for country CN.
      - `currency` 'CNY'
    - `companyName` string, required

## Response `200`

Successful response.

- object
  - `success` true, required
  - `data` union, required: Reusable beneficiary returned by create, get, and list endpoints.
    - object: Alipay beneficiaries created after 16 September 2026 have no identity document fields.
      - `type` 'individual', required
      - `idType` 'passport' | 'national-id': Type of the beneficiary identity or registration document. Required for bank payouts; not accepted for Alipay.
      - `idCountry` string: Two-letter uppercase country that issued the beneficiary identity or registration document. Required for bank payouts; not accepted for Alipay.
      - `idNumber` string: Beneficiary personal identity document number. Required for bank payouts; not accepted for Alipay.
      - `payoutDetails` union, required: Payout instructions supplied when registering a beneficiary. The service derives accountName from the recipient name.
        - object
          - `method` 'bank', required
          - `country` string, required
          - `payoutMethod` object, required
            - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
            - `code` string, required: Bank code from the bank directory for country CN.
            - `accountName` string: Derived from recipient names.
          - `currency` 'CNY'
        - object
          - `method` 'alipay', required
          - `country` 'CN', required
          - `payoutMethod` object, required
            - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
            - `accountName` string: Derived from recipient names.
          - `currency` 'CNY'
      - `firstName` string, required
      - `lastName` string, required
      - `id` string, required
      - `createdAt` integer, required: Unix milliseconds.
    - object
      - `type` 'business', required
      - `idType` 'business-registration-number', required: Type of the beneficiary identity or registration document.
      - `idCountry` string, required: Two-letter uppercase country that issued the beneficiary identity or registration document.
      - `registrationNumber` string, required: Beneficiary business registration number.
      - `payoutDetails` object, required: Payout instructions supplied when registering a beneficiary. The service derives accountName from the recipient name.
        - `method` 'bank', required
        - `country` string, required
        - `payoutMethod` object, required
          - `accountNumber` string, required: Beneficiary bank account number or Alipay account identifier.
          - `code` string, required: Bank code from the bank directory for country CN.
          - `accountName` string: Derived from recipient names.
        - `currency` 'CNY'
      - `companyName` string, required
      - `id` string, required
      - `createdAt` integer, required: Unix milliseconds.

## Other responses

- `400`: Invalid input.
- `403`: Resource belongs to another account.
- `404`: Resource not found.
- `409`: Duplicate or incompatible state.
- `422`: Missing documents or invalid lifecycle state.

## Changes

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

[Operation history](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/changes/api/b2b/cross-border/requests/beneficiaries/post.md)

---

[API](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official.md) - [All operations](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/llms.txt) - [OpenAPI document](https://skmtc.dev/honeycoin/apis/honeycoin-v3-api-official/revisions/fcb58b0ef441?raw)