Saved Payment Methods and Auto-Billing

Automatic renewal billing depends on a saved payment method. This article covers how customers add one, what “default” means, how the automatic charge run picks a method and what it does when the charge succeeds, is declined or cannot be attempted at all. It is written for both operators and their customers’ support needs.

Before you start #

• At least one gateway must be active — see Payment gateways.
• Real card vaulting only exists for Stripe and Square. PayPal and Bank Transfer methods are recorded as a reference rather than a vault token.
• The Process Due Invoices schedule must be enabled, and a worker must be consuming the payments queue, or nothing is ever charged automatically.

Adding a payment method (customer) #

1. Open Payment Methods in the client portal (/payment-methods).
2. Select Add New. A Select a Payment Provider screen always appears first, listing every active gateway.
3. Choose the provider and complete its form. For Stripe the page is titled Add a Credit Card and collects Name on card and Card details.
4. Leave Make this my default payment method ticked (it is ticked by default) unless the customer is adding a spare card.
5. Select Save Card.

Behind the scenes, for Stripe RackHelm creates or reuses a Stripe customer for the account, attaches the card, and confirms a setup intent marked for off-session use. For Square it creates a Square customer and a card-on-file. Either way the brand, last four digits and expiry are copied locally so screens can show them without calling the gateway.

Note: The first method a customer adds always becomes their default, whether or not the box is ticked. Only one method can be the default at a time — setting a new one clears the old.

Note: If the bank requires 3D Secure, the save pauses and the customer is asked to complete the challenge before the card is stored. A card that fails the challenge is not saved.

Warning: The Payment Methods list in the client portal has an Actions column that renders no buttons in this build, so customers cannot change their default or remove a card from that page. In practice they change the default by adding a card with Make this my default payment method ticked. There is no removal button on the staff side either — the admin Billing tab lists saved methods read-only — so a card can only be removed by someone working directly against the database.

Where else a card can be captured #

What staff can see #

Open Users & Roles → All Users → (customer) → Billing. The lower table lists every saved method with its Type, Details (card brand and last four, or the gateway name), whether it Is Default, and when it was Added. RackHelm never stores full card numbers — only the gateway’s token and the display fragments.

When you create an invoice by hand you can pin one specific saved card to it, so the automatic run charges that card rather than the account default. See Creating and editing invoices manually.

How automatic billing runs #

1. The Process Due Invoices schedule finds every pending invoice due today or earlier, skipping any whose order has been deleted.
2. It queues one payment job per invoice on the payments queue. Each job is unique per invoice for 10 minutes and is additionally serialised so two workers cannot charge the same invoice at once.
3. The job works out the split between account credit and card. Credit is only used if the customer has enabled Use Credit First; a residual card charge below 50p is raised to exactly 50p with credit covering the rest.
4. It selects the payment method: the invoice’s pinned method if there is one and it still belongs to the customer, otherwise the account default.
5. It charges through that method’s gateway, then settles the invoice — advancing due dates, queuing domain renewals, reactivating anything suspended for non-payment — and emails a receipt.

The outcomes #

Warning: Because a decline leaves the invoice pending, the customer is retried once per scheduled run — daily, by default — until the invoice is paid, voided, or the service is suspended by the overdue schedules. Expect a declined card to generate one failure email a day.

Expiring cards #

The Notify Expiring Cards schedule looks for saved cards whose expiry month and year fall in next month and emails those customers a warning. Each card is only ever warned about once for a given expiry date, so re-running the schedule does not spam anyone. It is seeded disabled — enable it under Schedules → Notify Expiring Cards.

An expired card is also flagged as such in the payment-method picker on the admin invoice creation screen, so you do not pin an invoice to a card that will fail.

Troubleshooting #