#Server (@paygate/server, Node and Bun)
import Paygate from "@paygate/server";
const paygate = new Paygate(); // PAYGATE_URL, PAYGATE_CLIENT_ID, PAYGATE_PRIVATE_KEY, PAYGATE_WEBHOOK_SECRET
const { checkout_url } = await paygate.pay({ amount: 1500, reference: "order_8123" });
PAYGATE_PRIVATE_KEY is a JSON Ed25519 JWK, not PEM.
Useful calls: pay, get, byReference, refresh, cancel, methods, createPaymentLink, paymentLinks, setPaymentLinkActive, createRecipient, addDestination, balances, setPayoutMode, release, settle, withdraw, instructions, instruction, webhook, mandate.
webhook(handler)(request) verifies the signature over the raw body and returns a non-2xx when your handler throws, so PayGate retries.
#Web (@paygate/web)
import { PaygateWeb } from "@paygate/web";
const pg = new PaygateWeb({ publishableKey: "pk_sandbox_..." });
const methods = await pg.paymentMethods("KES");
pg.go(payment.checkout_token); // hosted checkout
pg.mount("#pay", { token, label: "Pay KES 1,500" }); // or a ready button
#Mobile (@paygate/mobile + @paygate/mobile/relay)
The app never holds the tenant credential. Your backend mounts the relay; the app talks to it.
// backend — app/paygate/[[...path]]/route.ts for Next.js, or any fetch handler
import { createRelayHandler } from "@paygate/mobile/relay";
const relay = createRelayHandler({ paygate, basePath: "/paygate", authorize: requireSession });
// app
const paygate = createPaygateMobile({ baseUrl: "https://api.yours.app/paygate", headers });
const { payment } = await paygate.pay({ reference: "order_8123", amount: 1500, phone: "254712345678" });
pay() resolves only when the server reports succeeded; otherwise it throws PaygateMobileError with code, status, retryable, userMessage. The relay exposes exactly five routes: GET /methods, POST /payments, GET /payments/:id, POST /payments/:id/confirm, POST /payments/:id/cancel. No payouts, releases or withdrawals.
Express and Node's http module need a small adapter; app.use cannot take the Fetch handler directly. Read the raw body into a Request, call the relay with it, and write its Response back. Mount the adapter before express.json(), which would otherwise consume the body. The complete adapter is in the framework guide.
For cards, call pay() without phone (or with method: "card"); it returns checkoutUrl and charges nothing until the hosted page is completed.
#Native iOS and Android
No native SDK. Use the REST API from Swift or Kotlin through your own backend, or mount the same relay used by the React Native SDK and call it from the app. Keep the Ed25519 key on the server.