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.
- 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ỗ).
- Siz → agent API của bạnRequest ký RFC 9421:
GET /offers,seatmap,POST /checkout-sessionsđể giữ chỗ. - 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. - 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. - 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}. Khicompleted, Siz gọiGET …/ticket. - 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
paymentvẫn chạy, người dùng trả quacontinue_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:
- 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ường | Quy tắc |
|---|---|
merchant_id | Mã cửa hàng, ^[a-z0-9][a-z0-9-]{0,62}$, không trùng. |
display_name | Tê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_base | URL 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_origin | Origin 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_origin | Origin https phục vụ trang /agent-link (web app, không phải API). Tuỳ chọn, mặc định bằng checkout_origin. |
vertical | Ngà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_seconds | Số 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_accounts | Tố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_hosts | Tố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:
keyidvà 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".
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ó).@methodviết hoa.expires − created≤ 60 giây; chấp nhậncreatedlệch ±30 giây so với đồng hồ của bạn; từ chối khinow > expires.noncechỉ 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ỳ →
401problemSIGNATURE_INVALID;detailnó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:
"@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:
# 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ả
keyidhiện tại vàkeyidtrước đó, cùng trỏ tới calleraig. - 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ẫn | Việc |
|---|---|---|
| GET | /offers | Tìm suất chiếu/chuyến bay |
| GET | /offers/{offer_id}/seatmap | Sơ đồ ghế |
| POST | /checkout-sessions | Giữ 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}/cancel | Trả chỗ |
| POST | /checkout-sessions/{id}/complete | Luôn 403 FORBIDDEN với agent: agent không bao giờ tự hoàn tất |
| POST | /checkout-sessions/{id}/payment-method | v1.4: chọn phương thức thanh toán (Idempotency-Key bắt buộc) |
| GET | /checkout-sessions/{id}/ticket | v1.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.
{ "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).
{ "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ỷ
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:
seatsbắt buộc,quantity= số ghế. Vé máy bay:seatstuỳ 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_UNAVAILABLEkèmseats,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ạnexpires_at, chỉ khiopen; thêm messageprice_changednếu tổng đổi.cancel:open→canceled(trả ghế); đã huỷ/hết hạn → 200 không đổi;in_paymenthoặccompleted→409 INVALID_STATE.- Hết hạn lười: mỗi lần đọc, session
open/in_paymentquáexpires_atđược báo làcanceledvớicancel_reason: "expired".
{ "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/failedlà{}(hoặc chỉbuyer_inputvớ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).completedthànhtruekhi trang của bạn đã lưu hành khách.methods: chỉ khi sessionopen/in_paymentvà không cần hoặc đã xong buyer input.id^[a-z0-9_]{1,32}$;typevietqr | payment_link;label≤ 60;providerbắt buộc vớipayment_link;feechỉ để hiện (số tiền VietQR luôn bằngtotals.total, hãy gộp phí vào totals khi chọn).selected: sau khi chọn, có đúng một trongvietqr/payment_link.reference^[A-Z0-9]{6,25}$;account_name≤ 70;expires_atRFC 3339.
"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
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_paymentvà 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ớireason: "buyer_input_required"),410 HOLD_EXPIRED,400 INVALID_ARGUMENTfield: "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.
| HTTP | code | Khi nào |
|---|---|---|
| 400 | INVALID_ARGUMENT | Dữ liệu sai, kèm field (body > 32 KB: field: "body") |
| 401 | SIGNATURE_INVALID | Chữ ký sai (mục 3) |
| 403 | CUSTOMER_NOT_LINKED | customer_ref lạ hoặc đã thu hồi với caller này |
| 403 | FORBIDDEN | Ví dụ agent gọi /complete |
| 404 | NOT_FOUND | Offer/session không có, hoặc session của caller khác; mã liên kết lạ, hết hạn, đã dùng |
| 409 | SEAT_UNAVAILABLE | Ghế đã bị giữ, kèm seats, revision |
| 409 | IDEMPOTENCY_MISMATCH | Cùng Idempotency-Key, body khác |
| 409 | INVALID_STATE | Sai 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) |
| 409 | ALREADY_USED | API soát vé của bạn (không phải agent API): vé quét lần thứ hai |
| 410 | HOLD_EXPIRED | Session đã quá expires_at |
| 422 | QUOTA_EXCEEDED | Vượt giới hạn ghế hoặc số session đang sống, kèm limit |
| 503 | MERCHANT_UNAVAILABLE | Cơ sở dữ liệu lỗi… |
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. 00phả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ác54) và không có template tài khoản thứ hai (02–51ngoài38). 00=01,01=12(QR động),38= {00=A000000727,01= {00=bank_bin,01=account_number },02=QRIBFTTA},53=704,58=VN.62.08bằng đúngreference(không chỉ chứa nó).63= CRC-16/CCITT-FALSE (poly0x1021, init0xFFFF) tính trên payload tới hết6304, 4 chữ số hex viết hoa.54= số tiền nguyên VND =vietqr.amount=totals.totalcủa session.bank_bin/account_numbertrong QR bằng các trường JSON và thuộcpayment.vietqr_accountstrong 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_rejectedvới mã lý do (không ghi payload, số tài khoản hay URL), và người dùng vẫn còncontinue_url.
00020101021238540010A00000072701240006970436011001234567890208QRIBFTTA530370454061500005802VN62160812DEMO7K2Q9A4F63048BA8| Tag | Giá trị | Ý nghĩa |
|---|---|---|
| 00 | 01 | Phiên bản định dạng |
| 01 | 12 | QR động (dùng một lần) |
| 38 | 00·10·A000000727 01·24·(00·06·970436 01·10·0123456789) 02·08·QRIBFTTA | NAPAS GUID, BIN 970436, tài khoản 0123456789, dịch vụ chuyển nhanh tới tài khoản |
| 53 | 704 | VND |
| 54 | 150000 | Số tiền = tổng tiền của session |
| 58 | VN | Quốc gia |
| 62 | 08·12·DEMO7K2Q9A4F | 62.08 = reference (nội dung chuyển khoản) |
| 63 | 8BA8 | CRC16 |
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ủacheckout_origin(trang sandbox của bạn); providerkhớ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ường | Quy tắc |
|---|---|
booking_reference | Mã đặt chỗ ^[A-Za-z0-9_-]{1,64}$ (rạp: mã booking, hãng bay: PNR) |
status | valid | 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, venue | title ≤ 200; venue.name ≤ 200, venue.address ≤ 300 |
issued_at, starts_at, ends_at | RFC 3339 |
instructions | ≤ 200 ký tự, văn bản thuần |
ticket_url | https trên checkout_origin (sai thì Siz chỉ bỏ URL) |
| Vé phim | format ≤ 60, room ≤ 100, seats[] (nhãn ≤ 16), quantity |
| Vé máy bay | flight_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 |
{ "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 }"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èmsig= 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ủaticket_url. - Thẻ trong chat đóng dấu ĐÃ SỬ DỤNG khi
statuslàusedvà ĐÃ 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.
- 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-linktrênlink_origincủa bạn. - Trang
/agent-linkyê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. - Đồ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+ calleraig, rồi chuyển trình duyệt vềreturnkèmlink_request_idvàcode. Từ chối → vềreturnkèmerror=access_denied. - Chỉ chuyển về khi
returnbắ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. - Siz gọi
POST /links/exchange(có chữ ký) để đổi mã lấycustomer_ref. Mã chỉ dùng một lần; mã lạ, hết hạn, đã dùng hoặc saireq→404 NOT_FOUND.
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_deniedPOST /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.
GETkhô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 sangin_paymentvới lần gia hạn duy nhất, giốngpayment-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ăngstate_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).referencephải bằng reference VietQR đang chọn, nếu không →409 INVALID_STATEvớireason: "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/:tokengiả làm cổng thanh toán và xác nhận.
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_ORIGIN | Origin công khai của API mà Siz ký theo (@target-uri), không / cuối |
CHECKOUT_ORIGIN | Origin web app, dùng tạo continue_url, ticket_url, URL sandbox; phải https ở production |
AIG_PUBLIC_KEYS | Khoá công khai theo keyid (mục 3) |
AIG_LINK_RETURN_ORIGINS | Các origin trang /agent-link được quay về (CSV) |
PAYMENT_METHODS | CSV 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_NAME | Tà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_PREFIX | Tiền tố reference (0–10 ký tự A–Z0–9, mặc định PAY); reference = tiền tố + 8 ký tự |
PAYMENT_SANDBOX | 1 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ả
keyidcũ và mới trongAIG_PUBLIC_KEYStrong 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_origindạnghttps, 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_KEYScó khoá thật của Siz (không phải khoá thử) và ánh xạ tới calleraig.- 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 …/tickettrả 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-linkcần đăng nhập, gửiframe-ancestors 'none';AIG_LINK_RETURN_ORIGINSchỉ có origin aig-web. PAYMENT_SANDBOXkhông được đặt;CHECKOUT_ORIGINlàhttps.- Không log chữ ký, mã vào cửa, số tài khoản hay dữ liệu hành khách.