Going live

The environment is derived from the key alone: sk_test_ keys hit the sandbox (a payment simulator; no real operator is ever touched and no real money can move) and sk_live_ keys hit production. There is no environment switch, header or base-URL change: going live means replacing the key your backend loads.

Authorization: Bearer sk_test_XXXXXXXXXXXX   # sandbox: simulator, no real money
Authorization: Bearer sk_live_XXXXXXXXXXXX   # production: real operators, real money

Everything you built against the sandbox carries over: the same routes, the same response envelope, the same webhook signature scheme, the same closed error catalog. Sandbox and production data are fully isolated: ids from one environment answer 404 in the other.

Production access requires a verified business. In the Business Portal under Compliance, you submit your legal entity details, ownership and directors (including PEP disclosure), and the supporting documents. The review is two-stage on our side; you can track the state on the same page and respond to any request for more information.

Until your merchant account is ACTIVE (KYB approved), production capabilities stay closed: production API keys cannot be created, and a production payment link shows payers an honest unavailable screen. Sandbox access is unrestricted the whole time.

Once the account is ACTIVE, create a production app and mint an sk_live_ key in the dashboard under Developers > API keys. The full secret is shown exactly once, at creation: store it in your secrets manager, never in client code or a repository. A key minted before approval is impossible, and a compromised key can be revoked and reissued at any time without touching the app.

Scopes are fail-closed, so mint the key with exactly the scopes your integration needs (collections:write, payouts:read, ...). Verify the key with GET /v1/whoami before deploying: it names the merchant, app, environment and scopes behind the credential.

curl https://api.capayglobal.com/v1/whoami \
  -H "Authorization: Bearer sk_live_XXXXXXXXXXXX"

Webhook endpoints are per environment: your sandbox endpoints do not fire for live traffic. Register your production HTTPS endpoint (POST /v1/webhook_endpoints or the dashboard), store the whsec_ secret from that one response, and subscribe to at least collection.completed, collection.failed, payout.completed and payout.failed.

Verify the X-Capay-Signature header on the raw body of every delivery before trusting it, exactly as in the Authentication guide. Deliveries are at-least-once and can arrive out of order: key your processing on the event id. Authentication

The payer's payment prompt and mobile money statement carry your merchant trading name by default: the API fills metadata.statement_description with it on every collection and payout unless you supply your own value. Your customers see your business, never the gateway.

{
  "amount": "5000",
  "currency": "XAF",
  "country": "CM",
  "method": "mobile_money",
  "msisdn": "+237650000001",
  "merchant_reference": "order-10482",
  "metadata": {
    "statement_description": "SUNRISE ELECTRONICS"
  }
}

Keep any custom statement_description to letters, digits and spaces: mobile money operators reject or strip other characters from statement text.

Before pointing real customers at the integration:

• KYB approved: the merchant account shows ACTIVE in the portal.
• sk_live_ key minted with the right scopes, stored server-side, and verified with GET /v1/whoami.
• GET /v1/providers called with the live key: the countries and methods you need are open (see Coverage).
• GET /v1/pricing quoted for your typical amounts: the fees are what you expect (see Fees & settlement).
• Production webhook endpoint registered, signature verification proven against a live delivery.
• One small live collection completed end to end, and its webhook received and verified.
• A settlement account added in the portal so settlement payouts have somewhere to go.
• Every collection and payout status handled explicitly in your code: anything unhandled treated as failure, never success.

CoverageFees & settlementPayment links & checkout