PAYWISE 公开 API — v1

认证

除服务商 Webhook 接口外，每个请求都需要 API 密钥，可在仪表盘的 API 密钥 中生成。

Authorization: Bearer pw_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 完整密钥仅在创建时显示一次，PAYWISE 只保存其哈希值。每个 API 密钥的速率限制为每分钟 60 次请求，超出时返回 429 RATE_LIMITED。每个响应（无论成功或失败）都带有 X-Request-Id 请求头，也会显示在 API 日志的对应行中。
• 您可以在 API 密钥页面将每个密钥限制为您服务器的 IP 地址或 CIDR 网段。来自其他地址的请求将返回 403 IP_NOT_ALLOWED，并会通知您。

环境

每个 API 密钥只属于一个环境，可以直接从前缀看出：

响应结构

每个响应都只会是以下两种结构之一。

{
    "success": true,
    "data": {
        "…": "…"
    }
}

{
    "success": false,
    "error": {
        "code": "INVALID_API_KEY",
        "message": "Invalid API credentials."
    }
}

错误码

支付

创建交易

{
    "merchant_reference": "ORDER-1042",
    "amount": 250000,
    "currency": "IDR",
    "payment_method": "QRIS",
    "customer_id": "user-1042",
    "customer_name": "Budi Santoso"
}

{
    "merchant_reference": "ORDER-1043",
    "amount": 100,
    "currency": "USDT",
    "payment_method": "USDT",
    "network": "BEP20",
    "customer_id": "user-1043"
}

{
    "success": true,
    "data": {
        "reference": "PW20260921143022AB3F",
        "merchant_reference": "ORDER-1042",
        "payment_method": "QRIS",
        "environment": "sandbox",
        "customer_id": "user-1042",
        "customer_name": "Budi Santoso",
        "amount": 250000,
        "fee_bearer": "merchant",
        "currency": "IDR",
        "network": null,
        "status": "pending",
        "created_at": "2026-09-21T14:30:22+00:00",
        "paid_at": null,
        "qr_string": "SANDBOX-QRIS-PW20260921143022AB3F-NOT-PAYABLE",
        "pay_address": null,
        "pay_amount": 250000,
        "expires_at": "2026-09-21T14:50:22+00:00",
        "checkout_url": "https://checkout.paywise.asia/Xk7p2QaZ9mRt"
    }
}

USDT：请向客户展示 pay_address（BEP20 地址）和 pay_amount，即需要转账的确切 USDT 数额。pay_amount 等于 amount 加上由客户承担的网络费和处理费，因此您将收到完整的 amount。地址有效期为 60 分钟（expires_at）；之后到账的款项仍会被确认。少于 pay_amount 的付款不会被标记为已支付。

交易费用由谁承担按网站在 控制台 → 网站与 Webhook 中设置。当 fee_bearer 为 customer 时，客户支付 pay_amount（金额加费用：渲染 QR 字符串或显示此金额），您正好收到 amount；webhook 和您的控制台显示 amount。请告知客户价格已包含服务费。否则 QRIS 的 pay_amount 等于 amount。更改仅适用于新交易。

托管支付页面

在 控制台 → 网站与 Webhook 中为网站开启托管支付页面。该网站的交易（由 website 指定、与 return_url 匹配，或默认网站）会附带 checkout_url（否则为 null）：由 PAYWISE 托管的页面，向客户展示二维码（QRIS）或充值地址及确切金额（USDT）、倒计时以及自动更新的支付状态。将客户跳转到该页面，或在新标签页中打开。您也可以继续自行展示 qr_string 或 pay_address。

付款成功、过期或失败后，页面会将客户送回您在 控制台 → 网站与 Webhook 中为网站设置的返回 URL（默认网站，或 website 指定的网站）。传入 return_url 可为单笔付款覆盖：必须是 https 且位于这些域名（或其子域名）上，否则返回 422 RETURN_URL_NOT_ALLOWED。PAYWISE 会在其后附加结果：

https://shop.example.com/thanks?reference=PW20260921143022AB3F&merchant_reference=ORDER-1042&status=paid

查询交易

{reference} 是创建交易时 PAYWISE 返回的参考号，而不是您自己的 merchant_reference。

交易列表

该密钥所属环境中的交易，按时间倒序：每页 20 条，通过 per_page 最多 100 条。所有筛选条件均为可选，可组合使用。每一项与 GET /api/v1/transactions/{reference} 返回的对象相同。

{
    "success": true,
    "data": [
        {
            "reference": "PW20260921143022AB3F",
            "merchant_reference": "ORDER-1042",
            "payment_method": "QRIS",
            "status": "paid",
            "amount": 250000,
            "currency": "IDR",
            "…": "…"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "last_page": 1
    }
}

meta 包含当前页码、每页数量、匹配交易总数和最后一页。

交易状态

数据库、本 API、商户仪表盘和管理员仪表盘使用完全一致的状态值。

提现

提现

从您的服务器申请提取已结算资金：与控制台 → 提现相同，最低额、最高额、手续费、可用资金和自动出款规则都相同。只有正式密钥可以申请（沙盒密钥会收到 403 LIVE_KEY_REQUIRED）；没有邮件验证码，正式密钥本身即授权出款。请只在服务器上保存密钥，并考虑在 API 密钥页面设置允许的 IP 列表。

amount 是到账金额。提现手续费（QRIS Rp3.000，USDT 1.00 USDT）另外加收，从可用资金中扣除；响应中显示 amount（扣除额）、fee 和 payout_amount（到账额）。每笔限额：QRIS Rp25.000 – Rp20.000.000，USDT 10.00 USDT – 10,000.00 USDT。

curl -X POST https://paywise.asia/api/v1/withdrawals \
  -H "Authorization: Bearer pw_live_…" \
  -H "Idempotency-Key: payout-2026-09-27-001" \
  -H "Content-Type: application/json" \
  -d '{"payment_method":"QRIS","amount":1500000,"bank_code":"014","account_number":"1234567890"}'

{
    "success": true,
    "data": {
        "reference": "PWD20260927090112C4DQ",
        "payment_method": "QRIS",
        "environment": "live",
        "payout_method": "bank_transfer",
        "currency": "IDR",
        "network": null,
        "amount": 1503000,
        "fee": 3000,
        "payout_amount": 1500000,
        "status": "requested",
        "destination": {
            "bank_code": "014",
            "bank_name": "BCA",
            "account_number": "1234567890"
        },
        "reason": null,
        "requested_at": "2026-09-27T02:01:12+00:00",
        "completed_at": null,
        "closed_at": null
    }
}

422 INSUFFICIENT_FUNDS 表示金额加手续费超过该方式已结算且未提取的资金；error.available 为当前可申请的最大金额。QRIS 资金每天分几批结算；USDT 资金付款即结算。

提现从 requested 开始，经过 approved 和 processing 到 completed，或以 failed 或 rejected 结束（附 reason）。可通过 withdrawal.* webhook 或下方接口跟踪。

可用资金

密钥所属环境中每种支付方式的资金，与提现页面一致：当前可提现、等待下一批结算的金额、当前单笔提现的最大到账金额（max_withdrawal）以及每笔提现的限额和手续费。

{
    "success": true,
    "data": {
        "environment": "live",
        "methods": {
            "QRIS": {
                "currency": "IDR",
                "available": 1250000,
                "awaiting_settlement": 480000,
                "next_settlement_at": "2026-09-28T08:00:00+00:00",
                "next_settlement_amount": 480000,
                "max_withdrawal": 1245000,
                "withdrawal": {
                    "min": 25000,
                    "max": 20000000,
                    "fee": 5000
                }
            },
            "USDT": {
                "…": "…"
            }
        }
    }
}

Webhook

Webhook

PAYWISE → 您

在 仪表盘 → 网站与 Webhook 中配置 Webhook 地址和事件。当交易状态变更为已订阅的事件时，PAYWISE 会发送：

POST <your webhook_url>
Content-Type: application/json
X-PAYWISE-Signature: <hex-encoded HMAC-SHA256>

Webhook 从 217.217.253.90 · 2407:3640:2358:7339::1 发出。如果您的防火墙只接受已知地址，请允许这些地址；每次投递仍需验证签名。此列表如有变更会提前公告。

多个网站部署在不同服务器上？可在 控制台 → 网站与 Webhook 中为网站设置独立的 Webhook URL。该网站的付款（由 website 指定、与 return_url 匹配，或默认网站）将发送到那里；其余仍发送到您的主 Webhook URL。所有 Webhook 都使用同一个密钥签名。之前已有独立密钥的网站会继续使用它，直到您在该页面将其切换为主密钥。

每次投递尝试都会记录在“网站与 Webhook”页面：事件、尝试次数、您的接口实际返回的 HTTP 状态（超时则为空）以及最多 2 KB 的响应内容。投递失败会自动重试，您也可以在交易页面重新发送。

提现

提现事件 withdrawal.completed · withdrawal.failed · withdrawal.rejected 会在您的提现完成、失败或被拒绝时发送到您的主 Webhook URL（失败或被拒绝的金额可再次提现）。请在“网站与 Webhook”页面订阅。reason 说明失败或被拒绝的原因，完成时为 null。

{
    "event": "withdrawal.completed",
    "data": {
        "reference": "PWD20260925090112C4DQ",
        "payment_method": "QRIS",
        "environment": "live",
        "payout_method": "bank_transfer",
        "currency": "IDR",
        "network": null,
        "amount": 1500000,
        "fee": 5000,
        "payout_amount": 1495000,
        "status": "completed",
        "reason": null,
        "requested_at": "2026-09-25T02:01:12+00:00",
        "completed_at": "2026-09-25T02:03:40+00:00",
        "closed_at": null
    }
}