#Before you start
Create a sandbox app at console.paygate.example/signup. It issues credentials immediately — no operator, no waiting:
- Client id — identifies your app.
- Ed25519 private key — a JSON JWK, not a PEM file. It never leaves your server.
- Recovery token — shown once, and the only way to rotate or revoke the key later.
Sandbox is the default and the only thing self-serve creates: it runs on the simulator, no real money moves, and every scenario below works without a provider account. A live credential is issued separately, after provider onboarding.
#1. Install the SDK
bun add @paygate/server
# or: npm install @paygate/server
bun add @paygate/web
bun add @paygate/mobile
Only the server SDK ever holds the private key. The web and mobile packages take a publishable key, which can read payment methods and nothing else.
#2. Create a payment
Creating a payment is a server call. The amount is an integer in minor units — 250000 is KES 2,500.00.
import Paygate from "@paygate/server";
const paygate = new Paygate();
const payment = await paygate.pay({
amount: 250000,
currency: "KES",
reference: `order-${order.id}`, // your id: same reference never charges twice
return_url: "https://your.app/thanks",
});
// Send the buyer here.
console.log(payment.checkout_url);
curl -s https://api.paygate.example/v1/payments \
-H "authorization: DPoP $TOKEN" \
-H "dpop: $PROOF" \
-H "idempotency-key: order-9f2c-01" \
-H "content-type: application/json" \
-d '{
"reference": "order-9f2c",
"amount": 250000,
"currency": "KES",
"return_url": "https://your.app/thanks"
}'
The response is 201 with a payment in requires_action and a checkout_url. reference is yours and is unique per app: send it twice and you get the same payment back, never a second charge.
#3. Let the buyer pay
Redirect to checkout_url, or open it in a WebView on mobile. The hosted page lists the methods available for the currency — mobile money, card, or both — and handles the provider's step-up.
If you already have the buyer's phone number, you can skip the hosted page and start the attempt from your server:
curl -s -X POST https://api.paygate.example/v1/payments/$PAYMENT_ID/confirm \
-H "authorization: DPoP $TOKEN" \
-H "dpop: $PROOF" \
-H "idempotency-key: confirm-$PAYMENT_ID-1" \
-H "content-type: application/json" \
-d '{"method": "mobile_money", "phone": "254712345678"}'
Poll GET /v1/payments/{id}, or wait for the webhook, for the result.
#4. Read the verdict
Show success only when PayGate says succeeded:
const current = await paygate.get(payment.id);
if (current.status === "succeeded") {
// fulfil the order
}
Terminal statuses are succeeded, failed, cancelled and expired. A redirect, a deep link or a browser query string is not proof of payment; the return URL is for your UI, not your ledger.
For production, stop polling and take the webhook: it is signed, retried, and arrives once per state change.
#5. Prove the failure path
The sandbox is a state machine, not a stub. Run the decline before you ship:
await paygate.pay({
amount: 1500,
currency: "KES",
reference: `decline-${Date.now()}`,
phone: "254712340000", // a number ending 0000 declines with 1032
});
# same request as step 2, with a phone ending 0000 in confirm
The payment ends failed with provider_error and code 1032, and nothing is posted to the ledger. Handle it the same way you handle a real decline: tell the buyer, keep the order unpaid.
#Next
- Authentication — the token and DPoP proof the SDK hides from you.
- Payments — the full lifecycle, retries and cancellation.
- Webhooks — signature verification, deduplication and retries.
- Frameworks & SDKs — Next.js, Python, PHP, Flutter and React Native.
- Sandbox — decline numbers and copy-ready requests.