JS widget — vorgio.js
A browser-side flow that confirms a Vorgio invoice without ever holding your secret API token. Use it when:
- Your shop is mostly client-side JavaScript and you don't want to round-trip the whole order through your server, OR
- You want a hosted checkout-confirmation UI instead of writing your own.
The bundle lives at vorgio-app/vorgio-js and is published to npm as @vorgio-app/vorgio-js. Until the public Vorgio launch the canonical cdn.vorgio.example/v1/vorgio.js URL is reserved; pin to the npm-mirror CDN (unpkg / jsDelivr) in the meantime.
#Why a separate flow
Vorgio API tokens are secret. They unlock everything in your team. Putting one in browser-side JavaScript would let anyone reading your page's network tab create invoices on your behalf, look up your customer list, etc. — game over.
The widget therefore can't call POST /v1/checkouts directly. Instead:
- Your server creates a short-lived checkout intent (with the secret token, like any other server-to-server call).
- Vorgio returns a single-use
client_secrettied to that one intent. - Your shop hands the
client_secretto the browser. - The browser-side widget calls
POST /v1/checkout-intents/{id}/confirmwith only theclient_secret(no Vorgio token). On success, Vorgio runs the same flow as/v1/checkouts(find-or-create client, create invoice, send mail) and returns the invoice.
This is the same pattern Stripe popularised with PaymentIntents.
#The flow
1Shop server Browser Vorgio
2 │ │ │
3 │ POST /v1/checkout-intents │ │
4 │ Bearer act_… │ │
5 │ body: { client, invoice, │ │
6 │ send, return_url, │ │
7 │ metadata } │ │
8 ├────────────────────────────────────────────────────────────▶│
9 │ ← 201 { id, client_secret, │ │
10 │ expires_at } │ │
11 │ │ │
12 │ render the page with the │ │
13 │ client_secret in scope │ │
14 │ │ │
15 │ POST /v1/checkout-intents/{id}/confirm │
16 │ body: { client_secret } │
17 │ ├──────────────────────────▶│
18 │ │ ← 200 { invoice, status, │
19 │ │ return_url } │
20 │ │ │
21 │ optional redirect to return_url │
22 │ ← invoice.sent webhook ──────────────────────────────────────┤
23 │ ← invoice.paid webhook (later, on mark-paid) ────────────────┤
#Step 1 — Create the intent server-side
In your existing checkout handler, where you would have called POST /v1/checkouts, instead call:
1// Node/TypeScript
2const intent = await fetch('https://app.vorgio.example/api/v1/checkout-intents', {
3 method: 'POST',
4 headers: {
5 'Authorization': `Bearer ${process.env.VORGIO_TOKEN}`,
6 'Content-Type': 'application/json',
7 'Idempotency-Key': `order-${order.id}-intent`,
8 },
9 body: JSON.stringify({
10 client: { /* … same shape as /v1/checkouts */ },
11 invoice: { /* … */ },
12 send: { /* … */ },
13 return_url: `https://shop.example/order/${order.id}/thanks`,
14 metadata: { shop_order_id: String(order.id) },
15 }),
16}).then(r => r.json());
17
18return res.json({
19 clientSecret: intent.data.client_secret, // hand this to the browser
20 expiresAt: intent.data.expires_at,
21});
The response:
1{
2 "data": {
3 "id": "01jr7q9a4z3sx8b2yhf6e0wk5j",
4 "client_secret": "cs_01jr7q9a4z3sx8b2yhf6e0wk5j_secret_8h3Jf2pQwR…(27 chars)…",
5 "expires_at": "2026-05-11T08:30:00+00:00",
6 "return_url": "https://shop.example/order/1234/thanks"
7 }
8}
Properties of client_secret:
- Format:
cs_{intent_id}_secret_{27 random chars}(Stripe-style). The intent id is embedded so the JS widget can derive the URL path from a single token — your HTML only has to round-tripclient_secret. - Tied to one intent, one team, one successful confirm. A second confirm returns 409.
- Expires 30 minutes after creation. A confirm against an expired intent returns 410.
- Treat it like a short-lived URL — it's not as secret as the API token, but it's not a public ID either.
#Step 2 — Browser confirms the intent with vorgio.js
Load the bundle and call Vorgio.checkouts.create(...):
1<script src="https://unpkg.com/@vorgio-app/vorgio-js@0.1.0/dist/vorgio.js"></script>
2<div id="vorgio-checkout"></div>
3<script>
4 Vorgio.checkouts.create({
5 clientSecret: 'cs_…_secret_…', // from your server
6 container: '#vorgio-checkout',
7 locale: 'de', // de | en — overrides client.language for widget chrome only
8 returnUrl: 'https://shop.example/order/1234/thanks',
9 onConfirmed: ({ invoiceId, invoiceNumber }) => { /* analytics, inventory */ },
10 onError: (error) => { console.error(error); }, // RFC 7807 shape: type, title, status, detail
11 });
12</script>
ESM consumers can import { checkouts } from '@vorgio-app/vorgio-js' and call checkouts.create({...}) with the same options.
#What the widget renders
A small card inside the container with one of these states:
- idle — a localized "Complete order" button.
- pending — disabled button + spinner while the confirm request is in flight.
- success — green check + "Invoice on its way to {email}". Calls
onConfirmedand, ifreturnUrlis set, redirects 1.5 seconds later. - error — red banner with a localized message and the RFC 7807 details. Calls
onError(problem).
The widget injects its own scoped CSS once per page (selector prefix .vorgio-checkout) so it does not collide with the shop's styles.
#Calling the endpoint directly (no bundle)
If you'd rather not load the bundle, you can call the confirm endpoint from your own frontend — that's exactly what the widget does internally:
1<script>
2 async function confirmCheckout(clientSecret, intentId) {
3 const res = await fetch(`https://app.vorgio.example/api/v1/checkout-intents/${intentId}/confirm`, {
4 method: 'POST',
5 headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
6 body: JSON.stringify({ client_secret: clientSecret }),
7 });
8
9 if (!res.ok) {
10 const problem = await res.json();
11 throw new Error(problem.detail || problem.title);
12 }
13
14 const { data } = await res.json();
15 if (data.return_url) {
16 window.location.href = data.return_url;
17 }
18 return data;
19 }
20</script>
CORS for /api/v1/checkout-intents/*/confirm is open to all origins (*). The endpoint still requires a valid client_secret to do anything — see security notes below.
#Error cases
All responses follow the RFC 7807 shape (application/problem+json).
| Status | type |
Meaning |
|---|---|---|
| 404 | not-found |
Intent ID doesn't exist, OR client_secret doesn't match. (Both collapsed on purpose so IDs aren't guessable by enumeration.) |
| 409 | conflict |
Intent has already been confirmed once. Replays always fail. |
| 410 | gone |
Intent has expired (30 min after creation). Mint a new one. |
| 422 | validation-failed |
client_secret missing or empty. |
| 429 | rate-limit-exceeded |
IP-based rate limit hit (≥60 req/min per IP). |
#What the widget does NOT do
- Does not collect payment instrument data. No card fields, no SCA, no PSD2. The customer pays by bank transfer using the IBAN on the invoice.
- Does not collect address data. That's already in the intent's
clientblock (which you set server-side). - Does not handle "save for later" / "pay another way". It's a one-shot confirmation surface. If the customer wants a different payment method, your shop's checkout UI handles that, not the widget.
- Does not poll for payment confirmation. Use
invoice.paidwebhooks server-side.
#Security notes
- The Vorgio API token never leaves your server. It only shows up in step 1 (intent creation) — never in the browser.
- The
client_secretis 64 chars total (cs_+ 26-char ULID +_secret_+ 27 base62 chars), carrying ~161 bits of entropy in the random portion alone. It'sUNIQUE-indexed and consumed atomically (UPDATE … SET confirmed_at = now() WHERE confirmed_at IS NULL). Races aren't possible. - Confirm responses leak no difference between "intent doesn't exist" and "
client_secretdoesn't match" — both return 404. Intent IDs cannot be probed for existence. - Expired intents (older than 30 min + 24 h grace) are deleted nightly by
accounting:purge-checkout-intentsat 03:15.
#Source
The server-side endpoints live in App\Http\Controllers\Api\V1\CheckoutIntentController in this repository. The browser bundle lives at vorgio-app/vorgio-js and ships as @vorgio-app/vorgio-js on npm. The aspirational https://cdn.vorgio.example/v1/vorgio.js CDN URL is reserved for the public Vorgio launch — until then pin to unpkg or jsDelivr at a specific version.