Transactions

Debit a wallet

Deduct funds from a customer's wallet when they consume your product:

const debit = await xtopay.wallets.debit({
  wallet_id: "wal_a1b2c3",
  amount: 500,             // GHS 5.00
  description: "10 SMS messages sent",
  reference: "sms_batch_xyz",   // your internal reference — must be unique
});

The debit is atomic — if the wallet has insufficient balance, it fails immediately with 402 insufficient_wallet_balance. The balance is never partially deducted.

Idempotent debits

Pass a unique reference to make debits idempotent. If you retry with the same reference, Xtopay returns the original debit without double-charging:

const debit = await xtopay.wallets.debit({
  wallet_id: "wal_a1b2c3",
  amount: 500,
  description: "API call batch #8821",
  reference: "api_batch_8821",   // retry-safe
});

Check balance before debit

const wallet = await xtopay.wallets.retrieve("wal_a1b2c3");

if (wallet.balance < requiredAmount) {
  return { error: "insufficient_balance", balance: wallet.balance };
}

await xtopay.wallets.debit({
  wallet_id: wallet.id,
  amount: requiredAmount,
  reference: operationId,
});

Transaction object

{
  "id": "txn_a1b2c3",
  "wallet_id": "wal_abc",
  "type": "debit",
  "amount": 500,
  "currency": "GHS",
  "balance_before": 15000,
  "balance_after": 14500,
  "description": "10 SMS messages sent",
  "reference": "sms_batch_xyz",
  "created_at": "2026-05-24T10:05:00Z"
}

Transaction types

Type	Triggered by
`topup`	Customer completes a top-up payment
`debit`	Your app calls `/wallets/:id/debit`
`credit`	Admin credit or promotional grant
`refund`	Top-up refunded to customer's payment method
`expiry`	Credits expired per expiry policy
`transfer_in`	Balance moved from another wallet
`transfer_out`	Balance moved to another wallet

List transactions

const transactions = await xtopay.wallets.listTransactions({
  wallet_id: "wal_a1b2c3",
  limit: 20,
  type: "debit",
});

Webhook events

Event	Fired when
`wallet.topup_succeeded`	Top-up payment completes
`wallet.topup_failed`	Top-up payment fails
`wallet.debited`	Debit recorded
`wallet.credited`	Admin credit applied
`wallet.credit_expired`	Expiring credits removed
`wallet.balance_low`	Balance drops below a threshold you configure
`wallet.frozen`	Wallet frozen
`wallet.closed`	Wallet closed

Configure the wallet.balance_low threshold in Dashboard → Settings → Wallet Alerts to prompt customers to top up before they run out.