Vorgio

WooCommerce plugin — vorgio-for-woocommerce

A WordPress plugin that turns Vorgio into a checkout payment option in WooCommerce shops. Zero code for the merchant — install, paste a token, paste a webhook secret, pick a fulfilment trigger.

The plugin bundles the vorgio-php SDK with namespaces prefixed via PHP-Scoper so it cannot collide with another plugin that ships a different SDK version.

#Install

Two routes:

 1# Option 1 — clone into wp-content/plugins
 2cd wp-content/plugins
 3git clone https://github.com/vorgio/vorgio-for-woocommerce
 4cd vorgio-for-woocommerce && composer build  # produces dist/vorgio-for-woocommerce-<version>.zip
 5
 6# Option 2 — upload the release ZIP via WP admin
 7# WP admin → Plugins → Add New → Upload Plugin → vorgio-for-woocommerce-<version>.zip

Activate Vorgio for WooCommerce from the plugins page.

#Configure

In the WordPress admin: WooCommerce → Settings → Payments → Pay by invoice (Vorgio).

Field What to put
API token Your Vorgio token (act_…). Issued from your Vorgio team's API tokens page using the "Payment-provider integration" preset.
Webhook secret The signing secret shown when you added an endpoint at https://your-shop.example/wp-json/vorgio/v1/webhook in your Vorgio team's Webhooks page.
Fulfilment trigger When the WC order should auto-progress past on-hold. Two choices: On invoice sent (immediately on invoice.sent webhook — trust the customer to pay later) or On invoice paid (only when the merchant marks the invoice paid in Vorgio).
Status after trigger The WooCommerce status to set when the trigger fires — processing (default) or completed.
Default language de or en — the language Vorgio uses to render the invoice email and PDF for customers without a per-customer override.
Sender name override Optional — overrides the merchant's default sender name on Vorgio mails.
Payment terms (days) Forwarded as due_offset_days on the Vorgio invoice.
Tax rate (%) Forwarded as tax_rate. Vorgio computes invoice totals from this single rate.

Save. The "Pay by invoice (Vorgio)" option now appears on the WC checkout page.

To replace the webhook secret, click Rotate secret on the endpoint's row in Vorgio and paste the new secret into Webhook secret here within 24 hours — until then Vorgio signs with both secrets, so no order update is missed (see Webhooks).

#How it works

When a customer selects "Pay by invoice (Vorgio)" at checkout:

  1. WC fires woocommerce_checkout_order_processed.
  2. The plugin maps the WC order → Vorgio checkout payload:
    • WC customer → Vorgio client (with external_id = "wc_customer_{customer_id}" for logged-in shoppers, or "wc_order_{order_id}" for guest checkouts)
    • WC line items → invoice positions (mode fixed, amount_cents from line subtotal)
    • WC shipping lines and fees → additional positions
    • WC discounts → a single negative-amount "Discount" position
    • WC order ID → metadata.wc_order_id
  3. Calls POST /v1/checkouts server-side with idempotency key wc-order-{id}-{order_key}.
  4. Sets the WC order to on-hold and stores the Vorgio invoice ID, number and URL on the order meta.
  5. The customer sees the WooCommerce "Order received" page and gets the Vorgio invoice email separately.

Later, when Vorgio fires webhooks:

  • invoice.sent → if your fulfilment trigger is "On invoice sent", the WC order moves to the configured status after trigger. Otherwise an order note is recorded.
  • invoice.paid → the order is marked paid (payment_complete()) and, if the trigger is "On invoice paid", moved to the configured status.

#Order admin

In the WC order edit screen the plugin surfaces:

  • Vorgio invoice number in the order details panel
  • "View in Vorgio" link (deep-links to the invoice in your Vorgio team)
  • A failure reason, if checkout failed against Vorgio

#Failure UX

  • If the Vorgio call fails at checkout time (network error, 4xx, 5xx), the customer sees a friendly "We couldn't process your invoice" message. The WC order is marked failed with a structured private note describing the problem (validation field errors, rate-limit retry-after, RFC 7807 type + detail) for the merchant to investigate.
  • If a webhook delivery fails (your endpoint is down), Vorgio retries per the documented schedule and auto-disables after 7 failures (~ 2 days). Re-register the endpoint from the Vorgio Webhooks page once your site is healthy.

#Multilingual

The plugin sets client.language from the order's wp_user_locale meta when present (de* → de, en* → en); otherwise it falls back to the Default language setting.

#HPOS

The plugin declares HPOS (Custom Order Tables) compatibility. Both legacy post-table orders and HPOS shops are supported.

#Compatibility

  • WordPress 6.4+
  • WooCommerce 8.0+
  • PHP 8.2+

#Source

github.com/vorgio/vorgio-for-woocommerce. The plugin is licensed GPL-2.0-or-later.