Create a Cross-border Request

post

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

Create a transfer with senderId and beneficiaryId.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Create a transfer with senderId and beneficiaryId. Returns senderAmount, senderCurrency, receiverCurrency, requiredDocuments and documents, with quote:null. Obtain a quote separately before charging. Nonempty requirements start at documents_required; an empty list starts at pending_charge. Creation does not collect funds. Complete supporting document review before charging. Production and sandbox both support momo and bank collections, subject to account collection availability. Source currencies KES/NGN and destination CNY are subject to route availability.

Both purpose and subPurpose are required for every new request in production and sandbox. All purposes accept the same 19 lowercase subpurpose values listed in the request schema and payment purpose guide. Missing, null, empty, or unsupported subPurpose values return 400 VALIDATION_ERROR.

See beneficiaries, supporting documents, and sandbox testing.

Use clothes_bags_shoes instead of the former clothes_bags_shoees spelling.

Body Params

senderId

string

required

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

purpose

string

enum

required

Allowed:

subPurpose

string

enum

required

Required for every purpose in production and sandbox. All purposes accept this shared 19-value list. Select the exact lowercase value describing the payment; omitted, null, empty, or unsupported values are rejected. Use clothes_bags_shoes; the former clothes_bags_shoees spelling is not accepted.

amount

number

required

Amount to collect in chargeCurrency; returned as senderAmount. Obtain a quote with the same source amount before charging.

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 and sandbox support momo and bank collections, subject to account availability. Phone number and operator are required for momo and forbidden for bank.

beneficiaryId

string

required

An active saved beneficiary belonging to your account in this environment.

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.

403Sender or beneficiary belongs to another account.

404Sender, beneficiary, or user not found, or referenced identity was deleted.

409DUPLICATE_EXTERNAL_REFERENCE.

422Unsupported payout route or document requirements unavailable for the selected route.