Integrating your store with Siz

For developers at ticketing merchants (cinemas, airlines…) who want AI assistants to book through Siz. This guide summarizes the Merchant Agent API v1.4: Siz calls your API, users pay you directly, and Siz shows the payment instructions and tickets right in the chat.

For end users, see the User guide. The sample merchants referred to here are a cinema (base path /agent/v1) and an airline (/api/agent/v1).

1. Overview

Siz is the MCP server AI assistants connect to. When a user asks their assistant to book, Siz calls your agent API with signed requests. Money never passes through Siz: users pay you directly.

  1. AI assistant → SizThe user asks the assistant; the assistant calls Siz's MCP tools (search showtimes, view seats, hold).
  2. Siz → your agent APIRFC 9421 signed requests: GET /offers, seatmap, POST /checkout-sessions to hold seats.
  3. The user chooses how to paySiz calls payment-method; you return VietQR instructions or a payment link; Siz checks them against the registry and shows them on the card in the chat.
  4. The user pays on your sideA bank transfer or the payment gateway's page. You reconcile and move the session to completed.
  5. Siz reads it back and shows the ticketThe card in the chat polls Siz every few seconds; each time Siz reads GET /checkout-sessions/{id}. Once completed, Siz calls GET …/ticket.
  6. Check-in at the gateStaff scan the QR code; you mark the ticket as used.

Ground rules:

  • Siz never pays or holds money. An order is only “paid” when you report completed.
  • Every string you return is treated as data: Siz sanitizes it before display and drops unknown fields.
  • Siz does not receive passengers' personal data (date of birth, passport): users enter it on your page.
  • Everything in v1.4 is additive: a v1.3 merchant that sends no payment block still works, and users pay via continue_url.

2. Registering with Siz

The Siz operator adds your store to the static registry merchants.yaml. Siz never derives URLs from requests; every address comes from here. Send the operator the following values:

merchants.yaml
merchants:
  - merchant_id: vexinh                 # ^[a-z0-9][a-z0-9-]{0,62}$, unique
    vertical: cinema                    # ^[a-z]{2,32}$, e.g. cinema, flight
    display_name: Vé Xinh Cinema        # optional, ≤ 100 chars, shown on the permission page
    api_base: https://api.vexinh.example/agent/v1
    checkout_origin: https://vexinh.example
    link_origin: https://vexinh.example # optional, defaults to checkout_origin
    concurrency_budget: 20              # 1–1000 concurrent requests to you
    ttl_max_seconds: 600                # 1–900, your maximum hold time
    payment:
      vietqr_accounts:
        - bank_bin: "970436"            # 6 digits, quoted
          account_number: "0123456789"  # 1–19 letters or digits, exactly as in the QR
      link_hosts: ["checkout.stripe.com", "pay.vnpay.vn"]
FieldRule
merchant_idStore ID, ^[a-z0-9][a-z0-9-]{0,62}$, unique.
display_nameName shown on the permission and connections pages. Optional, at most 100 chars; defaults to merchant_id.
api_baseAbsolute https URL of the agent API root (Siz appends /offers, /checkout-sessions…). Siz does not follow redirects.
checkout_originhttps origin of the web app serving /checkout-sessions/:id, /tickets/:id and the sandbox pages. continue_url and ticket_url must be on this origin, and its host is always allowed as a payment-link host.
link_originhttps origin serving the /agent-link page (the web app, not the API). Optional, defaults to checkout_origin.
verticalIndustry, ^[a-z]{2,32}$, e.g. cinema, flight. For now each vertical is served by a single merchant.
concurrency_budget, ttl_max_secondsMaximum concurrent requests Siz sends you (1–1000); the maximum hold time you allow (1–900 seconds). Siz sends exactly this value as ttl_seconds when holding seats.
payment.vietqr_accountsUp to 10 receiving accounts {bank_bin, account_number}: bank_bin exactly 6 digits, account_number 1–19 letters or digits. Siz only shows VietQR codes whose account is on this list; if it is empty, VietQR is never shown.
payment.link_hostsUp to 20 payment gateway hosts, lowercase, with no scheme, port, path or wildcard. Matched exactly: evil.stripe.com does not match checkout.stripe.com.

The Siz operator sends you back:

  • the keyid and Ed25519 public key to verify signatures (see section 3);
  • the aig-web origin, to put on your list of places the /agent-link page may return to (section 8).

The payment block is the anti-spoofing anchor: even if your server is compromised, Siz will not show a QR to another account or a link to another site. When you change receiving accounts or payment gateways, have the registry updated first, otherwise that method is dropped (logged as account_not_allowed, link_host). Instructions already stored for open orders keep showing until the session changes, for at most one hold cycle (≤ 20 minutes).

3. Request signing

Every request Siz sends to your agent API is signed with Ed25519 under a subset of RFC 9421 (HTTP Message Signatures). Siz's caller is "aig".

Headers of a request with a body
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "idempotency-key");created=1790000000;expires=1790000060;nonce="AAECAwQFBgcICQoLDA0ODw";keyid="aig-dev-1";alg="ed25519"
Signature: sig1=:<base64 of the 64-byte Ed25519 signature>:
Content-Digest: sha-256=:<base64 of sha256(body)>:
Idempotency-Key: 5b7c1a52-0d7e-4c55-9c1e-3f7a2a0e9b11
  • Signed components, in this exact order: "@method" "@target-uri", then "content-digest" if there is a body, then "idempotency-key" if that header is present.
  • Content-Digest = sha-256=:base64(sha256(body)): (RFC 9530). Check it against the raw bytes of the body before parsing JSON.
  • @target-uri = your configured PUBLIC_ORIGIN (no trailing /) + path + ?query exactly as sent (Express: PUBLIC_ORIGIN + req.originalUrl). Never use the Host header (tunnels and proxies may change it).
  • @method in upper case. expires − created ≤ 60 seconds; accept created within ±30 seconds of your clock; reject when now > expires.
  • A nonce is single-use: store it (for example in a collection with a unique index and a 300-second TTL).
  • Any failure → 401 problem SIGNATURE_INVALID; detail says which step failed and never echoes the signature. Do not log signatures.

The string to sign (signature base), lines joined with \n, no trailing newline:

Signature base
"@method": POST
"@target-uri": https://api.vexinh.example/agent/v1/checkout-sessions
"content-digest": sha-256=:k6I5cakU5erL8KjSUVTNownDwccvu5kU1Hxg88toFYg=:
"idempotency-key": 5b7c1a52-0d7e-4c55-9c1e-3f7a2a0e9b11
"@signature-params": ("@method" "@target-uri" "content-digest" "idempotency-key");created=1790000000;expires=1790000060;nonce="AAECAwQFBgcICQoLDA0ODw";keyid="aig-dev-1";alg="ed25519"

Getting Siz's public key

Siz does not publish its request-signing key through an endpoint. The Siz operator sends you the keyid and the public key (32 raw bytes, base64) over a trusted channel. Put them in an environment variable, mapping each keyid to the caller aig:

.env
# RFC 8032 test public key (test 1), only to illustrate the format
AIG_PUBLIC_KEYS='{"aig-dev-1":{"caller":"aig","key":"11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo="}}'
  • When Siz rotates keys, keep both the current and the previous keyid, both pointing to the caller aig.
  • Every scope (idempotency keys, account links, session ownership) is tied to the caller, not to the keyid, so rotating keys never loses sessions or links.
  • Testing: use the RFC 8032 test 1 seed 9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60, the body {"hello":"world"} and the signature base above; Ed25519 is deterministic, so the signature must equal the contract's reference vector.

4. API reference (v1.4)

Every body is UTF-8 JSON, limited to 32 KB. Timestamps are RFC 3339 with a +07:00 offset. Money is an integer number of VND with "currency": "VND". The agent API sends no CORS headers and reads no cookies. Always set the Date header (Siz uses it to measure clock skew).

MethodPathPurpose
GET/offersSearch showtimes/flights
GET/offers/{offer_id}/seatmapSeat map
POST/checkout-sessionsHold seats (Idempotency-Key required, ≤ 128 chars) → 201
GET/checkout-sessions/{id}Read a session
GET/checkout-sessions?idempotency_key=Look up a session by key (kept ≥ 72 hours) · 202 in progress · 404
PUT/checkout-sessions/{id}Change seats/quantity (Idempotency-Key required)
POST/checkout-sessions/{id}/cancelRelease seats
POST/checkout-sessions/{id}/completeAlways 403 FORBIDDEN for agents: an agent never completes a session itself
POST/checkout-sessions/{id}/payment-methodv1.4: choose a payment method (Idempotency-Key required)
GET/checkout-sessions/{id}/ticketv1.4: ticket of a paid session
POST/links/exchangeExchange an account-link code for a customer_ref

Offers and seatmap

Cinema: query date (required, YYYY-MM-DD), movie (slug), cinema_id, q (≤ 100 chars, searches film titles, case- and accent-insensitive), limit (1–50, default 20), cursor. Flights: from, to (IATA codes), date required; class (economy|business|first), quantity (1–9), limit, cursor. Return only offers that have not started, sorted by starts_at then offer_id.

GET /offers (cinema)
{ "items": [
  { "offer_id": "6ab2a0d475d43ed461ca47c3", "vertical": "cinema",
    "title": "Mưa Đỏ", "starts_at": "2026-09-26T19:30:00+07:00",
    "venue": { "id": "6ab15635ed9be24a4df9ee12", "name": "Rạp Demo" }, "room": "R2",
    "movie": "mua-do",
    "prices": [{ "class": "standard", "amount": 60000 }, { "class": "vip", "amount": 78000 }],
    "currency": "VND", "available_count": 37 } ],
  "next_cursor": null }

Flights: offer_id = <flightId>:<class>, ends_at is the arrival time, optional price_estimate (total including taxes and fees for quantity).

GET /offers/{offer_id}/seatmap
{ "offer_id": "6ab2a0d475d43ed461ca47c3", "revision": 17, "currency": "VND",
  "prices": { "standard": 60000, "vip": 78000 },
  "seats": [ { "id": "6ab15635ed9be24a4df9ee17", "label": "A1", "class": "standard", "available": true } ],
  "layout": { "front_row": "A" } }

revision increases with every seat hold/release/sale and is informational only. layout.front_row (cinema only, optional) is the row closest to the screen.

Checkout session: create, read, change, cancel

Create a session
POST /checkout-sessions
Idempotency-Key: 5b7c1a52-0d7e-4c55-9c1e-3f7a2a0e9b11

{ "customer_ref": "mref_…",
  "line_items": [ { "offer_id": "6ab2a0d475d43ed461ca47c3", "quantity": 2,
                    "seats": ["<seat id>", "<seat id>"] } ],
  "ttl_seconds": 600 }
  • Exactly one line item. Cinema: seats required, quantity = number of seats. Flights: seats optional; if missing, you assign seats yourself.
  • ttl_seconds is clamped to [60, your TTL_MAX]. Limits shared by web and agent: seats per customer per showing, ≤ 3 live sessions per customer (over → 422 QUOTA_EXCEEDED).
  • Idempotency per (caller, key): same key + same body → the stored session (200); same key + different body → 409 IDEMPOTENCY_MISMATCH; still holding seats → 202 {"status":"in_progress"}.
  • Seats held by someone else → 409 SEAT_UNAVAILABLE with seats, revision; never hold partially.
  • PUT changes seats atomically (holds the new seats and releases dropped ones in one go), does not extend expires_at, only while open; adds a price_changed message if the total changes.
  • cancel: open → canceled (releases seats); already canceled/expired → 200 unchanged; in_payment or completed → 409 INVALID_STATE.
  • Lazy expiry: on every read, an open/in_payment session past expires_at is reported as canceled with cancel_reason: "expired".
Session object (v1.4, VietQR selected)
{ "id": "cs_2b9f…",
  "status": "in_payment",
  "cancel_reason": null,
  "customer_ref": "mref_…",
  "line_items": [ { "offer_id": "…", "quantity": 2,
      "seats": [ { "id": "…", "label": "F7", "class": "standard" },
                 { "id": "…", "label": "F8", "class": "standard" } ],
      "unit_amounts": [60000, 60000], "amount": 120000 } ],
  "totals": { "subtotal": 120000, "fees": 0, "total": 120000, "currency": "VND" },
  "expires_at": "2026-09-26T19:12:00+07:00",
  "continue_url": "https://vexinh.example/checkout-sessions/cs_2b9f…",
  "state_version": 4,
  "offer": { "title": "Mưa Đỏ", "starts_at": "2026-09-26T19:30:00+07:00",
             "venue": "Rạp Demo", "room": "R2" },
  "payment": {
    "methods": [
      { "id": "vietqr", "type": "vietqr", "label": "Chuyển khoản VietQR", "fee": 0 },
      { "id": "stripe", "type": "payment_link", "provider": "stripe", "label": "Thẻ quốc tế", "fee": 0 }
    ],
    "selected": {
      "method_id": "vietqr",
      "expires_at": "2026-09-26T19:12:00+07:00",
      "vietqr": { "payload": "000201…6304ABCD", "amount": 120000, "currency": "VND",
                  "reference": "DEMO7K2Q9A4F", "bank_bin": "970436",
                  "account_number": "0123456789", "account_name": "CONG TY VE XINH" }
    }
  } }

status: open | in_payment | completed | canceled | failed; cancel_reason: released | expired | user | refunded. booking_reference only when completed. state_version increases on every change, including every change to the payment block.

The payment block

  • Present in every response that contains a session. For completed/canceled/failed sessions it is {} (or only buyer_input for flights).
  • buyer_input { "required": true, "completed": false }: only when the vertical needs buyer data (passengers). completed becomes true once your page has saved the passengers.
  • methods: only when the session is open/in_payment and buyer input is not needed or is done. id ^[a-z0-9_]{1,32}$; type vietqr | payment_link; label ≤ 60; provider required for payment_link; fee is for display only (the VietQR amount always equals totals.total, so fold fees into the totals when a method is selected).
  • selected: after selection, exactly one of vietqr / payment_link. reference ^[A-Z0-9]{6,25}$; account_name ≤ 70; expires_at RFC 3339.
selected with a payment link
"selected": {
  "method_id": "stripe",
  "expires_at": "2026-09-26T19:12:00+07:00",
  "payment_link": { "url": "https://checkout.stripe.com/c/pay/…", "provider": "stripe" }
}

POST payment-method

Choose a method
POST /checkout-sessions/cs_2b9f…/payment-method
Idempotency-Key: cs_2b9f…:pm:3f0c9a1e5b7d4c2a8e6f1b3d5a7c9e0f

{ "method_id": "vietqr" }
  • The first selection moves open → in_payment and extends the hold once: expires_at = min(max(expires_at, now + 5 min), created_at + 20 min).
  • Selecting again (any method) is allowed while open/in_payment: it invalidates the old instructions (the old reference can no longer be confirmed, old tokens are rejected) and issues new ones.
  • Same key + same body → 200 with the current session (no new instructions); same key + different body → 409 IDEMPOTENCY_MISMATCH. Siz sends keys of the form <checkout_id>:pm:<32 hex>. Errors are bound to the key just like successes.
  • Errors: 409 INVALID_STATE (already done/canceled/failed, or passengers not entered yet with reason: "buyer_input_required"), 410 HOLD_EXPIRED, 400 INVALID_ARGUMENT field: "method_id", 404 NOT_FOUND.

GET ticket

200 with the ticket once the session has been paid (even after a refund: status: refunded); 409 INVALID_STATE with session_status if not yet; 404 NOT_FOUND. Field details are in section 7.

POST links/exchange

Body {code, link_request_id} → 200 {customer_ref}. See section 8.

Errors (problem+json)

Content-Type: application/problem+json, body {type, title, status, code, detail, …extras}. Siz tells 409 errors apart by code, not by status.

HTTPcodeWhen
400INVALID_ARGUMENTInvalid data, with field (body > 32 KB: field: "body")
401SIGNATURE_INVALIDBad signature (section 3)
403CUSTOMER_NOT_LINKEDUnknown customer_ref, or revoked for this caller
403FORBIDDENFor example, an agent calling /complete
404NOT_FOUNDNo such offer/session, or another caller's session; unknown, expired or used link code
409SEAT_UNAVAILABLESeats already held, with seats, revision
409IDEMPOTENCY_MISMATCHSame Idempotency-Key, different body
409INVALID_STATEWrong state, with session_status and possibly reason: buyer_input_required, reference_mismatch (ignore unknown values)
409ALREADY_USEDYour check-in API (not the agent API): a ticket scanned a second time
410HOLD_EXPIREDThe session is past expires_at
422QUOTA_EXCEEDEDSeat or live-session limit exceeded, with limit
503MERCHANT_UNAVAILABLEDatabase error…
Example
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{ "type": "https://zillexa.vn/problems/invalid-state",
  "title": "Invalid state", "status": 409, "code": "INVALID_STATE",
  "detail": "passengers must be entered on the checkout page first",
  "session_status": "open", "reason": "buyer_input_required" }

5. VietQR rules

You generate the VietQR payload (NAPAS 247, EMVCo merchant-presented mode). Siz parses the TLV and drops the method if any rule is broken:

  • Top-level tags must belong to {00, 01, 38, 52, 53, 54, 58, 59, 60, 62, 63}. Any other tag invalidates the whole payload.
  • 00 must come first and 63 last; no data object may have an empty value.
  • No 55/56/57 (tip and convenience fees: they make the amount actually transferred differ from 54) and no second account template (02–51 other than 38).
  • 00=01, 01=12 (dynamic QR), 38 = { 00=A000000727, 01 = { 00=bank_bin, 01=account_number }, 02=QRIBFTTA }, 53=704, 58=VN.
  • 62.08 equals reference exactly (not merely contains it).
  • 63 = CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) computed over the payload up to and including 6304, 4 upper-case hex digits.
  • 54 = integer VND amount = vietqr.amount = the session's totals.total.
  • bank_bin/account_number in the QR equal the JSON fields and are listed in the registry's payment.vietqr_accounts.
  • Payload ≤ 512 printable ASCII chars. If it is invalid, Siz drops the instructions (never fixes them), logs payment_instruction_rejected with a reason code (never the payload, account number or URL), and the user still has continue_url.
Example: 150,000 VND to 970436 / 0123456789, reference DEMO7K2Q9A4F
00020101021238540010A00000072701240006970436011001234567890208QRIBFTTA530370454061500005802VN62160812DEMO7K2Q9A4F63048BA8
TagValueMeaning
0001Payload format version
0112Dynamic QR (single use)
3800·10·A000000727 01·24·(00·06·970436 01·10·0123456789) 02·08·QRIBFTTANAPAS GUID, BIN 970436, account 0123456789, fast transfer to account service
53704VND
54150000Amount = the session total
58VNCountry
6208·12·DEMO7K2Q9A4F62.08 = reference (transfer message)
638BA8CRC16

6. Payment links

For a payment_link method, Siz only shows selected.payment_link.url when:

  • the scheme is https, it is ≤ 2048 chars long, and it has no userinfo (user@) or control characters;
  • the host exactly equals a host in payment.link_hosts, or the host of checkout_origin (your sandbox page);
  • provider matches ^[a-z0-9_]{1,32}$ and equals the method's provider.

The card in the chat shows a button to open the link and a QR code of the URL. The user pays on the gateway's page; you confirm through the gateway's webhook and move the session to completed.

7. Tickets and check-in

FieldRule
booking_referenceBooking reference ^[A-Za-z0-9_-]{1,64}$ (cinema: booking code, airline: PNR)
statusvalid | used | canceled | refunded; used_at once scanned
entry_code{ "format": "qr", "payload": "…" }, required when valid; ≤ 512 printable ASCII chars, signed by you
title, venuetitle ≤ 200; venue.name ≤ 200, venue.address ≤ 300
issued_at, starts_at, ends_atRFC 3339
instructions≤ 200 chars, plain text
ticket_urlhttps on checkout_origin (if wrong, Siz only drops the URL)
Cinema ticketsformat ≤ 60, room ≤ 100, seats[] (labels ≤ 16), quantity
Flight ticketsflight_number ^[A-Z0-9]{2,8}$, from/to {code, name} (code ^[A-Z]{3}$), departs_at, arrives_at, class ≤ 32, passengers[{name ≤ 60, seat?}], baggage ≤ 100
GET /checkout-sessions/{id}/ticket (cinema)
{ "booking_reference": "BK7K2Q9A", "status": "valid", "used_at": null,
  "issued_at": "2026-09-26T19:05:00+07:00",
  "entry_code": { "format": "qr", "payload": "<≤ 512 printable ASCII chars, HMAC-signed>" },
  "title": "Mưa Đỏ",
  "venue": { "name": "Rạp Demo", "address": "1 Đường Ví Dụ, Quận 1" },
  "starts_at": "2026-09-26T19:30:00+07:00", "ends_at": "2026-09-26T21:45:00+07:00",
  "instructions": "Show the QR code to the ticket checker.",
  "ticket_url": "https://vexinh.example/tickets/<bookingId>",
  "format": "2D Subtitled", "room": "R2", "seats": ["F7", "F8"], "quantity": 2 }
Flight tickets replace the cinema fields with
"flight_number": "VN123",
"from": { "code": "SGN", "name": "Tân Sơn Nhất" },
"to": { "code": "HAN", "name": "Nội Bài" },
"departs_at": "2026-09-27T07:00:00+07:00", "arrives_at": "2026-09-27T09:10:00+07:00",
"class": "economy",
"passengers": [ { "name": "NGUYEN VAN A", "seat": "12A" } ],
"baggage": "7kg carry-on"

Only passengers' display names; never send dates of birth or passports.

Entry codes

  • An entry code is a bearer credential: whoever holds it gets in. Sign it with HMAC using a server-side secret, and never log it. In the sample merchants, the payload is a JSON object (cinema: booking_id, screening, seats; airline: pnr, flight) with sig = the first 16 hex chars of HMAC-SHA256, compared in constant time.
  • Check-in: the staff API POST /staff/checkin {"qr": "…"} (staff/admin auth) verifies the signature (bad → 400) and marks the ticket used on the first scan (200 with {ticket}); a second scan → 409 ALREADY_USED. The sample airline serves this API at /api/staff/checkin; the staff page is /staff/checkin.
  • The ticket page /tickets/:bookingId (sign-in required, owner only) is the target of ticket_url.
  • The card in the chat is stamped USED when status is used and CANCELED when the ticket is canceled or refunded (ĐÃ SỬ DỤNG / ĐÃ HUỶ when the host app is in Vietnamese). Siz reads the ticket fresh every time; if you can't answer, Siz shows the last stored copy and marks it as stale.

8. Account linking

Account linking tells Siz which of your customers an Siz user is, so sessions and tickets are in their name. The result is a customer_ref (mref_ + 22 base64url chars) that Siz sends when creating a session.

  1. On the permission page, the user clicks “Link account”; Siz sends the browser to the /agent-link page on your link_origin.
  2. The /agent-link page requires signing in with your account, then asks “Siz wants to link to your account <email>” with two buttons, Approve / Deny.
  3. Approve → your customer API (the customer's Bearer JWT) issues a one-time code valid for 5 minutes, bound to the user + req + the caller aig, then redirects the browser to return with link_request_id and code. Deny → back to return with error=access_denied.
  4. Only redirect when return starts with an origin on your allowlist (sample merchants: AIG_LINK_RETURN_ORIGINS, normalized origins: lowercase host, no default port, no path, no trailing /). Otherwise the page refuses.
  5. Siz calls POST /links/exchange (signed) to exchange the code for the customer_ref. The code is single-use; an unknown, expired or used code or a wrong req → 404 NOT_FOUND.
The URL Siz opens and where the page returns
https://vexinh.example/agent-link?req=<link_request_id>&return=<URL-encoded "<SIZ_WEB_URL>/link/callback?auth_request_id=<id>">

# Approve → <return>&link_request_id=<req>&code=<code>
# Deny    → <return>&link_request_id=<req>&error=access_denied
Code exchange
POST /links/exchange          (RFC 9421 signed)
{ "code": "<one-time code>", "link_request_id": "<req>" }

200 { "customer_ref": "mref_<22 base64url chars>" }

return already has a query (auth_request_id): append parameters, do not replace the query. The session stores the user resolved from the link; a revoked link → 403 CUSTOMER_NOT_LINKED.

9. Checkout page

continue_url = https://<checkout_origin>/checkout-sessions/<id>. It is the fallback that always exists: when there is no payment block or Siz drops an instruction, the user pays here.

  • Sign-in required: signed-out visitors only see a generic sign-in screen, with no seats or prices revealed. Signed in, but not the session's linked user → 404.
  • GET has no side effects and can be reopened until expiry. The first POST (starting payment) moves the session to in_payment with its single extension, like payment-method.
  • Headers: Content-Security-Policy: frame-ancestors 'none', Cache-Control: no-store, Referrer-Policy: no-referrer, X-Robots-Tag: noindex.
  • Flights: this page is the only place passengers are entered; once saved, set buyer_input.completed = true, recompute the totals and increase state_version.
  • Return URLs: with a real payment gateway, set the gateway's return/cancel URLs to your own page on checkout_origin (the checkout page or /tickets/:bookingId). Siz needs no callback: the card in the chat reads the session again by itself.

10. Sandbox

The sample merchants turn on test mode with PAYMENT_SANDBOX=1. Only then do these exist:

  • The customer page /checkout-sessions/:id/simulate-transfer → POST …/simulate-transfer {reference} (customer JWT, session owner only). reference must equal the selected VietQR reference, otherwise → 409 INVALID_STATE with reason: "reference_mismatch".
  • Link methods stripe_sandbox, momo_sandbox: payment_link.url = <checkout_origin>/sandbox-pay/<token>, a single-use token issued when the method is selected; the /sandbox-pay/:token page pretends to be the payment gateway and confirms.
Sample merchant environment variables
PAYMENT_METHODS=vietqr,stripe_sandbox,momo_sandbox
VIETQR_BIN=970436
VIETQR_ACCOUNT=0123456789
VIETQR_NAME="CONG TY VE XINH"
PAYMENT_REFERENCE_PREFIX=DEMO
PAYMENT_SANDBOX=1          # test environments only, never in production
VariableMeaning
PUBLIC_ORIGINPublic origin of the API that Siz signs against (@target-uri), no trailing /
CHECKOUT_ORIGINWeb app origin, used to build continue_url, ticket_url and sandbox URLs; must be https in production
AIG_PUBLIC_KEYSPublic keys by keyid (section 3)
AIG_LINK_RETURN_ORIGINSOrigins the /agent-link page may return to (CSV)
PAYMENT_METHODSCSV vietqr,stripe_sandbox,momo_sandbox (default vietqr); *_sandbox methods only exist when PAYMENT_SANDBOX=1
VIETQR_BIN, VIETQR_ACCOUNT, VIETQR_NAMEReceiving account (6-digit BIN, account number of 1–19 letters/digits, name of A–Z 0–9 . , - and spaces, ≤ 70); missing or invalid drops vietqr
PAYMENT_REFERENCE_PREFIXReference prefix (0–10 chars A–Z0–9, default PAY); reference = prefix + 8 chars
PAYMENT_SANDBOX1 turns on simulate-transfer, sandbox-pay and the *_sandbox methods. Never set it in production

On the Siz side, dev builds can call merchants over http with SIZ_DEV_INSECURE_MERCHANTS=1; production builds always require https. Siz's mock merchant (cmd/mockmerchant) takes the same values through the flags -payment-methods, -vietqr-bin, -vietqr-account, -vietqr-name, -reference-prefix.

11. Going to production

Bank reconciliation

Receive balance notifications from a reconciliation service (SePay, Casso…) or your bank's webhook. For each transaction, match the transfer message against the selected reference, the amount against totals.total and the account against the pinned account, then call a single confirmation path (in the sample merchants: confirmPayment(session, source)), the same path the pay button, simulate-transfer and sandbox-pay use. This path is idempotent, creates the booking and a signed entry code, then moves the session to completed.

“Already completed” means a duplicate payment

When a new transaction arrives for a session already completed by another source or another transaction, do not treat it as success: it is a duplicate payment and must go into the refund process. Only ignore it when that very transaction is the one that confirmed the session. Money arriving after the hold has expired, or for a reference replaced by a new selection, must be refunded too.

Refunds

Siz does not refund automatically. When you cancel and refund a booking created by an agent, the session moves to canceled with cancel_reason: "refunded" and the ticket gets status refunded or canceled; the card in the chat is stamped CANCELED.

Rotate secrets carefully

  • Changing the entry-code HMAC secret makes every issued ticket impossible to check in. Only change it when no unused tickets remain, or reissue the tickets.
  • Siz's keys: keep both the old and the new keyid in AIG_PUBLIC_KEYS while Siz switches keys.
  • Changing receiving accounts or payment gateways: update the Siz registry first, then change it on your side.
  • Any mechanism that auto-completes stuck payments must confirm with the bank or payment gateway before setting completed.

12. Pre-launch checklist

  • The Siz registry has api_base, checkout_origin, link_origin as https, and payment.vietqr_accounts/link_hosts with the real accounts and hosts.
  • PUBLIC_ORIGIN is the correct public origin; the RFC 9421 test vector passes; nonces are stored with a TTL; signature failures return 401 SIGNATURE_INVALID.
  • AIG_PUBLIC_KEYS has Siz's real key (not the test key), mapped to the caller aig.
  • Idempotency for create, change and choose method; seats are never held partially.
  • Generated VietQR codes pass every rule in section 5: CRC, 54 = total, 62.08 = reference, no unknown tags.
  • Choosing a method again invalidates the old reference or token.
  • Bank reconciliation goes through one idempotent confirmation path; duplicate and late payments go into the refund process.
  • GET …/ticket returns tickets with HMAC-signed entry codes; a second check-in returns 409 ALREADY_USED.
  • The /checkout-sessions/:id, /tickets/:id and /agent-link pages require sign-in and send frame-ancestors 'none'; AIG_LINK_RETURN_ORIGINS contains only the aig-web origin.
  • PAYMENT_SANDBOX is not set; CHECKOUT_ORIGIN is https.
  • Never log signatures, entry codes, account numbers or passenger data.