Changelog

GET /v1/currencies — currency discovery. Returns the currencies active in your environment ({ code, name, symbol, decimals }), ordered with the home market (NGN) first. Read-only — any valid key can call it; there’s no filter param. Use it to discover valid currency values instead of hard-coding a list. See Currencies.

A provisioning virtual account now returns account_number: null. While a freshly-issued customer virtual account has status: "provisioning", account_number is null (the field is still present) — do not surface or fund it. Once status becomes "active", the real number is populated. provider_ref is present throughout for correlation.

POST /v1/name-enquiry returns cleaner errors. An unresolvable or provider-edge lookup now returns a clear, merchant-facing message instead of raw upstream text. HTTP status and error codes are unchanged.

A validation rejection at create is now recoverable with the same customer_reference. On a 422 validation_failed, the failed record is rolled back (the 422 detail no longer includes customer_id). Fix the offending field and retry reusing the same customer_reference with a fresh Idempotency-Key — you no longer need a new reference. (Post-submission identity corrections — after a customer is submitted for verification — still require a new customer.)

next_action upload paths corrected to /api/v1/.... The create-response next_action steps for individual customers now point at /api/v1/customers/{id}/files and /files/attach.

phone is now required for type: individual. Omitting it returns 400 missing_field (field phone). It was previously optional but is needed for virtual-account provisioning. Presence is required; the phone format is not enforced. Business (type: business) customers are unaffected.

X-Request-Id on every response. Each response (success or error) includes a unique request id. Include it when you contact support and we can trace the exact request — method, path, status, latency, and masked request/response bodies — in our logs. API requests are retained ~13 months for troubleshooting; secrets such as your API key are never stored.

next_action / requirements on create. For type: individual customers returned as pending, the create response includes next_action: "upload_identity_document" plus a requirements object listing the upload steps. Purely additive — existing fields are unchanged.

Document upload records. Uploading an identity document (/files → /files/attach) is now recorded against the customer. No request/response shape changed.

dob, street, city, state are now required for type: individual. Omitting any returns 400 missing_field (with the field name); a malformed dob returns 400 invalid_field. These were previously optional but are mandatory for virtual-account provisioning and are not updatable after create. id_issue_date remains optional.

POST /v1/customers/{id}/files now requires content_type. Pass the MIME type of the file you’ll upload — one of image/jpeg, image/png, image/webp, image/heic, image/heif, application/pdf. It’s returned inside required_headers as Content-Type. Omitting it returns 400 missing_field; an unsupported value returns 400 invalid_field.

Identity documents now attach reliably. Previously the presigned upload’s required_headers carried no Content-Type, so an upload that echoed them verbatim was stored without a valid content type and POST /v1/customers/{id}/files/attach rejected it. The response now always includes the Content-Type for your file.

Docs clarify the byte-PUT is server-side. The signed upload_url is not browser-CORS-enabled — run step 2 from your backend. Requesting the URL and attaching the file are ordinary Bearer-authenticated calls.

Invalid filter values now return 400 instead of being silently ignored. GET /v1/beneficiaries?currency= and GET /v1/webhook_deliveries?event_type= return 400 invalid_filter on an unrecognized value, and GET /v1/reports/*?format= returns 400 unsupported_format for anything other than json / csv / xlsx. Previously an unrecognized value was dropped (returning unfiltered, or default-format, results).

GET /v1/reports/bank-statement now requires currency. A bank statement is single-currency — a running balance across mixed currencies is meaningless — so there is no default. Omitting it returns 400 missing_currency; an unrecognized value returns 400 invalid_filter. Pass one of NGN / GBP / USD / EUR / CAD. (Previously defaulted to NGN.)

Webhook endpoint URLs must be publicly reachable. POST and PATCH /v1/webhook_endpoints require an HTTPS URL that resolves to a public address — loopback, private-network, and link-local hosts are rejected with 400 invalid_url. Replaying a delivery to an endpoint whose URL no longer resolves publicly is rejected the same way. Use a public HTTPS tunnel (not raw localhost) when testing locally.

POST /v1/webhook_endpoints now takes an Idempotency-Key. A same-key + same-body retry returns the original endpoint (including its secret) with 200; a same key with a different body returns 409 idempotency_key_conflict. Send a UUID per logical create.

Webhook test events now sign with the production scheme. The “send test event” action previously used a legacy signature header format; it now signs with the same X-Swappr-Signature: t=<unix>,v1=<hmac> scheme as real deliveries, so a receiver built against the test event verifies live traffic unchanged. See Webhooks → verify the signature.

id_expiry_date is now required for type: individual on POST /v1/customers (YYYY-MM-DD, future date). The banking partner needs it to provision the customer’s virtual account, and it cannot be added after verification. Creates without it are rejected with missing_field (field id_expiry_date).

GBP/USD/EUR payout gate is now per-flow. An individual sender (sender_customer_id) sends from the sender’s own virtual account — a new sender_account_not_provisioned (422) is returned if that customer has no active VBA in the currency. A business/treasury sender keeps the existing no_active_international_account (403) gate against the merchant’s international account. CAD routes via Interac for both.

POST /v1/beneficiaries no longer requires an active international account for GBP/USD/EUR — only the international-accounts feature flag (fx_features_not_enabled if off). A beneficiary is a sender-agnostic saved recipient; the capability check now lives at payout time. Previously this returned no_active_international_account at save time.

POST /v1/customers/{id}/kyc is documented as an acknowledgement for individuals — verification runs automatically once identity documents are attached (no separate submit). Status also refreshes from the partner on read.

Customers API — POST /v1/customers plus KYC submission, document upload, international account (VIBAN) issuance, and a unified GET /v1/customers/{id}/transactions history. See the Customers reference.

FX beneficiaries — POST /v1/beneficiaries now accepts GBP / USD / EUR recipients via a nested bank + address envelope, with an optional external_reference. See the FX shape.

FX payouts — POST /v1/payouts accepts beneficiary_id, customer_id, and customer_reference. The generic customer_id and the FX-specific sender_customer_id both attribute a payout to the same customer; pass either (or both, if they agree).

FX gating error code — POST /v1/beneficiaries and POST /v1/payouts report no_active_international_account when an FX (GBP / USD / EUR) operation is attempted without an active international account in that currency.

Standardized payout webhooks — payout.processing / payout.paid / payout.failed / payout.reversed now fire on every real status transition (not only on admin force-close), with a consistent payload that includes a customer block when attributed. See Webhooks → Payout lifecycle payload.

wallet_funded customer block — VA-credit webhooks for customer-owned accounts now carry a customer block.

Per-customer wallet filter — GET /v1/wallets/{id}/transactions?customer_id= returns the raw ledger view of one customer’s movements (requires the customer_transaction_view permission).