Cross-border Transfer Overview

A transfer has two payment stages: collection and beneficiary payout. Before collection, create the request, complete any required document review, and obtain a quote for customer confirmation. Request and quote creation, uploads, and submission do not charge the customer.

flowchart TD
    A[Register or reuse sender] --> B[Register or reuse beneficiary]
    B --> C[Create request with senderId and beneficiaryId]
    C --> D{Required documents?}
    D -->|Yes| E[Upload required types]
    E --> F[Explicitly submit documents]
    F --> G{Review}
    G -->|Rejected with reason| E
    G -->|Approved| H[pending_charge]
    D -->|No| H
    H --> Q[Create quote and save quoteId]
    Q --> I[Customer confirms amounts before expiry]
    I --> J[Initiate charge with quoteId]
    J --> K{Collection result}
    K -->|Failed| L[Reconcile before eligible retry]
    L --> Q
    K -->|Successful| M[HoneyCoin processes payout]
    M --> N{Payout result}
    N -->|Successful| O[Confirm delivery]
    N -->|Failed| P[Contact support; do not recharge]

See China processing hours for Alipay availability and the bank compliance-review window.

Customer API sequence

Paths are relative to https://api-v2.honeycoin.app/api/b2b/cross-border/requests in production, or https://api-v2.honeycoin.app/api/sandbox/b2b/cross-border/requests in sandbox.

Require a purpose and a subpurpose selection before creating the request; all purposes use the same subpurpose list.

Step	API or action	Save or check
1	`POST /senders` or reuse sender	`data.id` as `senderId`
2	`POST /beneficiaries` or reuse beneficiary	`data.id` as `beneficiaryId`
3	`POST /` with both IDs, `purpose`, and `subPurpose`	Request `data.id`, source amount and currencies, `quote: null`, `requiredDocuments`, status
4	If required: multipart `POST /documents`	One file per document type; upload is not submission
5	`POST /documents/submit`	`documents_submitted`; rejection requires correction and resubmission
6	Wait for `pending_charge`, then `POST /quotes` with the request's amount and currencies	Save quote `data.id` as `quoteId`; check `expiresAt`
7	Customer confirms the quoted amounts	Obtain a fresh quote if it expires before initiation
8	`POST /charges/{requestId}` with `{ "quoteId": "QUOTE_ID" }`	Save charge `data.transactionId`; quotes are single-use
9	Track transactions and request	Collection success is separate from `payout_successful`

Production document review is handled by HoneyCoin. Sandbox customers can select documents_approved or documents_rejected through the submit call's optional outcome. Omitting it leaves the request awaiting review. The sandbox guide explains payment fixtures and recovery scenarios.

Keep sender ID, beneficiary ID, request ID, quote ID, external reference, and transaction IDs separate. Request webhooks identify the request with data.id; transaction webhooks use data.transactionId. Process duplicate and reordered events safely and fetch the resource when reconciling an uncertain result.

Continue with beneficiaries, request examples, supporting documents, and status and recovery.

Use Cross-border Enums for display titles and exact API codes for purposes, methods, document types, and statuses.