Top-ups

Overview

A top-up is a payment that adds funds to a customer's wallet. Xtopay uses the same checkout flow as one-time payments — the customer picks their preferred method (card, mobile money, bank transfer) and completes the payment. On success, the wallet balance is credited automatically.

Create a top-up

const topup = await xtopay.wallets.createTopup({
  wallet_id: "wal_a1b2c3",
  amount: 20000,          // GHS 200.00 to add
  redirect_url: "https://yourapp.com/wallet/topup/success",
  cancel_url: "https://yourapp.com/wallet",
});

redirect(topup.checkout_url);

The customer is redirected to Xtopay checkout, completes payment, and is sent back to your redirect_url. The wallet balance is updated immediately on payment success — no polling needed.

Top-up object

{
  "id": "tup_a1b2c3",
  "wallet_id": "wal_abc",
  "amount": 20000,
  "currency": "GHS",
  "status": "succeeded",
  "payment_id": "pay_xyz789",
  "checkout_url": "https://checkout.xtopay.co/pay/tok_...",
  "created_at": "2026-05-24T10:00:00Z",
  "paid_at": "2026-05-24T10:01:30Z"
}

Pre-defined top-up amounts

Offer customers quick-select amounts in your UI:

const TOP_UP_AMOUNTS = [1000, 2000, 5000, 10000, 20000]; // GHS 10, 20, 50, 100, 200

export function TopupButtons({ walletId }: { walletId: string }) {
  return (
    <div className="flex gap-2">
      {TOP_UP_AMOUNTS.map((amount) => (
        <form key={amount} action="/api/wallet/topup" method="POST">
          <input type="hidden" name="wallet_id" value={walletId} />
          <input type="hidden" name="amount" value={amount} />
          <button type="submit">GH₵{amount / 100}</button>
        </form>
      ))}
    </div>
  );
}

Webhook

When a top-up succeeds, Xtopay fires wallet.topup_succeeded:

{
  "type": "wallet.topup_succeeded",
  "data": {
    "topup_id": "tup_a1b2c3",
    "wallet_id": "wal_abc",
    "amount": 20000,
    "new_balance": 35000
  }
}

Use this event to update your UI, send a balance confirmation email, or unlock features tied to minimum balance.

Minimum and maximum top-up amounts

Currency	Minimum	Maximum
GHS	GHS 5.00 (500)	GHS 10,000.00 (1,000,000)
NGN	NGN 100.00 (10,000)	NGN 1,000,000.00 (100,000,000)
KES	KES 50.00 (5,000)	KES 100,000.00 (10,000,000)

Requests outside these bounds return 400 amount_out_of_range.