Authentication

Every API request requires two headers: your secret key and your Merchant ID. JKAPay uses Bearer-token authentication — there's no request signing required (only for verifying incoming webhooks).

Required headers

Authorization: Bearer sk_test_xxx — your secret API key.
X-JKAPay-Merchant-Id: MCH_XXXXXXXXXXXX — your unique Merchant ID, found on your API keys page.

Merchant ID

Every JKAPay merchant account is assigned a unique Merchant ID (e.g. MCH_A1B2C3D4E5F6). This ID is permanent, public, and safe to store in your environment variables. You must include it in the X-JKAPay-Merchant-Id header of every API call.

Shell

# Add to your .env file
JKAPAY_MERCHANT_ID=MCH_XXXXXXXXXXXX
JKAPAY_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API key format

JKAPay issues two related strings per key:

pk_test_xxx / pk_live_xxx — the public ID. Safe to include in logs, server tags, and analytics. JKAPay sends this back in webhook headers as X-JKAPay-Key-Id so you know which key signed an event.
sk_test_xxx / sk_live_xxx — the secret key. Treat like a password. Shown once at creation, never displayed again. Store in your server's environment variables — never in client-side code.

Sending a request

HTTP

POST /v1/payments/initialize HTTP/1.1
Host: api.jkapay.com
Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-JKAPay-Merchant-Id: MCH_XXXXXXXXXXXX
Content-Type: application/json

{ "amount": "1.00", ... }

Environments & account status

Every key has an environment baked in (TEST or LIVE), and the same base URL serves both. Test keys route through JKAPay's sandbox simulator — no real prompts, no real money movement — while live keys settle real payments through the mobile-money networks. The wire formats are identical, so the only difference in your code is which secret you load.

Pending review: You can create Test keys to build and test your integration. Live keys are locked until your account is approved.
Approved: You can create both Test and Live keys.
Suspended / Rejected: All API key creation is disabled and existing keys are disconnected. Contact support@jkapay.com.

Test keys let you validate your integration end-to-end without moving real money. Specific phone-number endings trigger specific outcomes — see Sandbox / test mode. Switch to a live key only when you're ready to accept real payments.

Rotation and revocation

From your dashboard, you can revoke any key at any time. Once revoked, every request using that key returns 401 UNAUTHENTICATED within seconds.

If you suspect a key has been leaked, revoke it first, then create a replacement. JKAPay never enforces a cooldown — revocation is instant.

Errors

Authentication failures return:

JSON

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing or invalid X-JKAPay-Merchant-Id header"
  }
}

See Errors for the full list of error codes.