API 參考

TujuPay API，逐欄說明。

基於 HTTPS、行為可預期的 REST API。請求可使用表單編碼或 JSON，回應一律為 JSON，所有金額均為以仙為單位的整數。

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

基本資訊

基礎網址: https://api.tujupay.com/v1
身分驗證: HTTP Basic，以私密金鑰作為使用者名稱
金額: 以仙為單位的整數。RM 189.00 即 18900
幣別: myr
冪等性: 每個 POST 請求都要帶上 Idempotency-Key 標頭。冪等金鑰保留 24 小時
版本控制: 傳送 TujuPay-Version: 2026-10-01 以固定版本
分頁: limit（1 至 100）和 starting_after，回傳 has_more

Payment 物件

一個 Payment 代表顧客向您付款的一次嘗試，會依序經歷以下狀態。

欄位	類型	說明
id	string	唯一 ID，以 pay_ 開頭
status	enum	requires_payment、processing、succeeded、failed、expired 或 refunded
amount	integer	以仙為單位的金額
currency	string	固定為 myr
methods	array	結帳時提供的付款方式，例如 fpx 和 duitnow_qr
method_used	string	顧客實際使用的付款方式
reference	string	您自己的訂單編號
checkout_url	string	顧客付款的結帳頁網址
payout_date	date	此筆付款結算給您的工作日
created_at	timestamp	付款建立時間，採 ISO 8601 格式

付款狀態

1requires_payment已建立，等待顧客付款
2processing顧客已核准，銀行正在確認
3succeeded已付款，可安心處理訂單
4failed遭銀行拒絕，或顧客放棄付款
5expired30 分鐘內未付款。如需重試，請建立新的付款
6refunded已全額退款給顧客

端點

POST/v1/payments

建立付款

建立一筆付款，並回傳可導向顧客的 checkout_url。

請求

curl

curl https://api.tujupay.com/v1/payments \
  -u sk_test_51HxQ2...: \
  -H "Idempotency-Key: order-2214" \
  -d amount=18900 \
  -d currency=myr \
  -d "methods[]=fpx" \
  -d "methods[]=duitnow_qr" \
  -d reference=ORDER-2214 \
  -d return_url=https://yourshop.my/orders/2214

回應

JSON

{
  "id": "pay_3Kx9LmQ2",
  "status": "requires_payment",
  "amount": 18900,
  "currency": "myr",
  "methods": ["fpx", "duitnow_qr"],
  "reference": "ORDER-2214",
  "checkout_url": "https://pay.tujupay.com/c/3Kx9LmQ2",
  "payout_date": null,
  "created_at": "2026-10-09T10:42:00+08:00"
}

GET/v1/payments/{id}

查詢付款

回傳付款的最新狀態。漏收 Webhook 時可作為備援。

請求

curl

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

回應

JSON

{
  "id": "pay_3Kx9LmQ2",
  "status": "succeeded",
  "amount": 18900,
  "method_used": "fpx",
  "payout_date": "2026-10-09"
}

POST/v1/refunds

退款

對已成功的付款進行全額或部分退款。省略 amount 即全額退款。

請求

curl

curl https://api.tujupay.com/v1/refunds \
  -u sk_test_51HxQ2...: \
  -H "Idempotency-Key: refund-2214-1" \
  -d payment=pay_3Kx9LmQ2 \
  -d amount=5000

回應

JSON

{
  "id": "re_7Pq1Xs",
  "payment": "pay_3Kx9LmQ2",
  "amount": 5000,
  "status": "processing"
}

POST/v1/payment_links

建立付款連結

建立可分享的連結，方便在聊天或社群媒體上銷售。

請求

curl

curl https://api.tujupay.com/v1/payment_links \
  -u sk_test_51HxQ2...: \
  -d amount=6500 \
  -d "description=Kek Lapis Sarawak, 1 box" \
  -d single_use=true

回應

JSON

{
  "id": "plink_9Ad2",
  "url": "https://pay.tujupay.com/l/kek-lapis",
  "amount": 6500,
  "single_use": true,
  "active": true
}

GET/v1/payouts

列出結算

列出轉入您銀行的結算，由新到舊排列，每筆附對帳單。

請求

curl

curl "https://api.tujupay.com/v1/payouts?limit=2" \
  -u sk_test_51HxQ2...:

回應

JSON

{
  "data": [
    { "id": "po_1Tz", "amount": 320760, "status": "paid", "arrival_date": "2026-10-09" },
    { "id": "po_0Ym", "amount": 291840, "status": "paid", "arrival_date": "2026-10-08" }
  ],
  "has_more": true
}

錯誤

發生錯誤時，會回傳標準 HTTP 狀態碼，以及包含 type、code 和易讀說明 message 的 JSON 內容。

狀態碼	代碼	含義
400	invalid_request	參數缺漏或有誤，訊息中會指出是哪一個
401	unauthorized	API 金鑰缺漏、錯誤或已被撤銷
404	not_found	目前模式下找不到該 ID 的物件
409	idempotency_conflict	同一個 Idempotency-Key 搭配了不同的參數
429	rate_limited	請求過多。請稍候並以退避方式重試
500	server_error	我們這邊出了問題。可使用相同的冪等金鑰安全重試

JSON

{
  "error": {
    "type": "invalid_request",
    "code": "amount_too_small",
    "message": "amount must be at least 100 sen (RM 1.00).",
    "param": "amount"
  }
}