Going live — production checklist
Run this checklist end-to-end before flipping your shop to use Vorgio in production.
#Tokens & secrets
- [ ] Production token issued from the Payment-provider integration preset on your team's API tokens page.
- [ ] Token is stored only in your secrets manager / environment, never in source control. (Search your repo for
act_to be sure.) - [ ] Webhook endpoint registered in your Vorgio team's Webhooks page with the
https://URL of your production shop, subscribed toinvoice.sentandinvoice.paid. - [ ] Webhook signing secret stored in your secrets manager.
- [ ] Separate token for staging/dev, pointed at a separate Vorgio team. Never share tokens between environments.
- [ ]
php artisan vorgio:doctor --test-webhookis all green against production (PHP SDK ≥ 0.3.0) — confirms the token is live, carries the right abilities, and the webhook is registered and actually receiving signed events. See Verifying your connection.
#Rate limit
- [ ] Token's rate limit set to a value comfortably above your expected peak. Default 60/min is fine for most shops; bump to 120 or 300 if you expect bursty traffic (sales, marketing emails). Floor is 30/min.
- [ ] Your client code respects
Retry-Afteron429responses — see Rate limits.
#Idempotency
- [ ] Every
POST /v1/checkoutscarries anIdempotency-Keyderived from a stable per-order identifier (e.g.wc-order-{id}-checkout). - [ ] You handle the
Idempotency-Replay: trueresponse header — treat as success. - [ ] You don't re-use the same key with a modified body.
#Webhook receiver
- [ ] Endpoint verifies the
Vorgio-Signatureheader before parsing the body, usinghash_equals/ timing-safe comparison. - [ ] Endpoint responds with
2xxwithin 30 seconds. Heavy work is queued, not done inline. - [ ] Endpoint is idempotent on
event.id— duplicate deliveries don't double-fulfil. - [ ] Your monitoring alerts on the webhook endpoint going down (it's the only way Vorgio tells you the invoice was paid).
#Order semantics
- [ ] You've decided whether your shop fulfils on
invoice.sent(trust the customer) or only oninvoice.paid(cautious). Document the choice in your runbook. - [ ] If "on
invoice.paid": the merchant has a workflow for marking invoices paid promptly when the bank transfer arrives — either manually in the Vorgio UI, or by your shop callingPOST /v1/invoices/{id}/mark-paidonce its own processor confirms.
#Error UX
- [ ] At checkout time: if the Vorgio call fails, the customer sees a friendly message ("We couldn't process your invoice — please try again or pick a different payment method") — not a stack trace, not the RFC 7807 envelope.
- [ ] At fulfilment time: webhook failures are surfaced to the merchant (admin email / dashboard), not silently swallowed.
#Privacy / data handling
- [ ] Your privacy policy mentions that customer billing data (name, address, email) is shared with Vorgio for the purpose of issuing the invoice.
- [ ] If your shop is in the EU: you have a Auftragsverarbeitungsvertrag (AVV) / Data Processing Agreement in place with Vorgio. (Vorgio provides the standard one — contact support.)
- [ ] You don't put PII in
metadatathat isn't already on the invoice.
#Monitoring
- [ ] Alerts on:
- 5xx response rate from your
POST /v1/checkoutscalls - 429 response rate (rate-limit pressure)
- Webhook endpoint 5xx response rate
- Webhook delivery age (Vorgio events older than ~1h that weren't acknowledged)
- 5xx response rate from your
- [ ] Dashboards for the above with thresholds your on-call team understands.
#Smoke test
Run this in production with a real card / real bank transfer for one tiny order:
- Place a real checkout order on your live shop with "Pay by invoice (Vorgio)". Use a small amount you don't mind eating if something goes wrong.
- Verify in Vorgio that the client + invoice were created and the email landed in your test inbox.
- Verify the
invoice.sentwebhook arrived at your endpoint and the order moved to the configured status. - Pay the invoice (or mark it paid in Vorgio for the smoke test).
- Verify the
invoice.paidwebhook arrived and the order moved toprocessing/completed. - Verify the order's view-page in your shop shows the Vorgio invoice number / "View in Vorgio" link.
If all six steps pass, you're live. Roll out to all customers.
#Rollback plan
- [ ] You can disable the "Pay by invoice (Vorgio)" payment method in your shop's admin in under 60 seconds without a deploy. (For WooCommerce, this is a checkbox in the WC payments settings.)
- [ ] You have a runbook for "Vorgio is down" — typically: disable the payment option, surface a banner, switch to your fallback payment provider.
#When to involve Vorgio support
Reach out before launch if:
- You expect more than ~ 1000 invoices/day (might need rate-limit / infra tuning).
- You're integrating into a platform Vorgio doesn't have an official plugin for (yet) — Vorgio may want to learn from your integration.
- You have legal questions about retention, AVV, or e-invoice formats (XRechnung, ZUGFeRD).
- Your shop processes orders in a non-EUR currency. (Vorgio is EUR-only today.)
You're done. Welcome to the integration. 🚀