Wallets & prepaid credit

A wallet is a per-customer prepaid credit balance, denominated in a single currency. When a wallet is non-zero, it can be applied to settle open invoices automatically — useful for credits, gift cards, top-up billing, or platform-issued goodwill.

When you’d use one

Pay-as-you-go: customers top up; usage drains the wallet.
Annual prepay with monthly draw-down: bill upfront, recognise monthly via wallet settlement.
Goodwill credits: issue a credit note with outcome: credit_balance and apply it to the next invoice.
Refund to balance: instead of returning cash to a card, hold the refund in the wallet.

Shape

{
  "id": "wal_…",
  "customer_id": "cus_…",
  "currency": "USD",
  "balance": "127.50",
  "auto_top_up": {
    "enabled": true,
    "trigger_at": "10.00",
    "amount": "100.00",
    "payment_method_id": "pm_…"
  },
  "drift_floor": "0.00"
}

A customer can have at most one wallet per currency.

Crediting a wallet

POST /v1/wallets/{id}/credits
{ "amount": "50.00", "reason": "manual_topup", "external_id": "stripe_topup_…" }

reason is required and audited. Common values: manual_topup, auto_topup, credit_note, promotional, refund, migration.

Settling an invoice from a wallet

When an open invoice is created for a customer with a non-zero wallet in the matching currency, Paylera applies the wallet automatically — up to the wallet balance, never below the drift_floor. The remainder, if any, falls to the configured payment method.

To force wallet-only settlement (no card):

POST /v1/invoices/{id}/pay
{ "source": "wallet" }

This fails with wallet.insufficient_funds if the balance is less than amount_due.

Auto top-up

When a wallet drops below auto_top_up.trigger_at, an auto-top-up worker charges auto_top_up.payment_method_id for auto_top_up.amount and credits the wallet on success. Failures emit wallet.auto_topup_failed and back off with the same dunning policy as a normal invoice.

To disable:

PATCH /v1/wallets/{id}
{ "auto_top_up": { "enabled": false } }

Drift floor

drift_floor is the lowest balance auto-settlement is allowed to leave the wallet at. Default is 0. Set it to a positive value if you want to keep a buffer (e.g., reserve a deposit). Set it to a negative value to allow controlled overdraft (rare; requires operator approval and a documented credit policy).

Recognition

Crediting a wallet is not revenue. It’s a liability — you owe the customer that balance until it’s used. Recognition happens when the balance settles an invoice.

The ledger postings:

Event	Debit	Credit
Customer tops up wallet (cash in)	Cash	Wallet liability
Wallet settles an invoice	Wallet liability	AR
Customer requests wallet refund	Wallet liability	Cash

See Revenue recognition and Ledger reference for the full picture.

Common pitfalls

Multi-currency: a USD wallet does not settle a EUR invoice. You must explicitly convert by issuing a credit note + a top-up event.
Refund order matters: if a customer paid an invoice with a mix of wallet and card, the refund unwinds in reverse order — card first, then wallet.
Don’t expose wallet.balance to customers as “USD you have.” It’s a credit balance with terms — surface it in the UI as such.

Webhook events

Event	When
`wallet.credited`	Balance increased.
`wallet.debited`	Balance decreased (settlement, refund, manual debit).
`wallet.auto_topup_succeeded`	Auto top-up captured a payment.
`wallet.auto_topup_failed`	Auto top-up payment failed.
`wallet.below_drift_floor`	Balance hit `drift_floor` and settlement could not complete.