Cross-border Senders

Create a sender before creating a cross-border request. A sender describes the person or business sending the money. Register the recipient separately with POST /beneficiaries, then pass beneficiaryId alongside senderId on the request. 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.

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.

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.

Update a sender

Call Update a Cross-border Sender: PATCH {crossBorderBaseUrl}/senders/{id}. Send a JSON object with at least one changed field.

For example, to change an individual sender's phone number:

PATCH {crossBorderBaseUrl}/senders/sender_example_001
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/json

{"phoneNumber":"+254700111222"}

A successful update returns {"success":true,"message":"Sender updated successfully."}. Fetch the sender to read back its current details. An email change must be unique among your active senders; a duplicate returns 409 SENDER_EMAIL_IN_USE.

You cannot change type, idType, idCountry, idNumber, registrationNumber, or address through this endpoint. Fields belonging to the other sender type return 422 INVALID_UPDATE. Once any cross-border request references a sender, further updates return 403 EXISITING_PAYMENTS, including after the request has finished. Contact support if the saved identity needs correction. A different sender for future requests must use an unused email while the original remains active.

Find and manage senders

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

You can delete only a sender that has never been referenced by a cross-border request. A referenced sender returns 403 EXISITING_PAYMENTS even after its request has finished. Deleting an unused sender removes it from the active sender list; it cannot be used for a new request.

Continue with Cross-border Transfers.

See Cross-border Enums for display titles and exact identity types.