Vault capture

Located at Stores → Configuration → Byte8 → Pre-Order → Automated Vault Capture.

This is the differentiating feature vs. competitors — the module captures the deferred balance automatically using the customer's stored vault token (Stripe, Adyen, Braintree, Authorize.net, etc.), with cron retries and a fallback email when capture truly fails.

Fields

Field	Path	Default	Notes
Enable Automated Vault Capture	byte8_preorder/vault_capture/enabled	No	Master switch for the vault capture pipeline.
Capture Trigger	byte8_preorder/vault_capture/trigger	shipment_create	When to initiate capture — see Triggers below.
Maximum Capture Attempts	byte8_preorder/vault_capture/max_attempts	3	Retries before the fallback email goes out.
Retry Backoff (minutes)	byte8_preorder/vault_capture/retry_backoff	60	Minutes between retries — multiplied by attempt count.

For the trigger and retry logic in depth, see Advanced → Vault capture.

Triggers

Trigger	When it fires	Use this when
shipment_create	A shipment record is created against the order	Standard merchant flow. The moment the warehouse "ships" the order, the customer's balance is captured.
shipment_track	A tracking number is added to the shipment	When you want to delay capture until the carrier has actually picked up — the tracking number is your proof.
manual	Admin clicks "Capture vault" on the pre-order grid	When your accounting team prefers full manual control, no auto-capture.

The trigger applies globally — pick the one that matches your operational flow. You can still manually capture any pre-order from the admin grid regardless of trigger setting.

Retry behaviour

When Cron/ProcessVaultCaptures.php runs (every 5 min by default), it picks up pre-orders flagged as vault_capture_pending:

1. Calls the gateway via Model/Service/VaultCaptureService.php using the stored vault token.
2. On success — captures recorded, pre-order moves to complete, completion email sent.
3. On gateway failure — increments attempt counter, schedules next retry at now + retry_backoff × attempts.
4. Once attempts ≥ max_attempts — the pre-order goes into vault_capture_failed, the fallback email is sent to the customer with a payment link.

Fallback email

The fallback email (preorder_vault_capture_failed, configurable in etc/email_templates.xml) tells the customer their stored card couldn't be charged and links them to My pre-orders → Pay balance, where they pay manually using whatever method they prefer.

This is the only point a customer sees the failure — the merchant doesn't have to chase, and the customer doesn't see "Your card was declined" the moment they try to ship.

Vault method resolution

Model/Service/VaultMethodResolver.php reads the order's payment method and resolves the vault provider. Supported by default:

• Stripe (stripe_payments, vault variants)
• Adyen (adyen_* cc / vault)
• Braintree (braintree, braintree_paypal)
• Authorize.net (authorizenet_directpost, vault variants)
• Magento built-in vault_payment aggregator

If your gateway isn't listed, the resolver falls back to the generic Magento_Vault interface — most modern gateways implement that and "just work". For unusual / legacy gateways, write a small plugin on VaultMethodResolver.

What gets stored

At order placement, Model/Service/VaultTokenResolver.php writes the following columns on byte8_preorder:

Column	Purpose
vault_token_id	Foreign key into vault_payment_token
vault_method_code	Gateway code (e.g. stripe_payments)
vault_capture_status	Enum — pending, succeeded, failed, fallback_sent
vault_capture_attempts	Retry counter
vault_capture_last_error	Last gateway error message — surfaced in the admin grid
vault_capture_next_attempt_at	Scheduled retry timestamp
vault_capture_completed_at	Success timestamp

The grid shows all of these as columns / filters for ops visibility.

Related

• Advanced → Vault capture deep-dive — service architecture, plugin points, gateway-specific notes.
• CLI commands — preorder:vault:process and preorder:vault:reset for ops escape hatches.
• Pre-order grid — manual capture and capture-status visibility.