開發者
三次呼叫，一個 webhook。
Gateway 是託管式 checkout，所以整合刻意做得很精簡：建立訂單、將客戶導向付款頁、驗證簽章結果。以下就是全部介面——支付介面、支付方式邏輯、3-D Secure、錢包與收據，都由我們負責建置並持續更新。
概覽
你要整合的對象。
- 透過 HTTPS 的 REST
- JSON 進，JSON 出
- Bearer API 金鑰
- 冪等金鑰
- 簽章 webhook
- 重放攻擊防護
- 測試與正式模式
- iOS 與 Android SDK
- 商店外掛
- 內嵌欄位
快速入門
從零到一筆已付款訂單。
完整的順利流程。金額以最小單位計，reference 由你自訂，checkout URL 就是要將客戶導向的網址。API 基礎 URL 會隨沙盒金鑰一併發給你——將它匯出為 PROTOCORE_API_BASE，下列呼叫即可原樣執行。
建立訂單
一次呼叫，帶入金額、幣別與你自己的 reference。冪等金鑰由你產生——重送的請求會回傳原訂單，而不是建立第二筆。
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'將客戶導向 checkout
回應中會附上 checkout URL，網域是你專屬的 checkout 主機——沙盒發給你的那個，或是指向我們之後的自有網域。直接重新導向，或在 SDK 中開啟；支付方式、錢包與 3-D Secure 都在那個頁面上，你這邊無需開發。
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}驗證簽章結果
付款完成後，已簽章的事件會送達你的端點。先用 webhook 密鑰驗證簽章，再信任任何內容，接著依你已知的 reference 出貨。
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}參考
你真正會用到的端點。
文件中還有更多內容，但大多數整合用到這些就夠了。
Webhooks
後端會收到哪些通知。
每個事件都帶有你建立的訂單 reference，所以你的處理程式只需依類型分支，再於自己這邊查詢即可。
先驗證簽章，再信任內容。
每次傳送都帶有時間戳與針對原始內容的 HMAC 簽章。請以恆定時間比對，拒絕超出容許時間範圍的請求，並將重複的事件 id 視為已處理——收到非 2xx 回應時我們會重試，因此你的處理程式也應具備冪等性。
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}保證
你可以放心依賴的特性。
冪等建立
每次建立訂單都需帶冪等金鑰。重送的請求——無論是逾時、部署或佇列重新投遞之後——都會回傳原訂單，不會重複扣款。
已簽章、防重放的事件
Webhook 帶有含時間戳的 HMAC 簽章與固定的事件 id。傳送失敗會以退避方式重試，直到你的端點回應 2xx，部署期間也不會漏掉任何一筆付款。
一個 reference，貫穿全程
建立時提供的 reference 會出現在 checkout、收據、webhook、撥款與日後的任何退款中。無需在系統間對照第二組識別碼。
測試模式走的是同一條程式路徑
測試金鑰會對測試 session 執行完全相同的流程。測試通過的，就是上線的——差別只在於你送出哪組金鑰，而不是呼叫哪些端點。
測試資料
如何驗證關鍵流程。
以下每種情境都對應一組測試卡，沙盒建立時會隨金鑰一併提供——卡號依沙盒而異，不在此公開，以免發卡組織測試卡號區段調整後失準。無論哪種情境，行為皆可預期：測試要驗證拒絕交易，與驗證成功一樣容易。