---
title: "Create a Cross-border Request"
method: POST
path: "/api/b2b/cross-border/requests"
tags: ["Cross-border Requests"]
---

# Create a Cross-border Request

`POST /api/b2b/cross-border/requests`

## Request

- Base URL: `https://api-v2.honeycoin.app`
- URL: `https://api-v2.honeycoin.app/api/b2b/cross-border/requests`
- Auth: API key in header `Authorization`

Create a transfer with senderId and beneficiaryId. Returns senderAmount, senderCurrency, receiverCurrency, requiredDocuments and documents, with quote:null. Obtain a quote separately before charging. Nonempty document 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 support momo and bank collections, subject to account collection availability. Source currencies are KES/NGN and destination currency is CNY, subject to route availability. Both purpose and subPurpose are required for every new request; see the schema for accepted values.

## Request body

- CrossBorderCreateRequest
  - `senderId` string, required: An active sender ID belonging to your account in this environment.
  - `purpose` 'salary' | 'service_payment' | 'goods_payment' | 'family_support', required
  - `subPurpose` 'clothes_bags_shoes' | 'daily_supplies_and_cosmetics' | 'electronics_and_home_appliances' | 'toys_kids_babies' | 'interpretation_service' | 'translation_service' | 'human_resource_service' | 'estate_agency_service' | 'software_development_service' | 'web_design_or_development_service' | 'drafting_legal_service' | 'legal_related_certification_service' | 'accounting_service' | 'tax_service' | 'architectural_decoration_design_service' | 'advertising_service' | 'market_research_service' | 'exhibition_booth_service' | 'other_service', 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` 'KES' | 'NGN', required: Accepted source currencies; collection availability depends on your account and method.
  - `receiverCurrency` 'CNY', required
  - `externalReference` string, required: Your unique reference for the request, unique within your account.
  - `requestType` 'transfer', required: Use transfer for this flow. Collection requests are not supported.
  - `chargeDetails` CrossBorderChargeDetails, 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.
    - `method` 'momo' | 'bank', required
    - `firstName` string, required
    - `lastName` string, required
    - `country` string, required: Two-letter country code, uppercase.
    - `email` string, email, required
    - `phoneNumber` string: Required for momo; omit for bank. Country calling code and subscriber number, without spaces or a local leading zero.
    - `momoOperatorId` string: Required for momo, including KES; omit for bank. Select an operator available for the collection country.
  - `beneficiaryId` string, required: An active saved beneficiary belonging to your account in this environment.

## Response `200`

Successful response.

- object
  - `success` true, required
  - `data` CrossBorderRequest, required
    - `id` string, required: Cross-border request ID, distinct from a charge transaction ID.
    - `senderId` string
    - `purpose` 'salary' | 'service_payment' | 'goods_payment' | 'family_support'
    - `subPurpose` string, nullable: Payment sub-purpose. Required on new requests; older records may contain null.
    - `externalReference` string
    - `requestType` string
    - `status` 'documents_required' | 'documents_submitted' | 'documents_rejected' | 'documents_approved' | 'pending_charge' | 'charge_initiated' | 'charge_successful' | 'charge_failed' | 'payout_initiated' | 'payout_successful' | 'payout_failed' | 'refund_inititated' | 'refund_successful' | 'refund_failed' | 'closed', required: Request lifecycle status. The refund-in-progress wire value is spelled refund_inititated.
    - `quote` CrossBorderQuote, required: Quote used by the request's charge attempt. The returned receiverAmount is after the quoted fee; do not calculate it from the displayed exchange rate.
      - `id` string, required: Quote ID used to initiate the charge.
      - `senderAmount` number, required
      - `senderCurrency` string, required
      - `receiverAmount` number, required
      - `receiverCurrency` string, required
      - `exchangeRate` number, required
      - `expiresAt` integer, required: Quote expiry as a Unix timestamp in milliseconds. Expiry does not cancel an initiated charge.
    - `chargeDetails` object: Saved collection details for the selected momo or bank method.
    - `senderCurrency` string
    - `receiverCurrency` string
    - `createdAt` integer: Unix milliseconds.
    - `updatedAt` integer: Unix milliseconds.
    - `beneficiaryId` string, required: An active saved beneficiary belonging to your account in this environment.
    - `requiredDocuments` CrossBorderDocumentRequirement[]: Every group is required; one alternative within each anyOf is sufficient. Empty means no documents required.
      - `anyOf` CrossBorderRequiredDocument[], required: At least one of these document types satisfies this group.
        - `type` 'proforma_invoice' | 'contract', required
        - `name` string, required
        - `description` string, required
    - `documents` CrossBorderDocument[]
      - `type` 'proforma_invoice' | 'contract', required
      - `fileId` string, required
      - `uploadedAt` integer, required: Unix milliseconds.
    - `rejectionReason` string: Review reason; interpret as current only in documents_rejected.
    - `senderAmount` number: Source amount supplied as amount on creation. Match it when obtaining a quote.

## Other responses

- `202`: An identical request is still being processed. Wait and reconcile before retrying; no resource ID is included.
- `400`: Invalid request, bearer token, or current request state.
- `403`: Sender or beneficiary belongs to another account.
- `404`: Sender, beneficiary, or user not found, or referenced identity was deleted.
- `409`: DUPLICATE_EXTERNAL_REFERENCE.
- `422`: Unsupported payout route or document requirements unavailable for the selected route.

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