Cross-border Beneficiaries

Create a beneficiary separately from a transfer request. Save data.id as beneficiaryId, then reuse that active beneficiary for transfers to the same recipient and account. Use the same account and environment for the sender, beneficiary, and request.

All paths below are relative to https://api-v2.honeycoin.app/api/b2b/cross-border/requests. Sandbox uses /api/sandbox/b2b/cross-border/requests on the same host.

Create a beneficiary

Call POST /beneficiaries with JSON and your bearer token.

Do not send business-only fields for individuals or individual-only fields for businesses. Identity/registration numbers and account numbers are strings, 2–200 characters. Names are 2–255 characters. idCountry is the uppercase two-letter issuing country.

Alipay example

Alipay requires an individual beneficiary and an individual sender. Its payout country must be CN. Use a real Alipay account identifier in production:

{
  "type": "individual",
  "firstName": "Example",
  "lastName": "Recipient",
  "idType": "national-id",
  "idCountry": "CN",
  "idNumber": "EXAMPLE-CN-ID-001",
  "payoutDetails": {
    "method": "alipay",
    "country": "CN",
    "payoutMethod": {
      "accountNumber": "[email protected]"
    }
  }
}

Bank example

Select the code from the bank directory; the bank must belong to the payout country. Replace the placeholder code:

{
  "type": "business",
  "companyName": "Example Supplier",
  "idType": "business-registration-number",
  "idCountry": "CN",
  "registrationNumber": "EXAMPLE-CN-REG-001",
  "payoutDetails": {
    "method": "bank",
    "country": "CN",
    "payoutMethod": {
      "accountNumber": "1234567890",
      "code": "BANK_CODE_FROM_DIRECTORY"
    }
  }
}

Do not pass payoutDetails.payoutMethod.accountName: the service derives it from firstName + lastName, or companyName. payoutDetails.currency defaults to CNY; this does not enable other receiver currencies.

The response contains success: true and the saved beneficiary in data, including id, identity, payout details, and createdAt. An active duplicate account number within your account returns 409 BENEFICIARY_ACCOUNT_IN_USE.

Read, list, and delete

Listing accepts type, limit (1–100, default 20), and either after or before. A deleted beneficiary disappears from active listings and cannot be used for a new request or charge. There is no beneficiary update endpoint in this flow. Avoid deleting beneficiaries referenced by unfinished requests.

Migration from inline beneficiaries

Move the old request's beneficiary object into POST /beneficiaries, add firstName/lastName or companyName, and remove the supplied accountName. Pass only the returned beneficiaryId when creating a request. Retrieve recipient details through GET /beneficiaries/{id}; new request responses return beneficiaryId rather than an embedded beneficiary.

See Cross-border Enums for display titles and exact identity document types.