集成流程

本页面记录了两种主要集成路径的端到端流程：收款和出款。

收款流程

通过 QRIS、虚拟账户、银行转账、电子钱包或托管结账页面接受客户付款。

流程图

sequenceDiagram
    participant S as 您的服务器
    participant Z as 支付网关
    participant P as 支付渠道
    participant C as 客户

    S->>Z: 1. 创建支付请求
    Note right of S: POST /api/create/qris<br/>POST /api/create/va<br/>POST /api/create/bank<br/>POST /api/create/ewallet<br/>POST /api/checkout
    Z-->>S: 支付详情（二维码、虚拟账号、链接）
    S->>C: 2. 向客户展示支付信息
    Note right of S: 二维码、虚拟账号、<br/>重定向链接等
    C->>P: 3. 客户完成支付
    P->>Z: 支付通知
    Z->>S: 4. Webhook: payment.v2.completed
    opt 手动验证
        S->>Z: 5. POST /api/check/transaction
        Z-->>S: 交易状态
    end

详细步骤

1. 创建支付请求

根据支付方式选择相应的端点：

请求/响应详情请参阅生成直接支付或结账。

2. 向客户展示支付信息

• QRIS： 显示 data.qr_url 中的二维码图片或编码 data.qr_content
• 虚拟账户 / 银行转账： 显示账号和金额供客户转账
• 电子钱包： 将客户重定向至 data.redirect_url
• 结账： 重定向至 checkout_url — 网关处理支付界面

3. 客户完成支付

客户通过银行应用、电子钱包或扫描二维码完成支付。所有支付都有过期时间，在 data.expired_at 中返回。

4. 接收 Webhook

当支付成功时，网关向您注册的端点发送 payment.v2.completed Webhook：

{
  "event": "payment.v2.completed",
  "timestamp": "2025-01-15T14:35:00+07:00",
  "data": {
    "transaction_id": "...",
    "merchant_transaction_id": "ORDER-001",
    "amount": "50000.00",
    "status": "success"
  }
}

付款过期时不会发送 Webhook。请通过下方的状态查询来确认是否过期。

5.（可选）轮询状态

如果您的 Webhook 端点不可用或需要手动验证：

POST /api/check/transaction
{ "merchant_transaction_id": "ORDER-001" }

详情请参阅检查交易状态。

出款（转账）流程

使用此流程向银行账户汇款（例如提现、退款、佣金支付）。

流程图

sequenceDiagram
    participant S as 您的服务器
    participant Z as 支付网关
    participant B as 收款方银行

    S->>Z: 1. 查询 — 验证账户并预留资金
    Note right of S: POST /api/inquiry<br/>⏱ 有效期 30 分钟
    Z-->>S: inquiry_id、account_name、fee
    S->>Z: 2. 转账 — 执行出款
    Note right of S: POST /api/transfer<br/>{ "inquiry_id": "..." }
    Z->>B: 处理转账
    Z->>S: 3. Webhook 回调
    Note right of Z: disbursement.v2.completed（成功）<br/>disbursement.v2.fail（失败）<br/>disbursement.v2.expired（过期）
    opt 手动验证
        S->>Z: 4. POST /api/check/inquiry
        Z-->>S: 查询状态
    end

详细步骤

1. 创建查询

查询步骤用于验证目标银行账户并从您的余额中预留资金。

POST /api/inquiry
{
    "merchant_transaction_id": "PAYOUT-001",
    "bank_code": "014",
    "account_number": "1234567890",
    "amount": 100000
}

响应包含 inquiry_id、account_name（已验证的账户持有人）和 fee。

2. 执行转账

使用第一步中获得的 inquiry_id：

POST /api/transfer
{
    "inquiry_id": "01jj1g751vqw68ng5546xnda5c"
}

3. 接收 Webhook

网关会发送以下三种 Webhook 事件之一：

每个事件独立触发 — 每笔出款您将恰好收到上述三种事件之一。

4.（可选）轮询状态

POST /api/check/inquiry
{ "merchant_transaction_id": "PAYOUT-001" }

可能的状态值：pending（待处理）、valid（已批准，等待转账）、processing（处理中）、success（成功）、fail（失败）。

详情请参阅检查查询状态。

查询余额

在发起出款之前，您可以查看可用余额：

GET /api/balance

返回 balance（已结算）、reserved_funds（待处理查询预留的资金）和 outstanding_funds（未结算）。

详情请参阅检查余额。