Getting started
Five minutes from zero to a Vorgio invoice landing in your test inbox.
#1. Issue an API token
Go to API tokens in your Vorgio team settings (/{your-team}/api-tokens). Click the "Payment-provider integration" preset button — it pre-selects the four abilities you need:
checkouts:write— create checkoutsinvoices:read— look up invoice statusinvoices:mark-paid— needed if your shop marks invoices paid (e.g. when its own processor confirms a transfer)webhooks:manage— register your webhook endpoint
Give the token a name ("Acme Shop production"), keep the rate limit at the default 60/min for now, and click Create token.
Copy the token immediately. It's shown once — never again. The format is act_{your-team-slug}_{random40chars} prefixed with the token's numeric ID, like:
142|act_acme_shop_aB3xZ4kL...
The whole string is your Authorization: Bearer … value.
#2. Register a webhook endpoint
Go to Webhooks in your team settings. Add an endpoint URL where Vorgio should POST events:
- URL:
https://your-shop.example/webhooks/vorgio - Events: check
invoice.sentandinvoice.paid
Click Create webhook. The signing secret is shown once — copy it now. You'll need it to verify webhook signatures (see Webhooks).
For local development, expose your dev server with ngrok http 3000 (or similar) and use the public URL.
Tip: On Laravel, run
php artisan vorgio:doctor --test-webhooknow to confirm the token, abilities and webhook are wired up correctly before you write any code. See Verifying your connection.
#3. Make your first call
This single call creates a Vorgio client, issues a numbered invoice, and emails it to the customer:
1curl -X POST https://app.vorgio.example/api/v1/checkouts \
2 -H "Authorization: Bearer 42|act_acme_shop_aB3xZ4kL..." \
3 -H "Content-Type: application/json" \
4 -H "Idempotency-Key: order-1234-checkout" \
5 -d '{
6 "client": {
7 "external_id": "shop_customer_42",
8 "name": "Erika Mustermann",
9 "address": "Musterstraße 1",
10 "zip": "10115",
11 "city": "Berlin",
12 "country": "DE",
13 "email": "erika@example.com",
14 "language": "de",
15 "rate": 0,
16 "vat": 19.0,
17 "default_position_mode": "fixed"
18 },
19 "invoice": {
20 "tax_rate": 19.0,
21 "due_offset_days": 14,
22 "subject": "Order #1234",
23 "positions": [
24 {
25 "id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
26 "date": "2026-05-10",
27 "mode": "fixed",
28 "description": "1× Widget Pro",
29 "amount_cents": 4990
30 }
31 ]
32 },
33 "send": {
34 "subject": "Your invoice from Acme Shop",
35 "body": "Hi {client.name}, please find your invoice attached. — Acme Shop"
36 },
37 "metadata": {
38 "shop_order_id": "1234"
39 }
40 }'
Expected response: 201 Created with a body shaped like:
1{
2 "data": {
3 "client_id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
4 "invoice": { "id": "...", "number": "1", "amount_total": 5938, "...": "..." },
5 "mail_event_id": "1"
6 }
7}
A few seconds later, the email lands in erika@example.com with the PDF attached. A few seconds after that, your webhook endpoint receives an invoice.sent event with the same metadata.shop_order_id echoed back.
#4. Handle the webhook
Your endpoint receives a POST like:
1POST /webhooks/vorgio HTTP/1.1
2Content-Type: application/json
3Vorgio-Signature: t=1715342400,v1=4f8d2c...
4Vorgio-Event: invoice.sent
5
6{ "id": "evt_...", "type": "invoice.sent", "data": { "invoice": {...}, "client": {...} }, "metadata": {"shop_order_id": "1234"} }
The Vorgio-Signature header is HMAC-SHA256 over <unix>.<json> keyed with your webhook secret. Always verify before trusting the payload — see Webhooks for the verification snippets in PHP, JavaScript, and Python.
#What's next
You now have the full happy-path running. Next:
- Read the full /v1/checkouts reference for all the optional fields and per-language examples.
- Read Webhooks for signature verification, the retry policy, and what happens when your endpoint fails.
- If you're integrating into WooCommerce, skip ahead to the WooCommerce plugin — it wires all of the above for you.
- Before flipping to production, run through Going live.