Tích hợp cửa hàng với Siz

Dành cho lập trình viên của cửa hàng bán vé (rạp phim, hãng bay…) muốn cho trợ lý AI đặt vé qua Siz. Tài liệu này tóm tắt Merchant Agent API v1.4: Siz gọi API của bạn, người dùng trả tiền ở phía bạn, và Siz hiện hướng dẫn thanh toán cùng vé ngay trong khung chat.

Hướng dẫn cho người dùng cuối: Hướng dẫn sử dụng. Cửa hàng mẫu tham chiếu: rạp phim (base path /agent/v1) và hãng bay (/api/agent/v1).

1. Tổng quan

Siz là máy chủ MCP mà trợ lý AI kết nối tới. Khi người dùng nhờ trợ lý đặt vé, Siz gọi agent API của bạn bằng request có chữ ký. Tiền không bao giờ đi qua Siz: người dùng trả thẳng cho bạn.

  1. Trợ lý AI → SizNgười dùng nhờ trợ lý; trợ lý gọi công cụ MCP của Siz (tìm suất, xem ghế, giữ chỗ).
  2. Siz → agent API của bạnRequest ký RFC 9421: GET /offers, seatmap, POST /checkout-sessions để giữ chỗ.
  3. Người dùng chọn cách trảSiz gọi payment-method; bạn trả về hướng dẫn VietQR hoặc liên kết thanh toán; Siz kiểm tra với registry rồi hiện trên thẻ trong chat.
  4. Người dùng trả tiền ở phía bạnChuyển khoản ngân hàng hoặc trang của cổng thanh toán. Bạn đối soát và chuyển session sang completed.
  5. Siz đọc lại và hiện véThẻ trong chat hỏi Siz vài giây một lần; mỗi lần Siz đọc GET /checkout-sessions/{id}. Khi completed, Siz gọi GET …/ticket.
  6. Soát vé tại cổngNhân viên quét mã QR; bạn đánh dấu vé đã dùng.

Các nguyên tắc không đổi:

  • Siz không bao giờ thanh toán hay giữ tiền. Đơn chỉ là “đã trả” khi bạn báo completed.
  • Mọi chuỗi bạn trả về được coi là dữ liệu: Siz làm sạch trước khi hiện, bỏ trường lạ.
  • Siz không nhận dữ liệu cá nhân của hành khách (ngày sinh, hộ chiếu): người dùng nhập trên trang của bạn.
  • Mọi thứ trong v1.4 là bổ sung: cửa hàng v1.3 không gửi khối payment vẫn chạy, người dùng trả qua continue_url.

2. Đăng ký với Siz

Nhà vận hành Siz thêm cửa hàng của bạn vào registry tĩnh merchants.yaml. Siz không bao giờ suy ra URL từ request; mọi địa chỉ đều lấy từ đây. Gửi cho nhà vận hành các giá trị sau:

merchants.yaml
merchants:
  - merchant_id: vexinh                 # ^[a-z0-9][a-z0-9-]{0,62}$, duy nhất
    vertical: cinema                    # ^[a-z]{2,32}$, ví dụ cinema, flight
    display_name: Vé Xinh Cinema        # tuỳ chọn, ≤ 100 ký tự, hiện trên trang cho phép
    api_base: https://api.vexinh.example/agent/v1
    checkout_origin: https://vexinh.example
    link_origin: https://vexinh.example # tuỳ chọn, mặc định = checkout_origin
    concurrency_budget: 20              # 1–1000 request đồng thời tới bạn
    ttl_max_seconds: 600                # 1–900, thời gian giữ chỗ tối đa của bạn
    payment:
      vietqr_accounts:
        - bank_bin: "970436"            # 6 số, để trong ngoặc kép
          account_number: "0123456789"  # 1–19 chữ hoặc số, đúng như trong QR
      link_hosts: ["checkout.stripe.com", "pay.vnpay.vn"]
TrườngQuy tắc
merchant_idMã cửa hàng, ^[a-z0-9][a-z0-9-]{0,62}$, không trùng.
display_nameTên hiện trên trang cho phép và trang kết nối. Tuỳ chọn, tối đa 100 ký tự; mặc định là merchant_id.
api_baseURL tuyệt đối, https, tới gốc agent API (Siz ghép /offers, /checkout-sessions… vào sau). Siz không theo redirect.
checkout_originOrigin https của web app phục vụ /checkout-sessions/:id, /tickets/:id và các trang sandbox. continue_url, ticket_url phải nằm trên origin này, và host của nó luôn được phép làm host liên kết thanh toán.
link_originOrigin https phục vụ trang /agent-link (web app, không phải API). Tuỳ chọn, mặc định bằng checkout_origin.
verticalNgành, ^[a-z]{2,32}$, ví dụ cinema, flight. Hiện mỗi ngành chỉ do một cửa hàng phục vụ.
concurrency_budget, ttl_max_secondsSố request đồng thời tối đa Siz gửi tới bạn (1–1000); thời gian giữ chỗ tối đa bạn cho phép (1–900 giây). Siz gửi đúng giá trị này làm ttl_seconds khi giữ chỗ.
payment.vietqr_accountsTối đa 10 tài khoản nhận tiền {bank_bin, account_number}: bank_bin đúng 6 số, account_number 1–19 chữ hoặc số. Siz chỉ hiện VietQR có tài khoản nằm trong danh sách này; trống thì không bao giờ hiện VietQR.
payment.link_hostsTối đa 20 host của cổng thanh toán, chữ thường, không scheme, cổng, đường dẫn hay wildcard. So khớp chính xác: evil.stripe.com không khớp checkout.stripe.com.

Nhà vận hành Siz gửi lại cho bạn:

  • keyid và khoá công khai Ed25519 để xác minh chữ ký (xem mục 3);
  • origin của aig-web, để bạn đặt vào danh sách trang /agent-link được phép quay về (mục 8).

Khối payment là chốt chống giả mạo: kể cả khi máy chủ của bạn bị chiếm, Siz không hiện QR tới tài khoản khác hay liên kết tới site khác. Khi đổi tài khoản nhận tiền hoặc cổng thanh toán, hãy nhờ cập nhật registry trước, nếu không phương thức đó bị bỏ (log account_not_allowed, link_host). Hướng dẫn đã lưu cho các đơn đang mở vẫn hiện tới khi session đổi, tối đa một vòng giữ chỗ (≤ 20 phút).

3. Ký request

Mọi request Siz gửi tới agent API đều được ký theo một tập con của RFC 9421 (HTTP Message Signatures) bằng Ed25519. Caller của Siz là "aig".

Header của một request có 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 của chữ ký Ed25519 64 byte>:
Content-Digest: sha-256=:<base64 của sha256(body)>:
Idempotency-Key: 5b7c1a52-0d7e-4c55-9c1e-3f7a2a0e9b11
  • Các thành phần ký, theo đúng thứ tự: "@method" "@target-uri", rồi "content-digest" nếu có body, rồi "idempotency-key" nếu có header đó.
  • Content-Digest = sha-256=:base64(sha256(body)): (RFC 9530). Kiểm tra trên byte thô của body trước khi parse JSON.
  • @target-uri = PUBLIC_ORIGIN đã cấu hình của bạn (không có dấu / cuối) + đường dẫn + ?query đúng như đã gửi (Express: PUBLIC_ORIGIN + req.originalUrl). Không bao giờ dùng header Host (tunnel hay proxy có thể đổi nó).
  • @method viết hoa. expires − created ≤ 60 giây; chấp nhận created lệch ±30 giây so với đồng hồ của bạn; từ chối khi now > expires.
  • nonce chỉ dùng một lần: lưu lại (ví dụ collection có chỉ mục unique và TTL 300 giây).
  • Lỗi bất kỳ → 401 problem SIGNATURE_INVALID; detail nói bước nào sai, không bao giờ lặp lại chữ ký. Không log chữ ký.

Chuỗi cần ký (signature base), các dòng nối bằng \n, không có dòng trống cuối:

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"

Lấy khoá công khai của Siz

Siz không công bố khoá ký request qua một endpoint. Nhà vận hành Siz gửi cho bạn keyid và khoá công khai (32 byte thô, base64) qua một kênh tin cậy. Bạn đặt chúng vào biến môi trường, ánh xạ mỗi keyid tới caller aig:

.env
# Khoá công khai thử nghiệm của RFC 8032 (test 1), chỉ để minh hoạ định dạng
AIG_PUBLIC_KEYS='{"aig-dev-1":{"caller":"aig","key":"11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo="}}'
  • Khi Siz xoay khoá, để cả keyid hiện tại và keyid trước đó, cùng trỏ tới caller aig.
  • Mọi phạm vi (idempotency key, liên kết tài khoản, quyền sở hữu session) gắn với caller, không gắn với keyid, để xoay khoá không làm mất session hay liên kết.
  • Kiểm thử: dùng seed RFC 8032 test 1 9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60, body {"hello":"world"} và signature base ở trên; Ed25519 là tất định nên chữ ký phải trùng với vector chuẩn của hợp đồng.

4. API tham chiếu (v1.4)

Mọi body là JSON UTF-8, giới hạn 32 KB. Thời điểm theo RFC 3339 có offset +07:00. Tiền là số nguyên VND kèm "currency": "VND". Agent API không gửi header CORS và không đọc cookie. Luôn đặt header Date (Siz dùng để đo lệch giờ).

Phương thứcĐường dẫnViệc
GET/offersTìm suất chiếu/chuyến bay
GET/offers/{offer_id}/seatmapSơ đồ ghế
POST/checkout-sessionsGiữ chỗ (Idempotency-Key bắt buộc, ≤ 128 ký tự) → 201
GET/checkout-sessions/{id}Đọc session
GET/checkout-sessions?idempotency_key=Tìm session theo key (giữ ≥ 72 giờ) · 202 đang xử lý · 404
PUT/checkout-sessions/{id}Đổi ghế/số lượng (Idempotency-Key bắt buộc)
POST/checkout-sessions/{id}/cancelTrả chỗ
POST/checkout-sessions/{id}/completeLuôn 403 FORBIDDEN với agent: agent không bao giờ tự hoàn tất
POST/checkout-sessions/{id}/payment-methodv1.4: chọn phương thức thanh toán (Idempotency-Key bắt buộc)
GET/checkout-sessions/{id}/ticketv1.4: vé của session đã trả
POST/links/exchangeĐổi mã liên kết tài khoản lấy customer_ref

Offers và seatmap

Vé phim: query date (bắt buộc, YYYY-MM-DD), movie (slug), cinema_id, q (≤ 100 ký tự, tìm theo tên phim, không phân biệt hoa thường và dấu), limit (1–50, mặc định 20), cursor. Vé máy bay: from, to (mã IATA), date bắt buộc; class (economy|business|first), quantity (1–9), limit, cursor. Chỉ trả offer chưa bắt đầu, sắp theo starts_at rồi offer_id.

GET /offers (vé phim)
{ "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 }

Vé máy bay: offer_id = <flightId>:<class>, ends_at là giờ đến, tuỳ chọn price_estimate (tổng đã gồm thuế phí cho 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 tăng ở mỗi lần giữ/trả/bán ghế, chỉ để tham khảo. layout.front_row (chỉ vé phim, tuỳ chọn) là hàng gần màn hình nhất.

Checkout session: tạo, đọc, đổi, huỷ

Tạo 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 }
  • Đúng một line item. Vé phim: seats bắt buộc, quantity = số ghế. Vé máy bay: seats tuỳ chọn, thiếu thì bạn tự gán ghế.
  • ttl_seconds được kẹp vào [60, TTL_MAX của bạn]. Giới hạn cho cả web lẫn agent: số ghế mỗi khách mỗi suất, ≤ 3 session đang sống mỗi khách (vượt → 422 QUOTA_EXCEEDED).
  • Idempotency theo (caller, key): cùng key + cùng body → trả session đã lưu (200); cùng key + body khác → 409 IDEMPOTENCY_MISMATCH; đang giữ ghế dở → 202 {"status":"in_progress"}.
  • Ghế bị người khác giữ → 409 SEAT_UNAVAILABLE kèm seats, revision; không bao giờ giữ một phần.
  • PUT đổi ghế nguyên tử (giữ ghế mới và trả ghế bỏ trong một lần), không gia hạn expires_at, chỉ khi open; thêm message price_changed nếu tổng đổi.
  • cancel: open → canceled (trả ghế); đã huỷ/hết hạn → 200 không đổi; in_payment hoặc completed → 409 INVALID_STATE.
  • Hết hạn lười: mỗi lần đọc, session open/in_payment quá expires_at được báo là canceled với cancel_reason: "expired".
Session object (v1.4, đã chọn VietQR)
{ "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 chỉ có khi completed. state_version tăng ở mọi thay đổi, kể cả mọi thay đổi của khối payment.

Khối payment

  • Có trong mọi câu trả lời chứa session. Với session completed/canceled/failed là {} (hoặc chỉ buyer_input với vé máy bay).
  • buyer_input { "required": true, "completed": false }: chỉ khi ngành cần dữ liệu người mua (hành khách). completed thành true khi trang của bạn đã lưu hành khách.
  • methods: chỉ khi session open/in_payment và không cần hoặc đã xong buyer input. id ^[a-z0-9_]{1,32}$; type vietqr | payment_link; label ≤ 60; provider bắt buộc với payment_link; fee chỉ để hiện (số tiền VietQR luôn bằng totals.total, hãy gộp phí vào totals khi chọn).
  • selected: sau khi chọn, có đúng một trong vietqr / payment_link. reference ^[A-Z0-9]{6,25}$; account_name ≤ 70; expires_at RFC 3339.
selected với liên kết thanh toán
"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

Chọn phương thức
POST /checkout-sessions/cs_2b9f…/payment-method
Idempotency-Key: cs_2b9f…:pm:3f0c9a1e5b7d4c2a8e6f1b3d5a7c9e0f

{ "method_id": "vietqr" }
  • Lần chọn đầu chuyển open → in_payment và gia hạn một lần: expires_at = min(max(expires_at, now + 5 phút), created_at + 20 phút).
  • Chọn lại (bất kỳ phương thức) được phép khi open/in_payment: vô hiệu hướng dẫn cũ (reference cũ không còn xác nhận được, token cũ bị từ chối) và phát hướng dẫn mới.
  • Cùng key + cùng body → 200 với session hiện tại (không phát hướng dẫn mới); cùng key + body khác → 409 IDEMPOTENCY_MISMATCH. Siz gửi key dạng <checkout_id>:pm:<32 hex>. Lỗi cũng được gắn với key như thành công.
  • Lỗi: 409 INVALID_STATE (đã xong/huỷ/thất bại, hoặc chưa nhập hành khách với reason: "buyer_input_required"), 410 HOLD_EXPIRED, 400 INVALID_ARGUMENT field: "method_id", 404 NOT_FOUND.

GET ticket

200 với vé khi session đã được trả (kể cả sau hoàn tiền: status: refunded); 409 INVALID_STATE kèm session_status nếu chưa; 404 NOT_FOUND. Chi tiết các trường ở mục 7.

POST links/exchange

Body {code, link_request_id} → 200 {customer_ref}. Xem mục 8.

Lỗi (problem+json)

Content-Type: application/problem+json, body {type, title, status, code, detail, …extras}. Siz phân biệt các lỗi 409 theo code, không theo status.

HTTPcodeKhi nào
400INVALID_ARGUMENTDữ liệu sai, kèm field (body > 32 KB: field: "body")
401SIGNATURE_INVALIDChữ ký sai (mục 3)
403CUSTOMER_NOT_LINKEDcustomer_ref lạ hoặc đã thu hồi với caller này
403FORBIDDENVí dụ agent gọi /complete
404NOT_FOUNDOffer/session không có, hoặc session của caller khác; mã liên kết lạ, hết hạn, đã dùng
409SEAT_UNAVAILABLEGhế đã bị giữ, kèm seats, revision
409IDEMPOTENCY_MISMATCHCùng Idempotency-Key, body khác
409INVALID_STATESai trạng thái, kèm session_status và có thể reason: buyer_input_required, reference_mismatch (bỏ qua giá trị không biết)
409ALREADY_USEDAPI soát vé của bạn (không phải agent API): vé quét lần thứ hai
410HOLD_EXPIREDSession đã quá expires_at
422QUOTA_EXCEEDEDVượt giới hạn ghế hoặc số session đang sống, kèm limit
503MERCHANT_UNAVAILABLECơ sở dữ liệu lỗi…
Ví dụ
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. Quy tắc VietQR

Payload VietQR (NAPAS 247, EMVCo chế độ merchant-presented) do bạn tạo. Siz phân tích TLV và bỏ phương thức nếu vi phạm bất kỳ quy tắc nào:

  • Tag cấp cao nhất chỉ được thuộc {00, 01, 38, 52, 53, 54, 58, 59, 60, 62, 63}. Tag khác làm hỏng cả payload.
  • 00 phải đứng đầu, 63 đứng cuối; không data object nào có giá trị rỗng.
  • Không có 55/56/57 (tiền tip, phí tiện ích: làm số tiền chuyển thực tế khác 54) và không có template tài khoản thứ hai (02–51 ngoài 38).
  • 00=01, 01=12 (QR động), 38 = { 00=A000000727, 01 = { 00=bank_bin, 01=account_number }, 02=QRIBFTTA }, 53=704, 58=VN.
  • 62.08 bằng đúng reference (không chỉ chứa nó).
  • 63 = CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) tính trên payload tới hết 6304, 4 chữ số hex viết hoa.
  • 54 = số tiền nguyên VND = vietqr.amount = totals.total của session.
  • bank_bin/account_number trong QR bằng các trường JSON và thuộc payment.vietqr_accounts trong registry.
  • Payload ≤ 512 ký tự ASCII in được. Không hợp lệ thì Siz bỏ hướng dẫn (không sửa), ghi log payment_instruction_rejected với mã lý do (không ghi payload, số tài khoản hay URL), và người dùng vẫn còn continue_url.
Ví dụ: 150 000 VND tới 970436 / 0123456789, reference DEMO7K2Q9A4F
00020101021238540010A00000072701240006970436011001234567890208QRIBFTTA530370454061500005802VN62160812DEMO7K2Q9A4F63048BA8
TagGiá trịÝ nghĩa
0001Phiên bản định dạng
0112QR động (dùng một lần)
3800·10·A000000727 01·24·(00·06·970436 01·10·0123456789) 02·08·QRIBFTTANAPAS GUID, BIN 970436, tài khoản 0123456789, dịch vụ chuyển nhanh tới tài khoản
53704VND
54150000Số tiền = tổng tiền của session
58VNQuốc gia
6208·12·DEMO7K2Q9A4F62.08 = reference (nội dung chuyển khoản)
638BA8CRC16

6. Liên kết thanh toán

Với phương thức payment_link, Siz chỉ hiện selected.payment_link.url khi:

  • scheme là https, dài ≤ 2048 ký tự, không có userinfo (user@) hay ký tự điều khiển;
  • host đúng bằng một host trong payment.link_hosts, hoặc host của checkout_origin (trang sandbox của bạn);
  • provider khớp ^[a-z0-9_]{1,32}$ và bằng provider của phương thức.

Thẻ trong chat hiện nút mở liên kết và một mã QR của URL. Người dùng trả trên trang của cổng thanh toán; bạn xác nhận qua webhook của cổng rồi chuyển session sang completed.

7. Vé và soát vé

TrườngQuy tắc
booking_referenceMã đặt chỗ ^[A-Za-z0-9_-]{1,64}$ (rạp: mã booking, hãng bay: PNR)
statusvalid | used | canceled | refunded; used_at khi đã quét
entry_code{ "format": "qr", "payload": "…" }, bắt buộc khi valid; ≤ 512 ký tự ASCII in được, có chữ ký của bạn
title, venuetitle ≤ 200; venue.name ≤ 200, venue.address ≤ 300
issued_at, starts_at, ends_atRFC 3339
instructions≤ 200 ký tự, văn bản thuần
ticket_urlhttps trên checkout_origin (sai thì Siz chỉ bỏ URL)
Vé phimformat ≤ 60, room ≤ 100, seats[] (nhãn ≤ 16), quantity
Vé máy bayflight_number ^[A-Z0-9]{2,8}$, from/to {code, name} (mã ^[A-Z]{3}$), departs_at, arrives_at, class ≤ 32, passengers[{name ≤ 60, seat?}], baggage ≤ 100
GET /checkout-sessions/{id}/ticket (vé phim)
{ "booking_reference": "BK7K2Q9A", "status": "valid", "used_at": null,
  "issued_at": "2026-09-26T19:05:00+07:00",
  "entry_code": { "format": "qr", "payload": "<≤ 512 ký tự ASCII in được, có chữ ký HMAC>" },
  "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": "Đưa mã QR cho nhân viên soát vé.",
  "ticket_url": "https://vexinh.example/tickets/<bookingId>",
  "format": "2D Phụ đề", "room": "R2", "seats": ["F7", "F8"], "quantity": 2 }
Vé máy bay thay các trường vé phim bằng
"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 xách tay"

Chỉ tên hiển thị của hành khách; không bao giờ gửi ngày sinh hay hộ chiếu.

Mã vào cửa

  • Mã vào cửa là chứng từ vô danh: ai có mã là vào được. Ký bằng HMAC với một bí mật phía máy chủ, không bao giờ log. Ở cửa hàng mẫu, payload là một object JSON (rạp: booking_id, screening, seats; hãng bay: pnr, flight) kèm sig = 16 ký tự hex đầu của HMAC-SHA256, so sánh thời gian hằng.
  • Soát vé: API nhân viên POST /staff/checkin {"qr": "…"} (xác thực nhân viên/quản trị) kiểm chữ ký (sai → 400), đánh dấu vé used ở lần quét đầu (200 kèm {ticket}); lần quét thứ hai → 409 ALREADY_USED. Hãng bay mẫu đặt API này ở /api/staff/checkin; trang nhân viên là /staff/checkin.
  • Trang vé /tickets/:bookingId (cần đăng nhập, chỉ chủ vé) là đích của ticket_url.
  • Thẻ trong chat đóng dấu ĐÃ SỬ DỤNG khi status là used và ĐÃ HUỶ khi vé bị huỷ. Siz đọc vé mới mỗi lần; nếu bạn không trả lời được, Siz hiện bản lưu gần nhất và đánh dấu là cũ.

8. Liên kết tài khoản

Liên kết tài khoản cho Siz biết người dùng Siz là khách hàng nào của bạn, để session và vé đứng đúng tên họ. Kết quả là một customer_ref (mref_ + 22 ký tự base64url) mà Siz gửi khi tạo session.

  1. Trên trang cho phép, người dùng bấm “Liên kết tài khoản”; Siz đưa trình duyệt tới trang /agent-link trên link_origin của bạn.
  2. Trang /agent-link yêu cầu đăng nhập bằng tài khoản của bạn, rồi hỏi “Siz muốn liên kết với tài khoản <email> của bạn” với hai nút Đồng ý / Từ chối.
  3. Đồng ý → API khách hàng của bạn (Bearer JWT của khách) phát một mã một lần, hạn 5 phút, gắn với người dùng + req + caller aig, rồi chuyển trình duyệt về return kèm link_request_id và code. Từ chối → về return kèm error=access_denied.
  4. Chỉ chuyển về khi return bắt đầu bằng một origin trong danh sách cho phép của bạn (cửa hàng mẫu: AIG_LINK_RETURN_ORIGINS, origin chuẩn hoá: host chữ thường, không cổng mặc định, không đường dẫn, không / cuối). Nếu không, trang từ chối.
  5. Siz gọi POST /links/exchange (có chữ ký) để đổi mã lấy customer_ref. Mã chỉ dùng một lần; mã lạ, hết hạn, đã dùng hoặc sai req → 404 NOT_FOUND.
URL Siz mở và nơi trang quay về
https://vexinh.example/agent-link?req=<link_request_id>&return=<mã hoá URL của "<SIZ_WEB_URL>/link/callback?auth_request_id=<id>">

# Đồng ý  → <return>&link_request_id=<req>&code=<code>
# Từ chối → <return>&link_request_id=<req>&error=access_denied
Đổi mã
POST /links/exchange          (ký RFC 9421)
{ "code": "<mã một lần>", "link_request_id": "<req>" }

200 { "customer_ref": "mref_<22 ký tự base64url>" }

return đã có sẵn query (auth_request_id): hãy nối thêm tham số, đừng thay query. Session lưu người dùng được phân giải từ liên kết; liên kết đã thu hồi → 403 CUSTOMER_NOT_LINKED.

9. Trang checkout

continue_url = https://<checkout_origin>/checkout-sessions/<id>. Đây là đường lui luôn có: khi không có khối payment hoặc Siz bỏ một hướng dẫn, người dùng trả ở đây.

  • Cần đăng nhập: chưa đăng nhập chỉ thấy màn hình đăng nhập chung, không lộ ghế hay giá. Đã đăng nhập nhưng không phải người dùng đã liên kết của session → 404.
  • GET không có tác dụng phụ, mở lại được tới khi hết hạn. POST đầu tiên (bắt đầu trả) chuyển sang in_payment với lần gia hạn duy nhất, giống payment-method.
  • Header: Content-Security-Policy: frame-ancestors 'none', Cache-Control: no-store, Referrer-Policy: no-referrer, X-Robots-Tag: noindex.
  • Vé máy bay: trang này là nơi duy nhất nhập hành khách; lưu xong thì đặt buyer_input.completed = true, tính lại tổng và tăng state_version.
  • URL quay về: khi dùng cổng thanh toán thật, đặt URL quay về/huỷ của cổng về trang của bạn trên checkout_origin (trang checkout hoặc /tickets/:bookingId). Siz không cần callback: thẻ trong chat tự đọc lại session.

10. Môi trường sandbox

Cửa hàng mẫu bật chế độ thử bằng PAYMENT_SANDBOX=1. Chỉ khi đó mới có:

  • Trang khách hàng /checkout-sessions/:id/simulate-transfer → POST …/simulate-transfer {reference} (JWT của khách, chỉ chủ session). reference phải bằng reference VietQR đang chọn, nếu không → 409 INVALID_STATE với reason: "reference_mismatch".
  • Phương thức liên kết stripe_sandbox, momo_sandbox: payment_link.url = <checkout_origin>/sandbox-pay/<token>, token dùng một lần phát khi chọn phương thức; trang /sandbox-pay/:token giả làm cổng thanh toán và xác nhận.
Biến môi trường của cửa hàng mẫu
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          # chỉ ở môi trường thử, không bao giờ ở production
BiếnÝ nghĩa
PUBLIC_ORIGINOrigin công khai của API mà Siz ký theo (@target-uri), không / cuối
CHECKOUT_ORIGINOrigin web app, dùng tạo continue_url, ticket_url, URL sandbox; phải https ở production
AIG_PUBLIC_KEYSKhoá công khai theo keyid (mục 3)
AIG_LINK_RETURN_ORIGINSCác origin trang /agent-link được quay về (CSV)
PAYMENT_METHODSCSV vietqr,stripe_sandbox,momo_sandbox (mặc định vietqr); phương thức *_sandbox chỉ có khi PAYMENT_SANDBOX=1
VIETQR_BIN, VIETQR_ACCOUNT, VIETQR_NAMETài khoản nhận tiền (BIN 6 số, số tài khoản 1–19 chữ/số, tên A–Z 0–9 . , - và dấu cách, ≤ 70); thiếu hoặc sai thì bỏ vietqr
PAYMENT_REFERENCE_PREFIXTiền tố reference (0–10 ký tự A–Z0–9, mặc định PAY); reference = tiền tố + 8 ký tự
PAYMENT_SANDBOX1 bật simulate-transfer, sandbox-pay và các phương thức *_sandbox. Không bao giờ đặt ở production

Phía Siz, bản dev có thể gọi cửa hàng qua http với SIZ_DEV_INSECURE_MERCHANTS=1; bản production luôn đòi https. Cửa hàng giả của Siz (cmd/mockmerchant) nhận cùng các giá trị qua cờ -payment-methods, -vietqr-bin, -vietqr-account, -vietqr-name, -reference-prefix.

11. Lên production

Đối soát ngân hàng

Nhận biến động số dư từ dịch vụ đối soát (SePay, Casso…) hoặc webhook của ngân hàng. Với mỗi giao dịch, khớp nội dung chuyển khoản với reference đang chọn, số tiền với totals.total, tài khoản với tài khoản đã ghim, rồi gọi một đường xác nhận duy nhất (ở cửa hàng mẫu: confirmPayment(session, source)), đường mà nút trả, simulate-transfer và sandbox-pay cũng dùng. Đường này idempotent, tạo booking và mã vào cửa có chữ ký, rồi chuyển session sang completed.

“Đã completed” là thanh toán trùng

Khi một giao dịch mới tới cho session đã completed bởi nguồn khác hoặc giao dịch khác, đừng coi là thành công: đó là tiền trả trùng và phải vào quy trình hoàn tiền. Chỉ bỏ qua khi chính giao dịch đó đã xác nhận session. Tiền tới sau khi giữ chỗ hết hạn, hoặc cho reference đã bị thay bằng lần chọn lại, cũng phải hoàn.

Hoàn tiền

Siz không hoàn tiền tự động. Khi bạn huỷ và hoàn một booking do agent tạo, session chuyển sang canceled với cancel_reason: "refunded" và vé có status refunded hoặc canceled; thẻ trong chat đóng dấu ĐÃ HUỶ.

Xoay bí mật cẩn thận

  • Đổi bí mật HMAC của mã vào cửa làm mọi vé đã phát không soát được nữa. Chỉ đổi khi không còn vé nào chưa dùng, hoặc phát lại vé.
  • Khoá của Siz: giữ cả keyid cũ và mới trong AIG_PUBLIC_KEYS trong lúc Siz chuyển khoá.
  • Đổi tài khoản nhận tiền hoặc cổng thanh toán: cập nhật registry Siz trước, rồi mới đổi ở phía bạn.
  • Mọi cơ chế tự hoàn tất thanh toán bị treo phải xác nhận với ngân hàng hoặc cổng thanh toán trước khi đặt completed.

12. Checklist trước khi bật

  • Registry Siz có đủ api_base, checkout_origin, link_origin dạng https, và payment.vietqr_accounts/link_hosts đúng tài khoản, host thật.
  • PUBLIC_ORIGIN đúng origin công khai; test vector RFC 9421 chạy qua; nonce được lưu với TTL; lỗi chữ ký trả 401 SIGNATURE_INVALID.
  • AIG_PUBLIC_KEYS có khoá thật của Siz (không phải khoá thử) và ánh xạ tới caller aig.
  • Idempotency cho tạo, đổi, chọn phương thức; không bao giờ giữ ghế một phần.
  • VietQR tạo ra qua được mọi quy tắc ở mục 5: CRC, 54 = tổng tiền, 62.08 = reference, không tag lạ.
  • Chọn lại phương thức làm reference hoặc token cũ mất hiệu lực.
  • Đối soát ngân hàng đi vào một đường xác nhận idempotent; thanh toán trùng và thanh toán muộn vào quy trình hoàn tiền.
  • GET …/ticket trả vé có mã vào cửa ký HMAC; soát vé lần hai trả 409 ALREADY_USED.
  • Trang /checkout-sessions/:id, /tickets/:id, /agent-link cần đăng nhập, gửi frame-ancestors 'none'; AIG_LINK_RETURN_ORIGINS chỉ có origin aig-web.
  • PAYMENT_SANDBOX không được đặt; CHECKOUT_ORIGIN là https.
  • Không log chữ ký, mã vào cửa, số tài khoản hay dữ liệu hành khách.