開發文件

從零開始，完成第一筆付款。

本指南帶您完成一次完整串接：驗證身分、建立付款、將顧客導向結帳頁，並透過 Webhook 確認結果。大多數開發者一個下午就能完成。

◷ 沙盒將優先開放給候補名單中的開發者。正式金鑰將在 TujuPay 取得牌照後提供。

1. 開始之前

您需要準備三樣東西。本指南的所有操作都在沙盒中進行，不會有任何真實資金流動。

一個 TujuPay 帳戶。註冊後立即取得測試金鑰，無需審核。
一台能發出 HTTPS 請求的伺服器。任何程式語言皆可，本文範例使用 curl 和 Node.js。
一個用於接收 Webhook 的公開 HTTPS 網址。本機開發時，使用 ngrok 等通道工具即可。

2. 驗證您的請求

每個請求都以 HTTP Basic 驗證方式帶上您的私密金鑰：金鑰作為使用者名稱，密碼留空。測試金鑰以 sk_test_ 開頭，正式金鑰以 sk_live_ 開頭。私密金鑰只能存放在您的伺服器上，切勿放進行動應用程式或瀏覽器端程式碼。

sk_test_… 僅能在沙盒中使用，絕不會動用真實資金。
sk_live_… 將在您的企業通過驗證且 TujuPay 取得牌照後核發。
可隨時在商家後台輪替金鑰。舊金鑰將在 24 小時後失效。

curl

curl https://api.tujupay.com/v1/payments \
  -u sk_test_51HxQ2...:

3. 建立第一筆付款

當顧客準備付款時，在您的伺服器上建立付款。傳送以仙為單位的金額（RM 189.00 即 18900）、您接受的付款方式，以及您自己的訂單編號。請加上 Idempotency-Key，確保重試請求時不會重複建立付款。

amount 是以仙為單位的整數。金額一律不使用小數。
methods 可包含 fpx 和 duitnow_qr。省略此欄位則提供您已啟用的所有付款方式。
reference 由您自訂：建議填入您的訂單 ID，方便在您的系統中對應付款。

Node.js

const res = await fetch("https://api.tujupay.com/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa(process.env.TUJUPAY_SECRET + ":"),
    "Content-Type": "application/json",
    "Idempotency-Key": "order-2214",
  },
  body: JSON.stringify({
    amount: 18900,            // RM 189.00 in sen
    currency: "myr",
    methods: ["fpx", "duitnow_qr"],
    reference: "ORDER-2214",
    return_url: "https://yourshop.my/orders/2214",
  }),
});

const payment = await res.json();
// payment.checkout_url → send the customer here

4. 將顧客導向結帳頁

回應中包含 checkout_url，請將顧客重新導向至此網址。顧客選擇銀行或掃描 QR 碼，在網銀應用程式中核准付款後，會返回您設定的 return_url。

結帳頁支援任何手機，並顯示您的標誌和訂單明細。
顧客返回時，請顯示「處理中」訊息，直到 Webhook 確認結果為止。
不要因為顧客返回就將訂單標記為已付款，請等待 Webhook 通知。

Node.js

// Express example
app.post("/checkout", async (req, res) => {
  const payment = await createPayment(req.body.orderId);
  res.redirect(303, payment.checkout_url);
});

5. 透過 Webhook 確認結果

付款成功或失敗時，我們會向您的 Webhook 網址發送 payment.succeeded 或 payment.failed 事件。驗證簽章後，再處理訂單。Webhook 頁面詳細說明了簽章、重試機制和所有事件。

請在 10 秒內回應任何 2xx 狀態碼，耗時的工作改在背景處理。
每個事件只處理一次：儲存事件 ID，並忽略重複的事件。

6. 正式上線

當您的串接在沙盒中運作正常後，依照以下步驟即可開始收取真實款項。正式金鑰將在 TujuPay 取得牌照且您的企業通過驗證後提供。

在商家後台完成企業驗證：SSM 文件、董事資料和結算銀行帳戶。
將 sk_test_ 換成 sk_live_，並把 Webhook 網址更新為正式環境。
先進行一筆小額真實付款再退款，從頭到尾檢查整個流程。
開啟結算通知，款項到帳時即可收到提醒。