检查交易状态 · PGSwift Docs

使用此接口检查交易状态。如提供了 RRN 参数，该参数将在搜索中优先使用。

POST /api/check/transaction

请求

名称	类型	必填	描述
merchant_transaction_id	string	false	商户提供的交易标识符。
rrn	string	false	支付交易的检索参考号（RRN）。当提供 RRN 时，将优先用于搜索。

{
  "merchant_transaction_id": "INQ12300456",
  "rrn": "015221245517"
}

响应

名称	描述
status	请求状态指示器。成功时为 true，失败时为 false。
data.status	当前交易状态：Success、Pending 或 Fail，以首字母大写（TitleCase）形式返回。参见状态值。
data.transaction_id	系统生成的唯一交易标识符。
data.merchant_transaction_id	商户提供的交易标识符。
data.amount	交易金额，字符串格式，保留两位小数（例如 `"100000.00"`）。
data.channel	该交易使用的支付渠道，格式取决于支付类型。参见渠道值。
data.payment_channel	标准化支付渠道，所有支付类型和服务商使用同一格式：例如 `QRIS`、`VA_BRI`、`BANK_BCA`、`EWALLET_DANA`（支付类型前缀 + 附录中的代码）。无法确定渠道时为 null。建议优先使用此字段而非 `channel`。
data.created_at	交易创建时间戳。
data.updated_at	交易最后更新时间戳。
data.service_fee_rate	按 `amount` 收取的百分比费率，例如 `"4.00"` 表示 4%。参见费用计算。
data.service_fee_amount	每笔交易收取的固定费用。此字段不是总费用，总费用见 `service_fee_final`。
data.service_fee_final	从交易中扣除的总费用，即百分比费用加上 `service_fee_amount`。
data.nett_amount	存入商户账户的金额，即 `amount` 减去 `service_fee_final`。
data.rrn	支付交易的检索参考号（RRN）
data.expired_at	支付过期时间。格式取决于支付渠道：`QRIS` 为 ISO 8601 UTC；其他渠道为服务器时间（UTC+7，无偏移量），格式 `YYYY-MM-DD HH:MM:SS`。无支付或不适用时为 null。

{
    "status": true,
    "data": {
        "status": "Success",
        "transaction_id": "0aa59d5a-2a10-45be-a174-f7b954113d12",
        "payment_channel": "QRIS",
        "created_at": "2025-01-01T00:00:00.000000Z",
        "updated_at": "2025-01-01T12:00:00.000000Z",
        "merchant_transaction_id": "INQ12300456",
        "amount": "100000.00",
        "channel": "QRIS",
        "service_fee_rate": "4.00",
        "service_fee_amount": "0.00",
        "service_fee_final": "4000.00",
        "nett_amount": "96000.00",
        "rrn": "987654321",
        "expired_at": "2025-02-26T12:00:00.000000Z"
    }
}

{
    "status": false,
    "data": null,
    "message": "Error description"
}

费用计算

所有费用均由商户承担，并从 amount 中扣除。

service_fee_final = amount × service_fee_rate / 100 + service_fee_amount
nett_amount       = amount − service_fee_final

百分比费用部分先四舍五入保留两位小数，再加上 service_fee_amount。

以上示例中，100000.00 × 4 / 100 + 0.00 = 4000.00，因此 nett_amount 为 96000.00。

状态值

此接口返回的 data.status 为首字母大写（TitleCase）：Success、Pending 或 Fail。收款 Webhook（V1 与 V2）发送的相同状态为小写（success、fail）。

渠道值

data.channel 的格式取决于支付类型：

支付类型	格式	示例
QRIS	`QRIS`	`QRIS`
虚拟账户	不带前缀的银行代码（参见虚拟账户代码）	`BCA`、`BRI`、`MDR`
银行账户	`BANK_` 加银行代码（参见银行账户代码）	`BANK_BCA`
电子钱包	电子钱包代码（参见电子钱包代码）	`DANA`、`OVO`