Console
Docs/Build

SDK reference

Every call the server, web and mobile packages expose.

#Server (@paygate/server, Node and Bun)

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

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

TypeScript
// 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.

Reference

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

Open the API reference