inquiryPayment

2026-05-29 08:41

POST /v2/payments/inquiryPayment

POS 调用 inquiryPayment 接口来查询支付状态，通常在 POS 未从支付终端收到交易响应时使用。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

请求参数

参数名称

类型

是否必需

描述

paymentRequestId

String

是

由 POS 提供商定义的用于标识支付请求的唯一 ID。

最大长度：64 个字符。
仅允许字母（a-z、A-Z）、数字（0-9）和下划线（_）。

注意：此参数对每个门店是唯一的。使用 paymentRequestId 调用 inquiryPayment 接口查询支付状态。每次调用将返回最新的支付结果。

响应参数

参数名称	类型	是否必需	描述
result	Result	是	接口调用的结果。
paymentRequestId	String	是	由 POS 提供商定义的用于标识支付请求的唯一 ID。最大长度：64 个字符。仅允许字母（a-z、A-Z）、数字（0-9）和下划线（_）。注意：此参数对每个门店是唯一的。使用 paymentRequestId 调用 inquiryPayment 接口查询支付状态。每次调用将返回最新的支付结果。
paymentId	String	是	由 POS 提供商定义的用于标识支付的唯一 ID，与交易报告中的 paymentId 一致。
paymentCreateTime	String	是	创建支付的日期和时间。该值遵循 ISO 8601 标准格式，例如，"2019-11-27T12:01:01+08:00"。
paymentTime	String	是	支付达到成功最终状态的日期和时间。该值遵循 ISO 8601 标准格式，例如，"2019-11-27T12:01:01+08:00"。
paymentStatus	String	是	表示支付的最终状态。有效值为： `SUCCESS`：支付成功。 `FAIL`：支付失败。 `PROCESSING`：支付处理中。 `CANCELLED`：支付取消。 `PENDING`：支付完成，等待最终支付结果。
paymentAmount	Amount	是	商户请求以订单币种接收的支付金额。
paymentMethod	String	是	商户或收单机构用于收取付款的支付方式。请参阅支持的支付方式了解更多信息。

Result

参数名称	类型	是否必需	描述
resultStatus	String	是	结果状态。有效值为： `S`：成功 `F`：失败 `U`：未知
resultCode	String	否	结果码。（最大长度：64 个字符）
resultMessage	String	否	详细描述结果码的结果消息。（最大长度：256 个字符）

Amount

参数名称	类型	是否必需	描述
value	Integer	是	货币最小单位的金额值。例如，`10000` 表示新加坡元 100.00。（取值范围：0-2147483647）
currency	String	是	遵循 ISO-4217 标准的 3 个字符的货币代码。例如，`USD`。（最大长度：3 个字符）

结果码

结果码	状态码	结果信息	后续操作
`SUCCESS`	`S`	成功	无需后续操作。
`PROCESS_FAIL`	`F`	发生常规业务故障。请勿重试。	联系 Antom 技术支持。
`PARAM_ILLEGAL`	`F`	参数名称或值不符合指定要求。结果消息会根据具体错误而有所不同。	检查请求参数（包括头部参数和主体参数）是否正确有效。有关接口传参的更多信息请参阅请求头。
`INVALID_API`	`F`	调用的接口无效。	检查进行接口调用时是否使用了正确的接口名称。接口名称不区分大小写。
`CLIENT_INVALID`	`F`	客户端 ID 无效。	检查是否使用了正确的客户端 ID。支付终端集成使用支付终端的序列号（SN）作为客户端 ID。
`INVALID_SIGNATURE`	`F`	签名未通过验证。	参考集成示例代码，检查是否使用了正确的公钥、签名消息和签名算法。
`INVALID_ENCRPT_DATA`	`F`	加密数据无效。	参考集成示例代码，检查是否使用了正确的加密数据。
`METHOD_NOT_SUPPORTED`	`F`	服务器未实现请求的 HTTP 方法。	确保 HTTP 方法为 `POST`。
`TERMINAL_NOT_LOGIN`	`F`	支付终端未登录。	登录支付终端。
`TERMINAL_BUSY`	`F`	支付终端繁忙。	稍后重试。
`PAYMENT_NOT_EXIST`	`F`	支付不存在。	联系 Antom 技术支持排查问题。
`UNKNOWN_EXCEPTION`	`U`	未知原因引起的接口调用失败。	重新调用接口。

示例

以下代码展示了一个请求报文：

copy
{
  "paymentRequestId": "pay_1089760038715669_1027757450XXXXX"
}

以下代码展示了一个响应报文：

copy
{
  "result":{
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentRequestId": "pay_1089760038715669_1027757450XXXXX",
  "paymentId": "202502081140108001001888202003XXXXX",
  "paymentCreateTime": "2025-02-08T12:01:01+08:00",
  "paymentTime": "2025-02-08T12:01:01+08:00",
  "paymentStatus": "Success",
  "paymentAmount":{
    "currency": "SGD",
    "value": "50000"
  },
  "paymentMethod":"CARD"
}