Cross-border Senders

Create a sender before creating a cross-border request. A sender describes the person or business sending the money. Supply the recipient's identity in the request's beneficiary object and their account in beneficiary.payoutDetails. Reuse the sender ID for subsequent requests by that sender.

Authenticate and choose the environment

Use bearer authentication and keep API calls on your server. Generate the token with the credentials for the selected environment.

Environment	Token endpoint	Cross-border base URL
Production	`POST https://api-v2.honeycoin.app/api/b2b/auth/generate-bearer-token`	`https://api-v2.honeycoin.app/api/b2b/cross-border/requests`
Sandbox	`POST https://api-v2.honeycoin.app/api/sandbox/b2b/auth/generate-bearer-token`	`https://api-v2.honeycoin.app/api/sandbox/b2b/cross-border/requests`

Send Authorization: Bearer YOUR_BEARER_TOKEN on every cross-border call and Content-Type: application/json when sending JSON. Create separate senders in each environment; production sender IDs cannot be reused in sandbox.

Create a sender

Call Create a Cross-border Sender: POST {crossBorderBaseUrl}/senders.

Field	Requirement
`type`	`individual` or `business`
`phoneNumber`	Required; international format with `+` and country calling code
`email`	Required; unique among active senders in your account; normalized to lowercase
`idType`	Required; `passport`, `national-id`, or `business-registration-number`
`idCountry`	Required; two-letter country that issued the identity or registration document
`idNumber`	Required for individuals; personal identity document number, 2–200 characters. Forbidden for businesses
`registrationNumber`	Required for businesses; business registration number, 2–200 characters. Forbidden for individuals
`address`	Required object containing `country`, `city`, `street1`, and `postalCode`; `street2` is optional
`firstName`, `lastName`, `birthday`	Required for individuals; omit for businesses. Birthday uses `YYYY-MM-DD`
`companyName`	Required for businesses; omit for individuals
`nationality`	Optional two-letter country code for an individual

Use two-letter uppercase country codes. Personal names allow letters, spaces, apostrophes and hyphens and must be 2–255 characters. Company names must be 2–255 characters. Address limits are 100 characters for city, 200 for each street field, and 32 for postalCode.

Choose the idType that describes the supplied document. For business registration details, use idType: business-registration-number and registrationNumber. The sender's type determines which number field to send; do not send both number fields.

Individual example

{
  "type": "individual",
  "firstName": "Amina",
  "lastName": "Otieno",
  "phoneNumber": "+254712345678",
  "email": "[email protected]",
  "idType": "passport",
  "idCountry": "KE",
  "idNumber": "EXAMPLE12345",
  "birthday": "1990-04-15",
  "nationality": "KE",
  "address": {
    "country": "KE",
    "city": "NAIROBI",
    "street1": "10 Example Street",
    "postalCode": "00100"
  }
}

The response includes the sender record in data. Save data.id as your senderId. Example values throughout these guides are illustrative.

{
  "success": true,
  "data": {
    "type": "individual",
    "firstName": "Amina",
    "lastName": "Otieno",
    "phoneNumber": "+254712345678",
    "email": "[email protected]",
    "idType": "passport",
    "idCountry": "KE",
    "idNumber": "EXAMPLE12345",
    "birthday": "1990-04-15",
    "nationality": "KE",
    "address": {
      "country": "KE",
      "city": "NAIROBI",
      "street1": "10 Example Street",
      "postalCode": "00100",
      "street2": null
    },
    "id": "sender_example_001",
    "createdAt": 1789113600000
  }
}

Business example

{
  "type": "business",
  "companyName": "Example Trading Ltd",
  "phoneNumber": "+254712345679",
  "email": "[email protected]",
  "idType": "business-registration-number",
  "idCountry": "KE",
  "address": {
    "country": "KE",
    "city": "NAIROBI",
    "street1": "10 Example Street",
    "postalCode": "00100"
  },
  "registrationNumber": "EXAMPLE67890"
}

Alipay payouts require an individual sender. Use bank beneficiary details for a business sender's CNY transfer.

Find and manage senders

Action	Endpoint	Response
List active senders	`GET {crossBorderBaseUrl}/senders`	`data.senders` and `data.pagination`
Fetch one sender	`GET {crossBorderBaseUrl}/senders/{id}`	`data`
Delete a sender	`DELETE {crossBorderBaseUrl}/senders/{id}`	`success` and `message`

Sender listing supports limit, after, and before; see pagination. There is no sender update endpoint. Check your saved sender ID or list active senders before creating another record with the same email; duplicates return 409 SENDER_EMAIL_IN_USE.

Keep a sender active until its requests finish. Deleted senders are unavailable for new requests, and charging an Alipay request checks that the sender is still active. Deleting a sender does not close or refund an existing request. If you need to correct a sender used by an active request, contact support before deleting it.

Continue with Cross-border Transfers.