Cross-border Status, Webhooks and Retries

Store the sender ID, cross-border request ID, request externalReference, and each charge transaction ID separately. A request can have multiple failed charge attempts, but only one pending or successful deposit is permitted at a time.

Status lookups and identifiers

Use https://api-v2.honeycoin.app/api/b2b/cross-border/requests as {crossBorderBaseUrl}, or the corresponding sandbox base URL.

GET {crossBorderBaseUrl}/{id} expects a request ID. GET {crossBorderBaseUrl}/transactions/{id} expects a transaction ID. Neither lookup substitutes an external reference for the ID.

Request lifecycle

Transaction chargeStatus uses a separate set of lowercase values: pending, successful, and failed. A successful crossborder-deposit proves collection success only. Confirm request payout_successful to establish transfer completion.

Webhook events

Configure webhooks for the selected environment and validate webhook secrets. Acknowledge accepted deliveries promptly, process them asynchronously, and tolerate retries and delivery reordering. Use the resource lookup to reconcile stale or ambiguous updates.

The initial local charge

Initiating a charge creates a transaction with type crossborder-deposit. The transaction_created event identifies that charge using data.transactionId. Example:

{
  "event": "transaction_created",
  "data": {
    "transactionId": "charge_example_001",
    "publicKey": "ACCOUNT_PUBLIC_KEY",
    "amount": 1000,
    "currency": "KES",
    "type": "crossborder-deposit",
    "status": "pending",
    "externalReference": null
  },
  "timestamp": "2026-09-11T08:00:00.000Z"
}

The collection result arrives as transaction_updated for that same transaction:

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "charge_example_001",
    "publicKey": "ACCOUNT_PUBLIC_KEY",
    "amount": 1000,
    "currency": "KES",
    "type": "crossborder-deposit",
    "status": "successful",
    "method": "momo",
    "externalReference": null
  },
  "timestamp": "2026-09-11T08:01:00.000Z"
}

A charge transaction's external reference is not guaranteed to contain the request's external reference. Link it using the transaction ID returned at initiation, or list the request's transactions. Payout transactions use type: crossborder-payout.

The cross-border request

The crossborder_updated event carries the request ID in data.id, together with the request status and its external reference. It does not carry the charge ID in that field.

{
  "event": "crossborder_updated",
  "data": {
    "id": "request_example_001",
    "publicKey": "ACCOUNT_PUBLIC_KEY",
    "status": "payout_successful",
    "externalReference": "cny-transfer-001"
  },
  "timestamp": "2026-09-11T09:00:00.000Z"
}

The same shape is used for other request status changes, such as charge_successful or payout_failed. Read the request for its saved quote and data.beneficiary, including recipient identity and data.beneficiary.payoutDetails. Do not deduplicate all request events by request ID alone: the same ID appears in multiple status changes. Make each business effect idempotent and reconcile the current resource state before applying conflicting updates.

Retry and recovery rules

Request details cannot be edited through these endpoints. A retry uses the saved quote and collection details. If those details need changing, first establish that there is no pending or successful payment; close the unpaid request if eligible and create a new request with a new external reference.

An ineligible charge may return HTTP 400 with E-API-CBR-T.S-26 in production, or E-API-SANDBOX-CBR-CH.S-44 / E-API-SANDBOX-CBR-CH.S-52 in sandbox. State conflicts can also return 409 with CROSS_BORDER_CHARGE_IN_PROGRESS, CROSS_BORDER_REQUEST_ALREADY_CHARGED, CROSS_BORDER_REQUEST_NOT_CHARGEABLE, or CROSS_BORDER_REQUEST_CLOSED. Reconcile the saved request and transaction statuses in all these cases.

Pagination

All three list endpoints return newest records first and accept limit (1–100, default 20), after, and before. Use one cursor direction per call. Treat cursors as opaque and URL-encode them. Request the next page only when hasNext is true, using nextCursor as after; use prevCursor as before when hasPrev is true.

For request listing, status is a request lifecycle value. For transaction listing, status is a lowercase transaction chargeStatus, and externalReference filters the transaction's own reference. Request listing does not accept an externalReference filter. Preserve the same filters as you move through pages.

Example empty transaction page:

{
  "success": true,
  "data": { "transactions": [] },
  "pagination": {
    "nextCursor": null,
    "prevCursor": null,
    "hasNext": false,
    "hasPrev": false,
    "limit": 20
  }
}

Close an unpaid request

Call Close a Cross-border Request: POST {crossBorderBaseUrl}/{requestId}/close, with no body.

Closing is permitted only when the request is pending_charge, charge_initiated, or charge_failed, and it has no pending or successful deposit and no payout transaction. The status alone does not establish eligibility. Closing an active charge is rejected; this endpoint does not cancel an in-flight payment or refund collected funds.

{
  "success": true,
  "message": "Cross border request closed successfully.",
  "data": {
    "id": "request_example_001",
    "status": "closed",
    "pendingChargesClosed": 0
  }
}

An already closed request returns 409 CROSS_BORDER_REQUEST_ALREADY_CLOSED. Other lifecycle conflicts return 409 CROSS_BORDER_REQUEST_CANNOT_BE_CLOSED. Re-fetch the request before deciding the next action.