Live delivery countries and their payment types

curl --request GET \
  --url https://api.pay.aptahq.com/v1/reference/countries \
  --header 'X-AptaPay-Signature: <api-key>'

const options = {method: 'GET', headers: {'X-AptaPay-Signature': '<api-key>'}};

fetch('https://api.pay.aptahq.com/v1/reference/countries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

Reference

Live delivery countries and their payment types

Which countries you can pay OUT to, and by what method. The payout-side country picker: each entry carries the ISO country, its name, its currency, and the methods that work there (momo, bank, eversend).

Runtime data, asked of the provider live — not a hardcoded table — so a corridor the provider added or dropped shows up here without a redeploy. Note the real asymmetries it will report: Nigeria is bank-only, Tanzania is wallet-to-wallet only.

It never fails you into an empty picker. If the provider call fails or returns nothing, the gateway falls back to its compiled-in corridor table and logs a warning — stale reference data is a degraded read, not a reason to break your UI. A successful live call is also diffed against that table and every disagreement is logged, which is how we learn a corridor changed without reading a changelog.

currency comes from the gateway’s corridor table, since the provider does not return one here; an unknown country yields "" rather than a guessed currency. For collection coverage as well as payout, and for the full matrix, use GET /v1/reference/corridors instead.

GET

/

v1

/

reference

/

countries

Live delivery countries and their payment types

curl --request GET \
  --url https://api.pay.aptahq.com/v1/reference/countries \
  --header 'X-AptaPay-Signature: <api-key>'

const options = {method: 'GET', headers: {'X-AptaPay-Signature': '<api-key>'}};

fetch('https://api.pay.aptahq.com/v1/reference/countries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

{
  "code": 200,
  "message": "OK",
  "data": "<unknown>",
  "error": {
    "code": "payout_rejected_by_provider",
    "message": "<string>",
    "terminal": true,
    "retriable": true,
    "ambiguous": true,
    "details": {}
  }
}

Authorizations

X-AptaPay-Signature

string

header

required

v1={hex HMAC-SHA256} over the ten-field canonical string. Sent alongside X-AptaPay-Key, X-AptaPay-Timestamp and X-AptaPay-Nonce — all four are required. OpenAPI can only model one header per scheme, so the other three are described in the Authentication section above.

Response

Delivery countries.

The single response envelope, used by EVERY endpoint so a consuming app parses one shape everywhere.

code

integer

required

Example:

200

message

string

required

Example:

"OK"

data

any

Present on success. Shape varies per endpoint.

error

object

Machine-readable error classification. EXACTLY ONE of terminal/retriable/ ambiguous is true. laces_api inferred this from the HTTP status and got it wrong, stranding real money twice (2026-08-15, 2026-08-16). Branch on these booleans, never on the status code:

terminal -> the provider refused. Reverse the debit and tell the user. retriable -> safe to retry with the SAME Idempotency-Key. ambiguous -> the outcome is UNKNOWN. Do NOT reverse. Poll instead.

Show child attributes