Vorgio

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:

  1. Your server creates a short-lived checkout intent (with the secret token, like any other server-to-server call).
  2. Vorgio returns a single-use client_secret tied to that one intent.
  3. Your shop hands the client_secret to the browser.
  4. The browser-side widget calls POST /v1/checkout-intents/{id}/confirm with only the client_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-trip client_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 onConfirmed and, if returnUrl is 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 client block (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.paid webhooks 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_secret is 64 chars total (cs_ + 26-char ULID + _secret_ + 27 base62 chars), carrying ~161 bits of entropy in the random portion alone. It's UNIQUE-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_secret doesn'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-intents at 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.