---
title: "List Cross-border Beneficiaries"
method: GET
path: "/api/b2b/cross-border/requests/beneficiaries"
tags: ["Cross-border Requests"]
---

# List Cross-border Beneficiaries

`GET /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`

List active beneficiaries, newest first, with optional type and cursor filters.

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `type` 'individual' | 'business'

## Response `200`

Successful response.

- object
  - `success` true, required
  - `data` object, required
    - `beneficiaries` CrossBorderSavedBeneficiary[], required
      - union: 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
              - …
            - object
              - …
          - `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
              - …
            - `currency` 'CNY'
          - `companyName` string, required
          - `id` string, required
          - `createdAt` integer, required: Unix milliseconds.
    - `pagination` CrossBorderPagination, required
      - `nextCursor` string, nullable, required
      - `prevCursor` string, nullable, required
      - `hasNext` boolean, required
      - `hasPrev` boolean, required
      - `limit` integer, required

## 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/get.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)