Vorgio

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 to invoice.sent and invoice.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-webhook is 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-After on 429 responses — see Rate limits.

#Idempotency

  • [ ] Every POST /v1/checkouts carries an Idempotency-Key derived from a stable per-order identifier (e.g. wc-order-{id}-checkout).
  • [ ] You handle the Idempotency-Replay: true response header — treat as success.
  • [ ] You don't re-use the same key with a modified body.

#Webhook receiver

  • [ ] Endpoint verifies the Vorgio-Signature header before parsing the body, using hash_equals / timing-safe comparison.
  • [ ] Endpoint responds with 2xx within 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 on invoice.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 calling POST /v1/invoices/{id}/mark-paid once 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 metadata that isn't already on the invoice.

#Monitoring

  • [ ] Alerts on:
    • 5xx response rate from your POST /v1/checkouts calls
    • 429 response rate (rate-limit pressure)
    • Webhook endpoint 5xx response rate
    • Webhook delivery age (Vorgio events older than ~1h that weren't acknowledged)
  • [ ] 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:

  1. 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.
  2. Verify in Vorgio that the client + invoice were created and the email landed in your test inbox.
  3. Verify the invoice.sent webhook arrived at your endpoint and the order moved to the configured status.
  4. Pay the invoice (or mark it paid in Vorgio for the smoke test).
  5. Verify the invoice.paid webhook arrived and the order moved to processing/completed.
  6. 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. 🚀