Create a Cross-border Request

post

https://api-v2.honeycoin.app/api/b2b/cross-border/requests

Create a transfer and receive its quote in pending_charge.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Create a transfer and receive its quote in pending_charge. This call does not collect funds. amount is in chargeCurrency. Use the returned quote amounts. Production accepts chargeDetails.method=momo; sandbox also accepts bank (see Testing Cross-border Transfers). Alipay requires an individual sender. Examples use illustrative amounts, rates and beneficiary details. Sandbox: use the same suffix under /api/sandbox/b2b/cross-border/requests with a sandbox bearer token.

Follow the cross-border guide and sandbox testing guide.

Include a required beneficiary object with type, idType, idCountry, and payoutDetails. Individual beneficiaries require idNumber; business beneficiaries require registrationNumber. Omit the other type's number field. Accepted idType values are passport, national-id, and business-registration-number.

Payout instructions now belong in beneficiary.payoutDetails. Sending only the former top-level payoutDetails does not satisfy this contract. The recipient's account holder name belongs in beneficiary.payoutDetails.payoutMethod.accountName. New request responses expose this information in data.beneficiary.

See Status, webhooks and retries for response envelopes, pagination and recovery rules.

Body Params

senderId

string

required

An active sender ID belonging to your account in this environment.

purpose

string

enum

required

Allowed:

subPurpose

string

Required for goods_payment or service_payment. Goods: clothes_bags_shoees, daily_supplies_and_cosmetics, electronics_and_home_appliances. Services: interpretation_service. Use the exact wire spelling clothes_bags_shoees.

amount

number

required

Amount to collect in chargeCurrency; this is not the CNY amount.

chargeCurrency

string

enum

required

Accepted source currencies; collection availability depends on your account and method.

Allowed:

receiverCurrency

string

enum

required

Allowed:

externalReference

string

required

Your unique reference for the request, unique within your account.

requestType

string

enum

required

Use transfer for this flow. Collection requests are not supported.

Allowed:

chargeDetails

object

required

Production new requests support mobile money. See the sandbox guide for bank charge testing.

beneficiary

required

Required recipient identity and payout instructions, supplied inside each transfer request. Individuals use idNumber; businesses use registrationNumber. The other identity-number field is forbidden. The account holder name belongs in payoutDetails.payoutMethod.accountName.

Responses

200Successful response.

202An identical request is still being processed. Wait and reconcile before retrying; no resource ID is included.

400Invalid request, bearer token, or current request state.

403CROSS_BORDER_SENDER_FORBIDDEN.

404CROSS_BORDER_SENDER_NOT_FOUND or USER_NOT_FOUND.

409DUPLICATE_EXTERNAL_REFERENCE.

422UNSUPPORTED_METHOD: Alipay requires an individual sender.