Console

Sandbox · no real money

Test it before it matters

A payment that succeeds, a payer who declines, a retry that must not charge twice, a forged webhook. Each one is a sandbox case you can run end to end, with test data and a copy-ready request for every public operation.

Environment
sandbox
Currency
KES
Provider
simulator
Money at risk
none

This page cannot send a request for you, and that is deliberate. Every PayGate call is signed with your client's Ed25519 key and a per-request DPoP proof. A hosted page has no business holding that key, so the runnable path is the sandbox test in your own checkout.

Run bun run sandbox:test in the repository: it boots an in-process sandbox, seeds the five apps, and proves the cases on this page over real HTTP, then exits non-zero if any of them regress.

Start here

Two ways to test. Use the runner to prove the flow, then point your own integration at the same sandbox and run it again.

bun install
bun run sandbox:test      # self-contained: boots, seeds, runs, tears down
bun run seed              # API on :4000 with five sandbox apps, for your own calls
bun run demo              # :4100, a working storefront that hosts its own sandbox

Against 127.0.0.1:4000 the base URL is local, so no tunnel is needed. The SDK reads PAYGATE_CLIENT_ID, PAYGATE_PRIVATE_KEY and PAYGATE_WEBHOOK_SECRET; the demo prints the credentials it seeds.

Test data

The simulator is deterministic where it matters: the same number always produces the same outcome, so a failure test is repeatable.

CaseValueWhat happens
Payer numberAny Kenyan mobile numberThe simulator accepts it and settles on the next status query.
Payer number ending 0000254712340000Always declines: 1032, customer_cancelled.
Payout number ending 0000254712340000Payout fails: 2001, declined.
CurrencyKESThe simulator handles KES only; a live connector handles the rest.
AmountsInteger minor unitsNo decimal point is accepted anywhere.
Seeded appdemoVerified sellers, an instant payout mode and a batched one.
Seeded recipientMama Njeri's Shopapp_ref shop_88, payout mode instant.
Webhook tolerance300 secondsOlder signatures are refused even when the HMAC is correct.

Sandbox and live are separate rails: a sandbox credential only ever reaches the simulator, and the simulator is not registered in a production process.

Scenarios

Each case states what it proves and what a correct integration should observe. The runner asserts all of them; the expected lines below are copied from a passing run.

A payment that succeeds

The full create → confirm → status path, and that settlement is reported only after the provider is queried.

  1. Create a payment with paygate.pay() and keep the returned checkout_url.
  2. Open the checkout URL and pay with any number that does not end in 0000.
  3. Do not trust the browser redirect. Poll GET /v1/payments/{id}, or wait for the webhook, until the status is succeeded.

Expected processing while the attempt runs, then succeeded with a provider receipt. The redirect alone never settles anything.

A payer who declines

The failure path and its error taxonomy, without a network or a real phone.

  1. Create and confirm a payment with payer number 254712340000 (any number ending in 0000).
  2. Read the payment, then refresh it if it is still processing.

Expected failed, with the attempt carrying error code 1032 and category customer_cancelled. No ledger entry is posted for a failed payment.

A retry that must not double-charge

The idempotency rule every write depends on.

  1. Send the same POST /v1/payments twice with one Idempotency-Key.
  2. Send it a third time with the same key but a different amount.

Expected The first two return the same payment id. The third is 409 idempotency_conflict — never a second charge.

A payout the provider rejects

Payout failure handling and the difference between an instruction and a payment.

  1. Add a destination whose mobile number ends in 0000 to a recipient.
  2. Request a settlement to that recipient and read the instruction.

Expected The instruction fails with provider code 2001 (declined). The recipient's available balance is not reduced twice, and no retry is attempted automatically.

A forged webhook

Callbacks are authenticated before their contents are believed.

  1. Send your webhook endpoint a body with a signature computed from the wrong secret.
  2. Send the correct signature with a timestamp older than five minutes.

Expected Both are 401. A valid signature is HMAC-SHA256 over ${t}.${rawBody}, verified against the raw body before parsing.

A callback that is not proof

The rule that keeps a forged or replayed provider callback from marking money as paid.

  1. Create a payment and leave it requires_action.
  2. POST a success callback to /v1/callbacks/{provider} without a matching attempt.
  3. Read the payment.

Expected The callback is recorded and ignored for settlement. The payment keeps its state until a provider status query says otherwise.

Requests

Every public operation, with the credential it takes and a request you can paste into a terminal. Replace the $PLACEHOLDERS; the body templates are shapes, not valid values. /c/… routes are the buyer's checkout pages and are opened in a browser, not called with a key.

payments

get /v1/payment_methods Methods this tenant can use right now

Optional ?currency=KES. The publishable key must come from a registered Origin.

Credential publishableKey

curl -X GET "https://api.paygate.example/v1/payment_methods" \
  -H "Authorization: Bearer pk_sandbox_…"
get /v1/payments List payments for the calling tenant

?status=&limit=&cursor=

Credential accessToken + dpopProof

curl -X GET "https://api.paygate.example/v1/payments" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
post /v1/payments Create a payment intent

{ amount_minor, currency, reference, recipient_id?, splits?, metadata? } plus Idempotency-Key. splits is [{ recipient_id, amount }] and its shares must sum to the amount; it is mutually exclusive with recipient_id.

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/payments" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
get /v1/payments/{id} Read one payment and its attempts

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X GET "https://api.paygate.example/v1/payments/$ID" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
post /v1/payments/{id}/confirm Start or resume the provider attempt

{ method: 'mobile_money' | 'card', phone? } plus Idempotency-Key.

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/payments/$ID/confirm" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/payments/{id}/refresh Ask the provider for authoritative status

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/payments/$ID/refresh" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/payments/{id}/cancel Cancel an unpaid payment intent

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/payments/$ID/cancel" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/payment_links Create a payment link

{ description, amount, currency? }. The amount is fixed for the life of the link.

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/payment_links" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/payment_links/{id}/active Close or reopen a link

{ active: boolean }. Closing stops new payments and leaves existing ones alone.

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/payment_links/$ID/active" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

payouts

post /v1/releases Release a settled payment to its seller

{ recipient_id, reference } plus Idempotency-Key.

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/releases" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/recipients Create a seller, pharmacy or lab that can be paid

{ display_name, type, ... }

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/recipients" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
get /v1/recipients/{id} Read one recipient

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X GET "https://api.paygate.example/v1/recipients/$ID" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
patch /v1/recipients/{id}/payout_mode Change how this recipient is paid

{ payout_mode: 'instant' | 'on_request' | 'scheduled' | 'manual' }

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X PATCH "https://api.paygate.example/v1/recipients/$ID/payout_mode" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
post /v1/recipients/{id}/destinations Add a payout destination

{ provider, msisdn? , ... }

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/recipients/$ID/destinations" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
get /v1/recipients/{id}/balances Pending, unreleased, available, reserved and paid for one recipient

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X GET "https://api.paygate.example/v1/recipients/$ID/balances" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
get /v1/settlements List payout instructions

Credential accessToken + dpopProof

curl -X GET "https://api.paygate.example/v1/settlements" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
post /v1/settlements Create a payout instruction for a recipient

{ recipient_id, amount_minor, reference } plus Idempotency-Key. Above the approval threshold this waits for a second operator.

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/settlements" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
get /v1/settlements/{id} Read one payout instruction

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X GET "https://api.paygate.example/v1/settlements/$ID" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
post /v1/settlements/{id}/executed Record the app's signed-mandate execution result

{ status: 'succeeded' | 'failed', provider_ref?, reason? }, authenticated as the executor.

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X POST "https://api.paygate.example/v1/settlements/$ID/executed" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
post /v1/withdrawals A recipient-initiated withdrawal request

{ recipient_id, amount_minor } plus Idempotency-Key.

Credential accessToken + dpopProof

curl -X POST "https://api.paygate.example/v1/withdrawals" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"
get /v1/withdrawals/{id} Read one withdrawal request

Credential accessToken + dpopProof

Parameters

  • id path · string required
curl -X GET "https://api.paygate.example/v1/withdrawals/$ID" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

hosted

get /l/{token} Payment link page

Credential none

Parameters

  • token path · string required
curl -X GET "https://api.paygate.example/l/$TOKEN"
post /l/{token}/pay Create the payment behind a link and open checkout

No body. A form post is the buyer's explicit consent to pay.

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/l/$TOKEN/pay"
get /c/{token} Hosted checkout page, or the payment's result once terminal

Credential none

Parameters

  • token path · string required
curl -X GET "https://api.paygate.example/c/$TOKEN"
post /c/{token}/pay Buyer picks a method and pays without leaving the page

{ method: 'mobile_money', phone } or { method: 'card', card_number, card_expiry, card_cvv, card_holder }. Card fields are optional; a request without them falls back to the hosted card step.

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/c/$TOKEN/pay"
get /c/{token}/card Hosted card fallback, for connectors without a direct charge

Credential none

Parameters

  • token path · string required
curl -X GET "https://api.paygate.example/c/$TOKEN/card"
post /c/{token}/card Start a hosted card attempt

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/c/$TOKEN/card"
post /c/{token}/card/charge Charge a card the browser encrypted, without leaving the page

{ encrypted } — the provider's ciphertext; no PAN is sent to this origin.

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/c/$TOKEN/card/charge"
post /c/{token}/card/authorize Finish a direct card charge that needs a second factor

{ attempt_id, mode, auth_<field> } for a server-captured card, or { attempt_id, encrypted } when the browser re-encrypted the whole payload with the step-up fields inside it.

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/c/$TOKEN/card/authorize"
get /c/{token}/card/return Return from the card page

The provider's reference in the query.

Credential none

Parameters

  • token path · string required
curl -X GET "https://api.paygate.example/c/$TOKEN/card/return"
get /c/{token}/status Status page for a payment

Credential none

Parameters

  • token path · string required
curl -X GET "https://api.paygate.example/c/$TOKEN/status"
post /c/{token}/simulate Sandbox only: make the simulated provider settle

Credential none

Parameters

  • token path · string required
curl -X POST "https://api.paygate.example/c/$TOKEN/simulate"

auth

post /v1/auth/token Exchange a client assertion for a short-lived access token

grant_type=client_credentials&client_id=…&client_assertion=… as a form body. The DPoP header carries the proof.

Credential dpopProof

curl -X POST "https://api.paygate.example/v1/auth/token" \
  -H "DPoP: $DPOP_PROOF"

system

get /healthz Liveness, admission statistics, and optionally ledger drift

?full=1 adds a balanced-journal check for the first tenant. Expensive; not for a per-second probe.

Credential none

curl -X GET "https://api.paygate.example/healthz"
get /v1/openapi.json This document

Credential none

curl -X GET "https://api.paygate.example/v1/openapi.json"
post /v1/sandbox/signup Create a sandbox app and return its credentials once

{ app_name, email }. Sandbox only: this route cannot mint a live client.

Credential none

curl -X POST "https://api.paygate.example/v1/sandbox/signup"
post /v1/sandbox/rotate Replace the sandbox key pair

{ recovery_token }. The old client is revoked after the new one is registered.

Credential none

curl -X POST "https://api.paygate.example/v1/sandbox/rotate"
post /v1/sandbox/revoke Revoke the sandbox client

{ recovery_token }.

Credential none

curl -X POST "https://api.paygate.example/v1/sandbox/revoke"
get /v1/providers/health Observed health for every provider lane

Merchant-authenticated. The operator view is a separate, internal surface and is not part of this reference.

Credential accessToken + dpopProof

curl -X GET "https://api.paygate.example/v1/providers/health" \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"
get / Service banner

Credential none

curl -X GET "https://api.paygate.example/"

callbacks

post /v1/callbacks/{provider} Provider callback, authenticated by the provider's own signature

The provider's native body (Daraja Body.stkCallback, Paystack JSON). Verified before anything is recorded.

Credential none

Parameters

  • provider path · string required
curl -X POST "https://api.paygate.example/v1/callbacks/$PROVIDER"
post /v1/sequin/events Sequin change-data ingress, authenticated by HMAC over the raw body

Sequin's webhook batch, { data: [ { action, record, metadata } ] }, signed as x-sequin-signature. Watched tables: payment_poll_queue and webhook_outbox.

Credential none

curl -X POST "https://api.paygate.example/v1/sequin/events"

Machine-readable

If you are wiring an agent, give it the contract rather than this page.

  • /openapi.jsonOpenAPI 3.1, 40 paths. Also served by the API at /v1/openapi.json.
  • /llms-full.txtThe complete integration guide, including the test-mode rules.
  • /api/The same operations with every parameter, body and response.
Back to top