Skip to main content
Prepaid credit is credit a customer pays for before they use it: “buy ₦20,000 of credit, spend it on API calls”. Their usage invoices then spend the credit before charging the card.

​
Sell credit

Sell a credit pack (a one-time price on a product created with kind: credit) or a custom amount:
It issues a top-up invoice (billingReason: credit_purchase). Its credit waits as pending_payment, shown in pending on the balance, until the invoice is paid; then it becomes spendable and its expiry starts.
  • With manual collection (the default), send the customer to the invoice’s hostedUrl to pay.
  • With "collectionMode": "automatic", Bouclay charges paymentMethod, or the customer’s default card.
  • Voiding an unpaid top-up cancels its credit.

​
Bonus packs

“Pay ₦50,000, get ₦55,000”: set creditAmount above unitAmount on the pack’s price. The extra ₦5,000 is its own promotional lot, spent first. Refunding or charging back the top-up forfeits what is left of the bonus.

​
When VAT is charged

The customer pays VAT once on what their credit pays for. You choose when, with vatTiming on the purchase, the pack’s product, or your default under Billing settings → Tax → Prepaid credit. Which one fits is a question for your accountant. Credit taxed when bought only pays lines taxed the same way as its top-up. An exempt, zero-rated or export line, or one after a VAT rate change, is billed normally.

​
Refunds

Refunding a top-up is capped at the credit not yet spent (for at_purchase credit, that credit plus its VAT). A credit note on a usage invoice that prepaid credit paid gives that part back to the lots it came from.

​
Stop when credit runs out

Read projectedAvailable on the credit balance before costly work, and stop at zero. For an exact stop, with no overspend when two requests arrive at once, use credit holds.

​
Auto-reload

Keep a customer topped up: “when my credit falls to ₦5,000, buy ₦20,000 with my card”.
  • One rule per customer and currency. Posting again replaces it.
  • After every change to the customer’s credit and every usage event, Bouclay compares projectedAvailable with threshold. At or below it, it buys amount of prepaid credit, charged to paymentMethod or the default card.
  • One fall buys once. It buys again only after the credit has been back above the threshold.
  • PATCH /customers/{id}/credit-auto-reloads/{currency} changes it; "enabled": false turns it off.
If a charge fails, that top-up is voided, the rule turns itself off (disabledReason: payment_failed), and the customer gets an email saying automatic top-ups are off. Nothing is retried. Turn it back on once the card is sorted. A rule also turns itself off when there is no card left to charge (no_payment_method). Each change sends credit_auto_reload.updated.