Checkout Guard — User Manual

Overview

Checkout Guard is the safety layer around Vendure checkout and payments: Stripe manual-capture holds that actually place the order (an Authorized payment, capture or cancel from the admin, a safety capture before the authorisation expires), a bank-transfer method that carries the account details to the storefront and expires unpaid orders, a payment-event log with nightly Stripe reconciliation, session-bound anonymous order lookup, a trusted client-IP contract for server-side proxies, rate limits on the checkout mutations, and a checkout funnel.

Install & configure

yarn add @huloglobal/vendure-plugin-checkout-guard

import { CheckoutGuardPlugin, SessionBoundOrderByCodeAccessStrategy } from '@huloglobal/vendure-plugin-checkout-guard';

orderOptions: { orderByCodeAccessStrategy: new SessionBoundOrderByCodeAccessStrategy('2h') },
plugins: [
  CheckoutGuardPlugin.init({
    publicBaseUrl: 'https://shop.example.com',
    licenceKey: process.env.HULO_LICENCE_KEY_CHECKOUT_GUARD,
    stripe: { webhookSecret: process.env.STRIPE_CG_WEBHOOK_SECRET, safetyCaptureDays: 6 },
    bankTransfer: { expiryDays: 7, reminderAfterDays: 3 },
    reconciliation: { enabled: true, lookbackDays: 3 },
    trustedClientIp: { header: 'x-real-client-ip', secretHeader: 'x-checkout-guard-proxy', secret: process.env.CHECKOUT_GUARD_PROXY_SECRET },
    ops: { slackWebhookUrl: process.env.OPS_SLACK_WEBHOOK_URL, adminEmail: '[email protected]' },
  }),
]

Add CheckoutGuardPlugin.uiExtensions to compileUiExtensions. Create a payment method with the stripe-hold handler per channel that should hold rather than charge, and one with the bank-transfer handler (its arguments carry the account details shown to customers). Point a Stripe webhook at /checkout-guard/stripe-webhook with payment_intent.amount_capturable_updated, payment_intent.payment_failed and charge.succeeded.

Admin UI

Sales → Checkout Guard: Overview KPIs, Holds (capture / cancel), Bank transfers (awaiting / expired / settled, mark received), Payment events, Funnel and Settings, plus the Licence & billing card.

Licensing & tiers

Free tier: session-bound order lookup, trusted client IP, rate limits, funnel and the bank-transfer handler. Stripe holds, bank-transfer expiry and reminders, the failed-payment log, reconciliation, drift guard and ops alerts require a licence. Start the 14-day free trial or buy from the admin banner, or set HULO_LICENCE_KEY_CHECKOUT_GUARD. Buy at huloglobal.com/vendure-plugins/checkout-guard.

Troubleshooting

Hold placed but order not PaymentAuthorized: the webhook is not reaching the plugin or the secret is wrong — Stripe's dashboard shows the delivery status; the endpoint answers 5xx so Stripe retries.
Bank transfers never expire: expiry and reminders run on the worker and need a licence.
Order IP shows the proxy: the storefront proxy must send both the client-IP header and the shared-secret header configured in trustedClientIp.