Console
Docs/Get started

Quickstart

Create a sandbox payment, send the buyer to checkout, and read the verdict from your server.

#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

Node / Bun
bun add @paygate/server
# or: npm install @paygate/server
React (web)
bun add @paygate/web
React Native / Expo
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.

Node
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
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:

Shell
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:

TypeScript
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:

Node
await paygate.pay({
  amount: 1500,
  currency: "KES",
  reference: `decline-${Date.now()}`,
  phone: "254712340000", // a number ending 0000 declines with 1032
});
cURL
# 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.

Reference

Every route, parameter and response is generated from the OpenAPI 3.1 document.

Open the API reference