Card top-ups (Stripe)

With a Stripe payment method added under Payments, a customer can top up by card on Stripe’s own checkout page. You use your own Stripe account and keys; the money goes to that account. Check that your business meets Stripe’s rules on prohibited and restricted businesses before you start.

Setting it up

1. In your Stripe dashboard, copy your secret key.
2. Under Payments → Add a payment method → Stripe, enter it as the Secret key, and optionally a top-up cap and a waiting period for new accounts. The method’s row then shows its Webhook URL.
3. In your Stripe dashboard, add that address as a webhook endpoint and choose these events:
   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • checkout.session.async_payment_failed
   • charge.dispute.created
   • charge.dispute.closed
4. Copy the endpoint’s signing secret (it starts with whsec_) into the method’s Webhook signing secret.

Every notification from Stripe is checked against that secret. One with a wrong signature is recorded but never acted on.

How a payment is credited

A top-up is credited once Stripe says it’s paid, for exactly the amount and currency the customer chose. However often Stripe repeats a notification, the top-up is credited only once.

• Card payments are usually paid when the customer finishes checkout, so the balance is credited right away.
• Delayed payment methods (a bank debit, for example) can take days. The top-up waits until Stripe says the money arrived, then it’s credited. If the payment fails, the top-up is rejected and the customer is told.
• A payment for a different amount or currency than the top-up isn’t credited. It appears under Payments → Payments that need attention, as does a payment for a top-up you already rejected. Check it in your Stripe dashboard, then mark it handled.

Disputes (chargebacks)

When a customer disputes a card payment with their bank:

• the disputed amount is taken back from their balance, which may go negative;
• their account is frozen, so they can’t order or withdraw;
• every owner of the business gets an email and a panel notice.

A dispute on a payment no top-up matches charges nothing back and freezes no one; it appears under Payments that need attention instead.

Answer the dispute in your Stripe dashboard. When Stripe closes it, you get another email saying whether you won or lost. Nothing changes automatically when a dispute closes. If you won, you can unfreeze the customer under Users and give the amount back with a manual balance adjustment. If you lost, the chargeback stands.

Limiting risk

• Top-up cap: the most one card top-up may be, in your wallet currency.
• Waiting period for new accounts: how many days a new customer must wait before paying by card.

Both are optional, and you set them when you add the method.