Quickstart

Prerequisites

An Xtopay account — sign up free
Node.js 18+ or any HTTP client

1. Get your credentials

Credential	Example	Purpose
Client ID	`cid_test_...`	Identifies your application
Client Secret	`csk_test_...`	Authenticates your requests

Never expose your Client Secret in client-side code, mobile apps, or public repositories. Always use it server-side only.

Store them as environment variables:

XTOPAY_CLIENT_ID=cid_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
XTOPAY_CLIENT_SECRET=csk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Install the SDK

npm install @xtopay/node
# or
bun add @xtopay/node
# or
yarn add @xtopay/node

3. Initialise the client

import Xtopay from "@xtopay/node";

const xtopay = new Xtopay({
  clientId: process.env.XTOPAY_CLIENT_ID!,
  clientSecret: process.env.XTOPAY_CLIENT_SECRET!,
});

4. Create a payment

const payment = await xtopay.payments.create({
  amount: 5000,        // in the smallest currency unit (kobo, pesewas, cents)
  currency: "GHS",
  customer: {
    email: "ama@example.com",
    name: "Ama Owusu",
    phone: "+233244000000",
  },
  redirect_url: "https://yourapp.com/payment/success",
  metadata: {
    order_id: "ord_001",
    product: "Pro Plan",
  },
});

// Redirect your customer to this URL
console.log(payment.checkout_url);

The checkout_url opens Xtopay's hosted checkout page where your customer picks their preferred payment method (card, mobile money, bank transfer, USSD) and completes payment.

5. Listen for the result

Instead of polling, use webhooks. Register your endpoint in Settings → Webhooks, then handle the payment.succeeded event:

import { headers } from "next/headers";
import Xtopay from "@xtopay/node";

const xtopay = new Xtopay({
  clientId: process.env.XTOPAY_CLIENT_ID!,
  clientSecret: process.env.XTOPAY_CLIENT_SECRET!,
});

export async function POST(req: Request) {
  const body = await req.text();
  const signature = (await headers()).get("x-xtopay-signature")!;

  // Verifies the HMAC-SHA256 signature using your Client Secret
  const event = xtopay.webhooks.constructEvent(body, signature);

  switch (event.type) {
    case "payment.succeeded": {
      const { id, amount, currency, customer } = event.data;
      await fulfillOrder(event.data.metadata.order_id);
      break;
    }
    case "payment.failed": {
      await notifyCustomer(event.data.customer.email);
      break;
    }
  }

  return new Response("ok");
}