Resolve & banks

A payout to the wrong account is the most expensive support ticket there is. POST /v1/resolve asks the provider on the corridor who holds the destination and answers with the account-holder name exactly as the provider returned it. Names are never guessed: a corridor with no name source answers is_supported false and a closed reason_code instead of an invented name.

Results are cached per merchant and environment (found names for 7 days, not-found answers for 60 minutes by default) and served with cached true. The check is advisory: a payout can still be created when the name is missing, and the provider confirms the account again at dispatch.

POST/v1/resolve

Send the destination the way you would send it on POST /v1/payouts. mobile_money needs msisdn; bank needs account_number and bank_code (codes from GET /v1/banks). bank_transfer is accepted as an alias of bank and normalised, never echoed. Not a money endpoint: no Idempotency-Key.

Headers

• AuthorizationBearer sk_test_... or sk_live_.... The key needs the payouts:read or payouts:write scope (a collections-only key is refused with insufficient_scope).
• Content-Typeapplication/json

Request body

Example request

curl -X POST https://api.capayglobal.com/v1/resolve \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CM",
    "method": "mobile_money",
    "currency": "XAF",
    "msisdn": "+237650000001"
  }'

Example response

{
  "status": "success",
  "data": {
    "object": "resolution",
    "country": "CM",
    "method": "mobile_money",
    "currency": "XAF",
    "destination": {
      "msisdn": "+237650000001",
      "account_number": null,
      "bank_code": null,
      "bank_name": null
    },
    "is_supported": true,
    "found": true,
    "account_name": "JANE DOE",
    "display_name": "J. DOE",
    "active": true,
    "source": "simulator",
    "source_kind": "simulator",
    "cached": false,
    "resolved_at": "2026-09-04T10:00:00.000Z",
    "expires_at": "2026-09-11T10:00:00.000Z",
    "reason_code": null,
    "payout_available": true,
    "livemode": false
  },
  "request_id": "b1e2c3d4-5f60-4a71-8b92-c0d1e2f3a4b5"
}

{
  "status": "success",
  "data": {
    "object": "resolution",
    "country": "CM",
    "method": "mobile_money",
    "currency": "XAF",
    "destination": { "msisdn": "+237650000003", "account_number": null, "bank_code": null, "bank_name": null },
    "is_supported": true,
    "found": false,
    "account_name": null,
    "display_name": null,
    "active": false,
    "source": "simulator",
    "source_kind": "simulator",
    "cached": false,
    "resolved_at": "2026-09-04T10:00:00.000Z",
    "expires_at": "2026-09-04T11:00:00.000Z",
    "reason_code": "invalid_customer",
    "payout_available": true,
    "livemode": false
  },
  "request_id": "c2d3e4f5-6a71-4b82-9c03-d1e2f3a4b5c6"
}

{
  "status": "success",
  "data": {
    "object": "resolution",
    "country": "KE",
    "method": "bank",
    "currency": "KES",
    "destination": { "msisdn": null, "account_number": "0123456789", "bank_code": "KE-SIM-001", "bank_name": null },
    "is_supported": false,
    "found": false,
    "account_name": null,
    "display_name": null,
    "active": null,
    "source": null,
    "source_kind": null,
    "cached": false,
    "resolved_at": "2026-09-04T10:00:00.000Z",
    "expires_at": null,
    "reason_code": "resolve_unsupported",
    "payout_available": false,
    "livemode": true
  },
  "request_id": "d3e4f5a6-7b82-4c93-8d04-e1f2a3b4c5d6"
}

curl -X POST https://api.capayglobal.com/v1/resolve \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "method": "bank",
    "currency": "NGN",
    "account_number": "0000000002",
    "bank_code": "058"
  }'

Every state below is a 200 with the same object; read is_supported, found, active and reason_code together.

• foundis_supported true, found true, account_name set, display_name masked (J. DOE), reason_code null.
• not foundis_supported true, found false, reason_code invalid_customer: the destination is not registered with the operator. Cached for a short time so a typo is cheap to retry.
• active onlyis_supported true, found false, active true, source_kind active_check: the account exists but the operator shares no name (MTN without the KYC entitlement).
• unsupportedis_supported false, source null, reason_code resolve_unsupported: no provider on this corridor confirms names yet, or no bank list is loaded for the country.
• source downHTTP 503 provider_unavailable: every name source for the corridor is temporarily unavailable. Retry with backoff; the payout itself can still be created.

Returned by POST /v1/resolve. The provider payload behind it is never exposed.

On top of the app quota, every key has its own resolve budget: 30 calls per minute and 2,000 per day by default. A denied call answers 429 rate_limited with Retry-After and X-RateLimit-Resolve-Remaining: 0; successful calls carry the remaining per-minute budget in X-RateLimit-Resolve-Remaining. Cache resolved names on your side: the answer is stable for the whole cache window.

The limiter fails closed. If the platform cannot meter a call it answers 500 internal_error rather than serve a name unmetered; retry shortly.

GET/v1/banks

GET /v1/banks?country=NG returns the codes to send as bank_code. Reference data: no scope beyond a valid key. Production keys only see lists a provider synced; sandbox keys also see the simulator’s seed banks. An empty list is honest and carries a note.

Query parameters

Example request

curl "https://api.capayglobal.com/v1/banks?country=NG" \
  -H "Authorization: Bearer sk_test_8fK2q0Zr41Xa"

Example response

{
  "status": "success",
  "data": {
    "object": "list",
    "country": "NG",
    "currency": "NGN",
    "count": 2,
    "source": "seed",
    "as_of": null,
    "banks": [
      { "code": "044", "name": "Access Bank", "slug": null, "type": "bank", "swift_code": null },
      { "code": "058", "name": "Guaranty Trust Bank", "slug": null, "type": "bank", "swift_code": null }
    ],
    "note": null,
    "livemode": false
  },
  "request_id": "e4f5a6b7-8c93-4da4-9e15-f2a3b4c5d6e7"
}

{
  "status": "success",
  "data": {
    "object": "list",
    "country": "KE",
    "currency": null,
    "count": 0,
    "source": null,
    "as_of": null,
    "banks": [],
    "note": "No bank list is loaded for KE yet. Resolution and bank payouts for KE open once a provider list is synced; mobile money is unaffected.",
    "livemode": true
  },
  "request_id": "f5a6b7c8-9da4-4eb5-af26-a3b4c5d6e7f8"
}

POST /v1/payouts with method bank now takes a beneficiary object: bank_code (from GET /v1/banks), account_number (6 to 20 digits) and an optional account_name, your own label for the recipient. The bank code must exist in the list for that country and environment.

When a fresh resolution exists for the destination at creation time, the payout carries it: beneficiary.verified_name and name_check.status verified. The money path itself never calls a provider for a name; without a fresh cache row name_check.status is unchecked and the provider confirms the account at dispatch.

{
  "amount": "25000",
  "currency": "NGN",
  "country": "NG",
  "method": "bank",
  "beneficiary": {
    "bank_code": "058",
    "account_number": "0000000002",
    "account_name": "John Doe"
  },
  "merchant_reference": "salary-2026-09-0042"
}

"beneficiary": {
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank",
  "account_number_last4": "0002",
  "account_name": "John Doe",
  "verified_name": "JOHN DOE"
},
"name_check": { "status": "verified", "account_name": "JOHN DOE" }

sk_test_ keys never reach a provider. The last four digits of the msisdn (mobile money) or account number (bank) pick the answer; any other suffix resolves found as SANDBOX ACCOUNT nnnn. Sandbox bank codes for NG are 058, 044, 057, 033 and 011; GH has GH-SIM-001 plus MTN, VOD and ATL; KE has KE-SIM-001.

As of 2026-09-04. Sources are governed by the platform team without a deploy; a source whose credentials are not yet stored answers is_supported false until they are.

• CM mobile moneyMTN account-holder check: active true; the name follows once the KYC entitlement is confirmed on the API user.
• NG, GH, KE bankPaystack account resolution, live once the Paystack key is stored. Until then: is_supported false.
• GH mobile moneyPaystack wallet resolution (MTN, VOD, ATL), same condition.
• Sandbox, every corridorThe simulator answers every mobile money destination and every bank code from the seed list.

Both endpoints use the standard error envelope. reason_code inside a 200 is not an error.