Cross-border Quotes

A quote gives the source amount, receiver amount, fee, and exchange rate for a cross-border charge. Request creation returns quote: null; obtain a quote separately before asking the customer to confirm payment.

Use https://api-v2.honeycoin.app/api/b2b/cross-border/requests as {crossBorderBaseUrl} in production, or https://api-v2.honeycoin.app/api/sandbox/b2b/cross-border/requests in sandbox. Send a bearer token for the selected environment and Content-Type: application/json when sending JSON.

Create a quote

Call Create a Cross-border Quote: POST {crossBorderBaseUrl}/quotes.

{
  "senderAmount": 1000,
  "senderCurrency": "KES",
  "receiverCurrency": "CNY"
}

Field	Requirement
`senderAmount`	Positive number. Match the request's `senderAmount`, originally supplied as `amount`.
`senderCurrency`	`KES` or `NGN`. Match the request's `senderCurrency`, originally supplied as `chargeCurrency`.
`receiverCurrency`	`CNY`. Match the request's receiver currency.

Currency and collection availability depend on the routes enabled for your account. A quote does not create a transfer request or initiate a payment. For a request requiring document review, obtain the quote after the request reaches pending_charge so it does not expire while review is pending.

Example response amounts are illustrative:

{
  "success": true,
  "data": {
    "id": "quote_example_001",
    "status": "active",
    "senderAmount": 1000,
    "senderCurrency": "KES",
    "receiverAmount": 49.5,
    "receiverCurrency": "CNY",
    "exchangeRate": 0.05,
    "feeAmount": 0.5,
    "feeCurrency": "CNY",
    "expiresAt": 1791198000000
  }
}

Save data.id as quoteId. Display senderAmount, receiverAmount, feeAmount, and their currencies directly. receiverAmount is the amount after the quoted fee has been deducted. Do not deduct the fee again or recompute the receiver amount from exchangeRate.

Check a quote

Call Get a Cross-border Quote: GET {crossBorderBaseUrl}/quotes/{id}, using the quote ID. The response includes the quote fields above, requestId (null until the quote is consumed), and createdAt in Unix milliseconds.

Quote `status`	Meaning
`active`	The quote has not been consumed. Check `expiresAt` separately before using it.
`consumed`	The quote has been used for a charge attempt and cannot be reused. `requestId` identifies its request.

expiresAt is a Unix timestamp in milliseconds. Use the returned timestamp rather than assuming a fixed validity period. An active quote whose expiry has passed is unusable. Quote expiry does not confirm that a payment failed or cancel a charge that has already been initiated; continue tracking that transaction.

Use the confirmed quote

After the customer confirms the amounts, call POST {crossBorderBaseUrl}/charges/{requestId}:

{
  "quoteId": "quote_example_001"
}

Use an unexpired, unused quote from the same account and environment with the exact amount and currencies saved on the request. The request must be pending_charge or an eligible charge_failed retry, with no pending or successful deposit. Save the returned data.transactionId separately from the request and quote IDs. Read the request's data.quote for the quote used by its charge attempt.

Errors and retries

HTTP status and code	Next action
`400 VALIDATION_ERROR`	Check the quote fields, or include a nonempty `quoteId` when initiating a charge.
`404 QUOTE_NOT_FOUND`	Check the quote ID, account, and environment.
`404 REQUEST_NOT_FOUND`	Check the request ID, account, and environment.
`422 REQUEST_CLOSED`	Closed requests cannot be charged. Reconcile any existing payment before deciding whether to create another request.
`422 REQUEST_NOT_CHARGEABLE`	In production and sandbox, fetch the request and transactions. Complete required document review and charge only a `pending_charge` request or an eligible `charge_failed` retry with no pending or successful deposit.
`422 INVALID_RATE`	No usable quote was returned. Do not initiate a charge from this response. Retry quote creation later; contact support if it persists.
`422 QUOTE_MISMATCH`	Obtain a quote using the request's exact amount and currencies.
`422 QUOTE_EXPIRED`	Obtain a fresh quote and ask the customer to confirm its amounts.
`422 QUOTE_ALREADY_CONSUMED`	Reconcile the request and its transactions. Use a fresh quote only for an eligible new attempt.
`503 EXCHANGE_RATE_UNAVAILABLE`	Wait and retry quote creation.

A quote can be consumed even when the charge call returns an error or the payment later fails. After an uncertain response, fetch the request, list its transactions, and check the quote before deciding whether to retry. If a deposit is pending or successful, continue tracking it. If the request is eligible and all prior deposits failed, obtain a fresh quote, ask the customer to confirm it, and retry with the same request ID and the new quoteId.

Continue with Cross-border Transfers and status, webhooks and retries.