开发文档

从零开始，完成第一笔付款。

本指南带您走完一次完整的集成：身份验证、创建付款、引导顾客前往结账页面，并通过 Webhook 确认结果。大多数开发者一个下午就能完成。

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

1. 开始之前

您需要准备三样东西。本指南的所有操作都在沙盒中进行，不会转移任何真实资金。

一个 TujuPay 账户。注册后即可立即获得测试密钥，无需审核。
一台能发出 HTTPS 请求的服务器。任何编程语言都可以，本文示例使用 curl 和 Node.js。
一个用于接收 Webhook 的公开 HTTPS URL。本地开发时，可以使用 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，请将顾客重定向到该地址。顾客选择银行或扫描二维码，在网银应用中批准付款后，会返回您设置的 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 URL 发送 payment.succeeded 或 payment.failed 事件。先验证签名，再处理订单。Webhook 页面详细说明了签名、重试机制以及每一种事件。

请在 10 秒内返回任意 2xx 状态码，耗时的工作放到后台处理。
每个事件只处理一次：保存事件 ID，忽略重复的事件。

6. 正式上线

集成在沙盒中运行无误后，按以下步骤开始接收真实付款。TujuPay 获得牌照且您的业务完成验证后，才会提供正式密钥。

在商家后台完成业务验证：SSM 文件、董事资料和结算银行账户。
将 sk_test_ 换成 sk_live_，并把 Webhook URL 更新为正式环境地址。
进行一笔小额真实付款并退款，从头到尾检查整个流程。
开启结算提醒，款项转入银行时第一时间知道。