How Shopify card vaulting works
When a customer places a deposit or partial-payment preorder, Shopify securely saves ("vaults") their payment method at checkout. STOQ never sees or stores the card itself: it asks Shopify to charge that saved method later, using a payment mandate, when the remaining balance is due. This article explains that mechanism: what Shopify controls, what STOQ controls, and what happens when there's no valid vaulted method to charge.
This is a decision/explainer article about how the payment machinery works under the hood. To configure deposits, due dates, and manual vs. automatic collection, see Set up payment for preorders. To actually charge a balance, see Collect remaining preorder payments.
Before you begin
| Requirement | Detail |
|---|---|
| Shopify Payments | Vaulting and mandate charges only work through Shopify Payments, since this is a Shopify Payments capability, not something STOQ can add for other gateways |
| Partial payment or deposit offer | Full-payment preorders are charged in full at checkout and never need a vaulted method |
| Shopify purchase option | Vaulting for deposits relies on Shopify's native deferred/remaining-balance selling plan mechanics, which require the purchase option to stay on |
How vaulting works (Shopify's part)
Customer checks out with a deposit
At checkout, Shopify charges only the deposit or upfront amount configured on the offer. The rest of the order total is left as an outstanding balance.
Shopify vaults the payment method
As part of completing that checkout, Shopify Payments securely stores ("vaults") the card or payment method the customer used. This card data lives entirely in Shopify's PCI-compliant systems: STOQ has no access to card numbers and never stores them.
Shopify creates a payment mandate
Shopify links the vaulted method to the order through a payment mandate. This mandate is what authorizes a future charge against that saved method: it's the same underlying mechanism Shopify uses for subscriptions and deferred/remaining-balance selling plans.
STOQ later requests a charge against the mandate
When the balance is due, or when you collect manually, STOQ asks Shopify to charge the saved method, passing the order and mandate ID. Shopify accepts the request right away, then settles the card charge asynchronously.
What STOQ does with the vaulted method
STOQ doesn't handle the card itself. Everything it does goes through Shopify's Admin API, referencing the order and mandate by ID:
- Checks a vaulted method exists. Before scheduling or attempting a charge, STOQ asks Shopify whether the order has a vaulted method. If Shopify reports none, STOQ treats the order as uncollectable and doesn't attempt a charge.
- Reads the mandate ID. STOQ uses the ID of the vaulted payment method Shopify returns as the reference for the charge request.
- Requests the charge. STOQ asks Shopify to charge the mandate with auto-capture on, so a successful charge is captured immediately rather than only authorized.
- Tracks the attempt. Every attempt, successful, failed, or still pending, is recorded on the order, starting as pending since Shopify settles the charge asynchronously.
- Polls for the result. STOQ checks pending attempts starting 10 minutes after the request and for up to 24 hours, until Shopify reports a final status, success or failure. See When payment collection fails for the full failure-handling flow.
- Re-verifies the due date. Right before an automatic collection attempt, STOQ re-fetches the order's live payment schedule from Shopify and confirms the balance is actually due, so a stale cached due date never causes an early charge.
What customers will see
| Where | What happens |
|---|---|
| Checkout | The customer enters their card (or other Shopify Payments method) once, pays the deposit, and Shopify vaults that method for the remaining balance, with no separate "save my card" step or checkbox for the customer to interact with |
| Order confirmation | The order is created with the deposit paid and a balance outstanding; the customer isn't shown anything about the vault or mandate directly |
| When the balance is charged | If the mandate charge succeeds, the customer is simply charged, and Shopify sends its standard payment/receipt notifications per your store's settings |
| If the mandate charge fails | The customer receives STOQ's payment-collection-failed email (if Shopify returns a payment collection URL) with a link to Shopify's hosted payment page, where they can pay with a new or corrected card |
FAQ
Does STOQ store my customers' card details?
No. Card data is stored entirely by Shopify Payments in its PCI-compliant vault. STOQ only holds the Shopify order ID and the payment mandate ID it needs to request a charge, never card numbers, expiry dates, or CVV.
What is a payment mandate?
It's Shopify's authorization object linking a vaulted (saved) payment method to a specific order, created automatically when the customer pays a deposit through Shopify Payments. STOQ requests future charges against this mandate rather than against a raw card.
Why can't I offer a deposit without Shopify Payments?
Vaulting a payment method for a later charge is a Shopify Payments capability. Without it, there's no vaulted method for STOQ (or Shopify) to charge later, so partial payment/deposit isn't available, only full payment at checkout.
What happens if the customer's saved card expires before the balance is charged?
The mandate charge fails when attempted.
- STOQ records the failure.
- STOQ notifies you.
- If Shopify returns a payment collection URL for the order, STOQ emails the customer a link to Shopify's hosted payment page so they can pay with an updated card.
Is the charge immediate, or does Shopify take time to process it?
Shopify accepts the mandate-payment request right away and returns a payment reference ID, but the actual card charge settles asynchronously.
- STOQ records the attempt as pending.
- STOQ polls Shopify for the final result.
- The result typically resolves within minutes, and no later than the 24-hour polling window.
Can I see which orders have a valid vaulted payment method?
Not directly as a filter in STOQ today. STOQ checks for a vaulted method at charge time.
- If Shopify reports no vaulted method, the charge attempt doesn't proceed.
- The order remains uncollected.
- It's visible with an outstanding balance in your preorder orders report.
Does auto-capture mean the charge is captured instantly?
STOQ requests the mandate payment with auto-capture on, meaning a successful authorization is captured automatically rather than only authorized. The overall charge still settles asynchronously on Shopify's side, so there is a short delay before the order's financial status updates.
Related guides
Set up payment for preorders
Configure deposits, due dates, and manual vs. automatic collection.
Collect remaining preorder payments
Charge the outstanding balance in bulk or one order at a time.
When payment collection fails
What happens when a vaulted card is declined, expired, or removed.
Reschedule preorder payments
Move the due date instead of charging now.
