整合結帳
建立測試結帳,並串接商品交付流程。
選擇整合方式
完整整合包含建立 Checkout Session、驗證付款 Webhook、避免重複交付商品,以及登錄交付記錄。
自動整合(AI 輔助)
將下方提示詞貼到專案目錄中的 AI 程式編寫工具(Claude Code、Cursor、Codex 等)。代理會取得我們的機器可讀文件並完成完整的測試模式整合,包含結帳、Webhook,以及發生付款爭議或爭議款時作為交付證據的配送記錄;您只需檢視變更、填入 API 金鑰即可上線。
更進一步 — 串接 Tokenz MCP。 若你的 AI 工具支援 MCP,加入我們的 MCP 伺服器後,代理就能直接搜尋文件、建立測試結帳工作階段並驗證 Webhook 簽章 — 一套引導式、可自我驗證的串接流程。下方的提示詞在有無 MCP 的情況下都能運作。
登入(不必貼上 API 金鑰)
使用 https://mcp.tokenz.one/merchant。用戶端會以 OAuth 2.1(authorization code 與 PKCE)引導您登入。請使用 Merchant Dashboard 帳號登入,並在同意時選擇正式或測試模式。不必貼上 API 金鑰。此連線要求 dashboard:read 與 test_api_keys:create 範圍。登入後,測試工具會為該連線自動建立測試金鑰。此網址也接受 secret_test_ 金鑰。
claude mcp add --transport http tokenz https://mcp.tokenz.one/merchant
選用的測試金鑰
https://mcp.tokenz.one/mcp 不使用 OAuth 登入。未帶 Authorization 標頭時,文件與 Webhook 工具即可使用:search_docs、get_doc、list_docs、get_openapi、list_test_cards、verify_webhook_signature、sign_test_webhook_payload、check_auth。測試動作工具需要以 Authorization: Bearer secret_test_... 傳送測試金鑰:create_test_checkout_session、get_checkout_session、get_order、cancel_test_order、create_test_refund、get_refund。正式金鑰會被拒絕。
claude mcp add --transport http tokenz https://mcp.tokenz.one/mcp --header "Authorization: Bearer secret_test_YOUR_KEY_HERE"
提示詞:在測試模式下端到端整合 Tokenz Checkout
You are integrating Tokenz — a Merchant of Record (MoR) checkout — into this project, end to end, in TEST MODE.
If a Tokenz MCP server is connected to you (you will see tools like `search_docs`, `get_openapi`, `create_test_checkout_session`, and `verify_webhook_signature`), use it throughout the steps below: prefer `search_docs`/`get_doc` over fetching raw doc URLs, take test cards from `list_test_cards`, and use `create_test_checkout_session` + `get_order` to prove the integration works against the real API. Everything below still applies either way.
Before writing any code:
1. Detect my project's stack and find the code that grants purchased items to a customer (fulfillment). Then ask me the questions below immediately, and fetch https://docs.tokenz.one/llms-v3.txt while you wait for my answers. It contains the v3 guides and links to the raw OpenAPI contracts. Fetch the linked Checkout Session, Order, and Webhook JSON specs before implementing their requests and payloads; those raw specs are authoritative for fields, constraints, errors, and response formats. Use https://docs.tokenz.one/llms.txt to find any additional guides you need. Stay on v3 for this new integration. If you cannot fetch URLs, ask me to paste the relevant guides and raw contracts.
2. The questions:
- What product(s) should the checkout sell (name, amount, currency)?
- Which environment file should hold my Tokenz test secret key (secret_test_...) and webhook signing secret (e.g. .env.local)? I will fill in the values myself. Remind me that the key needs the `CreateCheckoutSession`, `GetOrder`, and `RegisterDeliveryRecord` permissions.
- Confirm the framework/stack and the fulfillment code you found before patching anything. If the project has no fulfillment code yet, ask me how a paid order should be delivered and which ID identifies the customer.
- If this project only runs locally: how should Tokenz reach the webhook endpoint? (Offer to set up a tunnel such as ngrok or cloudflared, or ask me for a deployed HTTPS URL.)
Constraints (non-negotiable):
- Never hardcode, log, or commit secrets — API keys and webhook signing secrets alike; read them from environment variables only.
- Create Checkout Sessions server-side only; never expose the secret key to the browser.
- Define products and prices server-side; never trust amounts sent by the browser. Amounts are in minor units, and every product item needs a taxCategory from the docs' enum.
- Send `customerInfo.recipientId` on every Checkout Session: my system's ID for the account that receives the purchase. Grant the items to the order's `recipientId` and send the same value as `user.recipientId` in the delivery record.
- Verify webhook signatures (Tokenz-Signature header) over the raw, unparsed request body; do not skip this.
- Fulfill orders from verified webhook events (order.succeeded), never from the customer reaching the success page — redirects prove navigation, webhooks prove payment. Handle webhook retries idempotently, keyed on the event's top-level `id`; the same event can be delivered more than once.
- Register a delivery record with Tokenz for every order you fulfill (POST /v3/order/{orderId}/delivery). This is a required part of the integration, not an extra: the delivery record is the proof of delivery sent to the bank or card issuer when a customer disputes a payment or files a chargeback, and an order without one has no evidence to defend it. Do not skip it, stub it, or offer it to me as optional.
- Build redirect URLs from a configured base URL, not from request headers such as Origin.
- Stay in Tokenz test mode until I explicitly ask to go live.
- Keep changes minimal; do not refactor unrelated code.
- Communicate with me in the language I use with you.
Deliverables — verify each actually works before claiming it is done:
1. A server endpoint that creates a Tokenz Checkout Session and returns its URL.
2. A checkout button/flow that redirects the customer to the hosted checkout.
3. Success, processing, and canceled pages wired to the session's redirect URLs. (Some payment methods settle asynchronously — the processing page is not optional.)
4. A webhook endpoint that receives events, verifies the signature, and updates order state. As soon as the webhook URL is known, tell me so I can register it in the Tokenz Dashboard (remind me: register it in TEST mode; the Dashboard shows the signing secret once, and I will put it into the env file myself — never ask me to paste it in chat) — then keep building while I do that.
5. Delivery registration, for every order the webhook fulfills:
- Order of operations: in the webhook handler, mark the event as processed, grant the items, and store the delivery record (or a job for it) as one transaction or one durable write, and only then acknowledge with 2xx. A retried webhook must find either nothing done or everything done, never granted items with no delivery record; if the project's storage cannot make that atomic, have the handler re-check fulfilled orders that lack a record and create it. Call the Delivery Registration API from outside the webhook response path (a queued job or background task), so a slow or unreachable API never delays the acknowledgement.
- Payload: send the full payload the docs recommend — `status`, `progress`, `at`, `user`, `items` with `deliveredQuantity` (plus the in-app balance before and after, when the item is a currency), `cartContext`, `deliveryContext`, and `deliveryInfo` — built from the real fulfillment data, never from placeholders. `cartContext` and `deliveryContext` describe the customer's device: capture the IP address, user agent, and device ID from the customer's own requests (when the Checkout Session is created, and at delivery if the customer is present), and store them with the order. Never fill them from the webhook request, which comes from Tokenz's servers; leave out a field you do not have.
- One record per delivery: register a failed delivery too (`status: failed`), send one record per delivery when an order is delivered in parts, and never let a retried webhook create a second record for the same delivery.
- Response: treat every entry in `warnings` as a bug and fix it. A failed call must never repeat or undo the fulfillment.
- Retries: each call creates a new record and there is no idempotency key, so keep every record Tokenz has not accepted in the project's own storage, in one of three states. Retryable (Tokenz answered 5xx): re-send automatically, including after a restart. Blocked (Tokenz answered 4xx): fix the cause before re-sending — 403 Forbidden means the key lacks the `RegisterDeliveryRecord` permission (on by default for secret keys), so tell me to use a secret key that has it; 401 Unauthorized means the key is missing, invalid, or revoked, so tell me to fix the key; re-send either once the key changes. Any other 4xx means the request is wrong, so fix it first. Needs review (no answer: timeout or dropped connection): never resend automatically; flag it for me to check.
6. A completed end-to-end test purchase using the test cards from the docs, with the webhook received and verified, the items granted once, and the delivery record accepted (201 Created, no warnings). If you have browser-automation tools, perform the test purchase yourself; otherwise give me exact steps.
7. A short go-live checklist for me: everything that must change to leave test mode (a live secret key with the permissions this integration uses, including `RegisterDeliveryRecord`; live webhook registration with its new signing secret; a stable public webhook URL; real tax/fulfillment handling), plus anything you stubbed.
If any step is blocked (missing key, docs ambiguity, unsupported stack), stop and ask me instead of guessing.
必要條件
請確保您已從 Tokenz 獲取 API 憑證(公鑰和金鑰)。您可以在 Tokenz Dashboard 的開發頁面找到您的憑證。
如果您想了解 Tokenz Checkout 的工作原理,請參閱 Checkout 了解更多詳細資訊。
整合期間請使用測試 API 金鑰(包含 test_,例如 secret_test_...):以測試金鑰建立的結帳工作階段會在測試模式下執行,不會產生實際扣款。上線時再切換為正式金鑰。
設定伺服器
import os
from flask import Flask, request, redirect
from flask_cors import CORS
import requests
# Replace the keys with yours
SECRET_KEY = os.environ.get("SECRET_KEY", "secret_test_YOUR_KEY_HERE")
app = Flask(__name__, static_url_path="")
CORS(app)
root = "../client/build"
@app.route("/", methods=["GET"])
def index():
return redirect("http://localhost:3080")
創建結帳工作階段
在您的伺服器上添加一個端點來創建結帳工作階段。結帳工作階段控制您的客戶在 Tokenz 託管的支付頁面上看到的內容,例如項目、訂單金額、貨幣和可用的支付方式。
定義項目(line item)
總是將您的產品庫存的敏感資訊(如價格和可用性)保存在您的伺服器上,以防止客戶從客戶端進行操作。在創建結帳工作階段時定義產品資訊。
訂單總額一律依 itemDetails 中的價格計算。部分範例中出現的頂層 amount 欄位為選填,但若您提供該欄位,其值必須與 itemDetails 的總額相符,否則請求將被拒絕。
稅金。 本快速入門(及其範例載荷)基於 Merchant of Record(MoR)模式——即 Tokenz 帳戶的預設模式:Tokenz 會自動計算並代收稅金,您只需為每個商品設定 taxCategory。如果您的帳戶被特別設定為 Payment Gateway 模式,則每個 Checkout Session 都必須額外包含頂層 tax 物件(以最小貨幣單位表示,例如 "tax": { "amount": 0, "currency": "USD" });缺少該欄位的請求會被拒絕並回傳 order.tax-required。如果不確定您的帳戶使用哪種模式,請與您的 Tokenz 聯絡人確認。
指定接收者
將 customerInfo.recipientId 設定為您自己系統中接收此次購買的帳戶 ID,例如玩家在遊戲中的帳戶 ID。在 Merchant of Record 模式下此欄位為必填:未提供該欄位的 Checkout Session 會被拒絕,錯誤為 checkoutsession.recipient-id-required。在 Payment Gateway 模式下此欄位為選填。
Tokenz 會將該值複製到訂單的 recipientId。請將商品發放給該接收者,並在登記交付時將相同的值作為 user.recipientId 傳送。如需提供其他接收者資訊,請使用 customerInfo.recipientInfo。
"customerInfo": {
"recipientId": "user_42931",
"emailAddress": "customer@example.com"
}
每個 Checkout Session 還必須包含 itemDetails、successUrl、pendingUrl 和 cancelUrl。
提供成功和取消的 URL
指定成功和取消頁面的 URL,確保它們是可公開訪問的,以便 Tokenz 可以將客戶轉址過去。您也可以使用相同的 URL 來處理成功和取消狀態。
如果客戶從行動應用程式開始結帳,這些 URL 也可以將客戶帶回應用程式,請參閱返回您的應用程式。
[非必要] 定義可用的支付方式
指定為此結帳向您的客戶提供的支付方式列表。如果未提供支付方式或提供了空列表,則所有可用的支付方式都將顯示給客戶。
[非必要] 限制客戶類型
設定 allowedCustomerTypes 可限制哪些客戶能使用此 Checkout Session 付款:PERSON(個人)、BUSINESS(企業)或兩者。若省略,則兩者皆允許。
"allowedCustomerTypes": ["BUSINESS"]
Checkout Session 會回傳相同的列表。在該限制不適用的工作階段中(例如管理現有訂閱),此欄位不存在。
[非必要] 附加您自己的識別碼與中繼資料
externalOrderId:您系統中的訂單 ID,儲存在產生的訂單上,可在控制台中搜尋。不需唯一。externalSubscriptionId:您系統中的訂閱 ID,當 Checkout Session 建立訂閱時儲存在該訂閱上。metadata:任意 JSON 物件,最大 2 KB。一次性付款時 Tokenz 將其儲存在訂單上,定期付款時儲存在訂閱上,並在 API 回應與 Webhook 中回傳。中繼資料無效的請求會被拒絕,錯誤為metadata.invalid。
將客戶轉址到 Tokenz 結帳頁面
創建工作階段後,將您的客戶轉址到回應中返回的結帳頁面的 URL。
@app.route("/create-tokenz-checkout", methods=['POST'])
def create_tokenz_checkout():
CALLBACK_URL_PREFIX = request.headers['referer']
headers = {"Authorization": f'Bearer {SECRET_KEY}'}
print(headers)
payload = {
"amount": {
"currency": "JPY",
"amount": 5200
},
"itemDetails": [
{
"product": {
"label": "ひとにぎりのエメラルド",
"description": "80+8",
"images": [
"https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
],
"quantity": 3,
"price": {
"currency": "JPY",
"amount": 1200
},
"taxCategory": "DIGITAL_GOODS_AND_SERVICES"
}
},
{
"product": {
"label": "エメラルドの荷車",
"description": "100+10",
"images": [],
"quantity": 1,
"price": {
"currency": "JPY",
"amount": 1600
},
"taxCategory": "DIGITAL_GOODS_AND_SERVICES"
}
}
],
"customerInfo": { "recipientId": "user_42931" },
"successUrl": "http://localhost:9000/success",
"pendingUrl": "http://localhost:9000/pending",
"cancelUrl": "http://localhost:9000/cancel"
}
res = requests.post(
"https://api.tokenz.one/v3/checkoutsession", json=payload, headers=headers
)
session = res.json()
return redirect(session["url"], 303)
建立您的結帳頁面
添加成功頁面
為您提供的結帳工作階段 successUrl 創建一個成功頁面,向您的客戶顯示訂單確認資訊或訂單詳細資訊。客戶成功完成結帳後,Tokenz 將轉址到此頁面。
<!DOCTYPE html>
<html>
<head>
<title>Thanks for your order!</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<section>
<p>
感謝您的惠顧!如果您有任何問題,請發送電子郵件至
<a href="mailto:orders@example.com">orders@example.com</a>。
</p>
</section>
</body>
</html>
添加待處理付款頁面
對於非同步支付方式(如便利店支付或銀行轉賬),支付可能會處於待處理狀態,時間從幾分鐘到幾天不等。為 pendingUrl 添加一個頁面。當客戶關閉異步支付的說明頁面後,Tokenz 會轉址到此頁面。
<!DOCTYPE html>
<html>
<head>
<title>感謝您的訂購!</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<section>
<p>
您的支付正在處理中!我們會在完成後第一時間通知您。
如果您有任何問題,請發送電子郵件至
<a href="mailto:orders@example.com">orders@example.com</a>.
</p>
</section>
</body>
</html>
添加取消頁面
為 cancelUrl 添加另一個頁面。當客戶在結帳中點擊返回按鈕時,Tokenz 會轉址到此頁面。
<!DOCTYPE html>
<html>
<head>
<title>結帳已取消</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<section>
<p>忘記添加商品到購物車了?繼續購物,然後回來支付!</p>
</section>
</body>
</html>
返回您的應用程式
如果客戶從行動應用程式開始結帳,您可以在付款後將客戶帶回應用程式。successUrl、pendingUrl 和 cancelUrl 除了網頁 URL,也接受應用程式連結:
- 通用連結(iOS)或 App Links(Android):已設定由您的應用程式開啟的
https://URL,例如https://example.com/app/purchase-complete。 - 您的應用程式註冊的自訂 URL scheme,例如
myapp://purchase-complete。
每個 URL 必須是 scheme://... 格式的絕對 URL,且不超過 300 個字元。使用 javascript:、data:、vbscript:、file:、blob: 或 about: 的 URL 會被拒絕。
Tokenz 結帳頁面不會自行離開結果頁面。付款結束後,客戶會看到結果頁面,點擊其中的按鈕即開啟 successUrl;若付款仍在處理中,則開啟 pendingUrl;若付款失敗,則開啟 cancelUrl。結帳中的返回按鈕會開啟 cancelUrl。
連結能否開啟您的應用程式,取決於您的應用程式如何註冊該連結,以及顯示結帳頁面的瀏覽器。最穩妥的做法是將 successUrl 設為您自行託管的 https:// 頁面,並在該頁面放置開啟應用程式的按鈕:
<!DOCTYPE html>
<html>
<head>
<title>感謝您的訂購!</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<section>
<p>您的購買已完成。</p>
<a href="myapp://purchase-complete">返回應用程式</a>
</section>
</body>
</html>
應用程式被開啟並不代表客戶已付款。與其他轉址一樣,請依據 order.succeeded Webhook 發放商品。
添加結帳按鈕
最後,添加一個頁面來顯示客戶訂單的預覽。允許他們審核或修改訂單—當他們被轉址到結帳頁面後,訂單內容即為確定狀態,除非創建新的結帳工作階段,否則無法修改訂單。
在您的訂單預覽頁面中添加一個按鈕。當您的客戶點擊此按鈕時,他們會被轉址到 Tokenz 託管的支付頁面。
<!DOCTYPE html>
<html>
<head>
<title>購買新產品</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<section>
<div class="product">
<img src="https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" alt="Treasure chest" />
<div class="description">
<h3>寶箱</h3>
<h5>$1,000</h5>
</div>
</div>
<form action="/create-tokenz-checkout" method="POST">
<button type="submit" id="checkout-button">結帳</button>
</form>
</section>
</body>
</html>
驗證整合
- 完成一筆測試付款,確認訂單成功。
- 驗證 Webhook 簽章,確保重複事件不會造成重複交付。
- 收到
order.succeeded後交付商品,並登錄交付記錄。 - 切換正式金鑰前,檢查成功、處理中與取消頁面。