API 参考

TujuPay API，逐个字段详解。

基于 HTTPS、行为可预期的 REST API。请求可采用表单编码或 JSON，响应始终为 JSON，所有金额均为以仙为单位的整数。

◷ 沙盒将先向候补名单中的开发者开放。TujuPay 获得牌照后，才会提供正式密钥。

基本信息

基础 URL: 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	参数缺失或有误，message 会指明是哪个参数
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"
  }
}