跳转到内容
PGSwift Docs
文档/查询

查询

使用此接口创建付款查询请求。

POST /api/inquiry

请求

名称类型必填输入校验描述
merchant_transaction_idstringtrue客户为商户提供的唯一标识符
bank_codestringtrue与该交易关联的银行代码（参见附录）。
amountnumbertrue数字类型，1–12 位以数字格式表示的交易金额
account_numberstringtrue

数字类型，1–30 位


客户用于该交易的银行账号。
customer_namestringtrue长度在 5–25 个字符之间，允许字符：a–z、A–Z、0–9、-（短横线）、（空格）与本次交易相关的客户姓名
{
    "merchant_transaction_id": "RP123333333",
    "amount": 100000,
    "bank_code": "014",
    "account_number": "0123456789",
    "customer_name": "John Doe"
}

响应

名称描述
status操作状态指示器。true 表示成功，false 表示失败。
code机器可读的错误代码，仅在带代码的拒绝响应中出现：INVALID_BANK_CODE 和 INVALID_ACCOUNT_NUMBER（HTTP 400）、PAYOUT_NOT_CONFIGURED（HTTP 403），以及 INQUIRY_IN_PROGRESS（HTTP 409 — 参见下方并发部分）。参见下方响应代码。请以此字段为准，不要依赖 message。
message在重放的查询（例如 "Inquiry retrieved successfully"）以及失败情形下出现；在新创建且未失败的查询中不会出现。
data查询详情。在校验被拒绝（400/403）、并发锁定响应（409）、内部错误（HTTP 200，status:false，仅包含 message）、以及通用 500 错误时为 null。
data.inquiry_id查询的唯一标识符。
data.merchant_transaction_id商户提供的交易标识符。
data.status当前查询状态：pending（待处理）、valid（已批准，等待转账）、processing（处理中）、success（成功）、fail（失败）。相同的状态列表请参阅 检查查询状态。
data.account_number与该交易关联的银行账号。
data.account_name账户持有人姓名（如不可用，可为 null）。
data.bank_code交易使用的银行代码。
data.bank_name处理该交易的银行名称。
data.amount交易金额。新创建且未失败的查询中为请求金额，数字类型；重放及失败的查询中为实际入账给收款人的金额，字符串类型，保留两位小数。
data.fee适用的交易费用，字符串格式，保留两位小数（例如 "5500.00"）。
data.requested_amount客户请求出款的金额，字符串格式，保留两位小数。新创建、重放及失败的查询中均相同。
data.user_receives实际入账给收款人的金额，字符串格式，保留两位小数。charged_to_user 时等于 requested_amount 减去 fee；charged_to_client 时等于 requested_amount。
data.payout_fee_type费用收取模式：charged_to_user（费用从请求金额中扣除）或 charged_to_client（费用在请求金额之外从客户余额中收取）。
data.reason失败原因。仅在 data.status 为 fail 时出现。
data.payment_at完成时间戳，服务器时间（UTC+7，无偏移量），YYYY-MM-DD HH:MM:SS 格式（例如 "2026-08-13 09:12:45"），与 data.expired_at 格式一致。仅在 data.status 为 success 时出现。
data.expired_at查询过期时间戳，服务器时间（UTC+7，无偏移量），YYYY-MM-DD HH:MM:SS 格式（例如 "2026-08-13 09:30:00"）。只要 data.status 不为 fail 就会出现。
data.expired_at_iso与 expired_at 相同的过期时间，ISO 8601 格式并带偏移量（例如 "2025-02-26T19:00:00+07:00"）。所有渠道格式一致。expired_at 为 null 时为 null。

当 data.status 为 fail 时，data 包含与其他响应相同的字段集合，并额外包含 reason，但不包含 payment_at 和 expired_at。请注意，失败的查询中 account_name 通常为 null — 对于未通过校验的查询，银行从未确认过账户持有人姓名。

{
    "status": true,
    "data": {
        "inquiry_id": "01jj1g751vqw68ng5546xnda5c",
        "merchant_transaction_id": "RP123333333",
        "status": "valid",
        "account_number": "0123456789",
        "account_name": "John Doe",
        "bank_code": "014",
        "bank_name": "Bank Central Asia",
        "amount": 100000,
        "fee": "5500.00",
        "requested_amount": "100000.00",
        "user_receives": "100000.00",
        "payout_fee_type": "charged_to_client",
        "expired_at": "2026-08-13 09:30:00",
        "expired_at_iso": "2026-08-13T09:30:00+07:00"
    }
}

幂等性

使用相同的 merchant_transaction_id 再次调用此端点，不会创建第二条查询 — 系统会返回该查询当前的 data.status。fail 状态的查询是终态：其 merchant_transaction_id 不能被复用；请使用新的 merchant_transaction_id 重新发起。

并发

如果两个携带相同 merchant_transaction_id 的请求同时到达，第二个请求将收到 HTTP 409，并带有 code: "INQUIRY_IN_PROGRESS" — 稍等片刻后重试即可获取已存储的查询。

{
    "status": false,
    "code": "INQUIRY_IN_PROGRESS",
    "message": "A request with the same merchant_transaction_id is already being processed. Please wait before retrying.",
    "data": null
}

响应代码

HTTPcodeMessage建议操作
400INVALID_BANK_CODEInvalid bank code.使用附录中的有效代码后重新发送
400INVALID_ACCOUNT_NUMBERInvalid account number maximum 30 digits.修正账号后重新发送
403PAYOUT_NOT_CONFIGUREDPayout is not configured, please contact support.请联系支持团队
409INQUIRY_IN_PROGRESS参见上方示例稍作延迟后重试，即可获取已存储的查询

两个端点全部错误 code 的完整列表，以及代码与字段稳定性约定，请参阅完整的错误代码参考。

© 2026 PGSwift. 保留所有权利。