支付结果查询

2024-12-19 05:40

POST /v1/payments/inquiryPayment

使用此接口查询先前提交的支付请求的交易状态和其他信息。

结构

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

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

paymentRequestId String

商户为识别支付请求而分配的专属 ID。paymentRequestId 和 paymentId 不能都为null。如果两者都指定，paymentId 优先。

更多信息：

最大长度：64 字符

paymentId String

Antom 为识别支付而分配的支付 ID。paymentRequestId 和 paymentId 不能都为null。paymentId 与 paymentRequestId 之间存在一一对应的关系。如果同时指定了两者，paymentId 优先。

更多信息：

最大长度：64 字符

merchantAccountId String

用于识别商户账户的商户 ID。

注意：当您在多个地点使用同一个客户端 ID 时，请指定此参数。

更多信息：

最大长度：32 字符

出参

result Result REQUIRED

请求调用结果的信息。

注意：此字段不表示支付结果。此字段仅表示查询支付接口是否调用成功。

Show child parameters

paymentStatus String

表明支付结果。有效值包括：

SUCCESS：支付成功。
FAIL：支付失败。
PROCESSING：支付处理中。
CANCELLED：支付已取消。
PENDING：支付完成，等待最终支付结果。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

paymentResultCode String

不同支付状态的结果代码。可能的支付结果代码列在此页面的 支付结果代码表 中。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

paymentResultMessage String

解释支付结果代码的返回消息。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：256 字符

paymentRequestId String

商户为识别支付请求而分配的专属 ID。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

paymentId String

Antom 为识别支付而分配的支付 ID。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

paymentAmount Amount

商家在订单币种中请求接收的支付金额。

Show child parameters

paymentCreateTime Datetime

支付创建的日期和时间。

注意：此字段在接口调用成功（result.resultStatus 的值为S）时返回。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

paymentTime Datetime

支付成功达到最终状态的日期和时间。

注意：此字段仅在支付达到最终成功状态（paymentStatus的值为SUCCESS）时返回。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

pspCustomerInfo PspCustomerInfo

客户信息，对应于Alipay+支付方式。

注意：当Alipay+支付方式能够提供相关信息时，此字段会被返回。

Show child parameters

redirectActionForm RedirectActionForm

关于跳转操作的信息。

注意：当 paymentResultCode 的值为PAYMENT_IN_PROCESS时，此字段会被返回。

Show child parameters

acquirerReferenceNo String

非 Antom 收单机构为交易分配的交易 ID。

更多信息：

最大长度：64 字符

transactions Array<Transaction>

关于交易的后续操作信息。

注意：当交易存在退款或请款时，此参数会被返回。

Show child parameters

customsDeclarationAmount Amount

用于海关报关的总金额。

注意：此字段仅在支付成功且钱包为 AlipayCN 时返回。

Show child parameters

grossSettlementAmount Amount

此字段的值等于交易金额乘以 settlementQuote 的值。

注意：当币种兑换预先确定且汇率在交易时锁定时，会返回此字段。

Show child parameters

settlementQuote Quote

结算币种与交易币种之间的汇率。

注意：当 grossSettlementAmount 返回时，此字段会返回。

Show child parameters

paymentResultInfo PaymentResultInfo object

支付结果信息。

注意：当在 支付（收银台）接口中的 paymentMethodType 值为CARD, GRABPAY_MY, 或 GRABPAY_SG，且 paymentStatus 的值为SUCCESS或FAIL时返回此参数。

请选择场景

authExpirytime Datetime

授权支付的过期时间和日期。在此时间之后，您无法进行请款操作。

关于此字段的更多信息：

值遵循 ISO 8601 标准格式。例如，"2019-11-27T12:01:01+08:00"。

注意：当在 支付（收银台）接口中的 paymentMethodType 值为CARD时，此参数会被返回。

promotionResult Array <PromotionResult>

优惠方案结果。

注意：当买家在下单时使用了优惠方案活动时，会返回此参数。

Show child parameters

reversalType string

交易逆转类型。有效值为：

PAYMENT_REVERSAL: 表示 Antom 未及时收到支付成功通知导致交易超时关闭，触发退款但支付方式不支持或退款操作失败。

注意：当发生交易逆转时，会返回此参数。

paymentMethodType String

支付方式选项中包含的支付方式类型。参见支付方式以查看有效值。

注意：当选用 Antom Checkout Page 集成时，返回此字段。

更多信息：

最大长度：64 字符

API Explorer

示例代码沙箱运行

请求

URL

请求体

响应

Case

Payment successul

响应体

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详情请参阅以下列表：

如果 result.resultStatus 的值为 S， 支付结果查询 接口调用成功。您可以从接口响应的 paymentStatus 字段获取支付结果。
如果 result.resultStatus 的值为 F， 支付结果查询 接口调用失败。您无法从接口响应中获取支付结果。
如果 result.resultStatus 的值为 U， 支付结果查询 接口调用的状态未知。使用相同的请求参数重试 支付结果查询 接口。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	接口调用成功。通过 paymentStatus 获取订单状态。
ACCESS_DENIED	F	访问被拒绝。	详细原因请咨询 Antom 技术支持。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_NOT_EXIST	F	订单不存在。	检查 paymentId 是否正确。如果正确，请联系 Antom 技术支持了解具体原因。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PAYMENT_IN_PROCESS	U	支付正在处理中。	对于收银台支付，您发起的请求具有与已存在交易相同的 paymentRequestId，这可能是已完成或正在进行的交易。检查响应中是否返回了 redirectActionForm.redirectUrl。如果返回了，将用户重定向到 redirectUrl 指定的地址以完成支付。如果没有返回，支付可能已经完成。详情请参阅结果处理逻辑。对于代扣，支付正在处理中。等待异步通知或调用支付结果查询接口来查询最终的支付状态。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
SYSTEM_ERROR	F	发生系统错误。	获取 Antom 技术支持前请勿重试。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。

支付结果代码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	支付成功，无需进一步操作。
ACCESS_DENIED	F	访问被拒绝。	详细原因请咨询 Antom 技术支持。
CURRENCY_NOT_SUPPORT	F	币种不受支持。	详细原因请咨询 Antom 技术支持。
FRAUD_REJECT	F	由于风险控制，交易无法进一步处理。如果用户已为交易付款，交易将被退款。	当满足以下条件之一时，请联系 Antom 技术支持：您想要提出申诉。用户在两周内未收到退款。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
INVALID_CARD	F	银行卡无效。可能是银行卡号无法识别，银行卡没有对应的发卡行，或者卡号格式错误。	使用新卡发起支付，或联系发卡行。
INVALID_EXPIRY_DATE_FORMAT	F	expiryYear 或 expiryMonth 的格式不正确。	检查传递的参数 expiryYear 和 expiryMonth 的格式。
ISSUER_REJECTS_TRANSACTION	F	发卡行拒绝了交易。	使用新卡发起支付，或联系发卡行。
INVALID_ACCESS_TOKEN	F	访问令牌已过期、被撤销或不存在。	检查 accessToken 是否过期、被撤销或不存在。重新签署合同并重新发起授权签名流程。
INVALID_MERCHANT_STATUS	F	由于存在限制，商户状态异常。	详细原因请咨询 Antom 技术支持。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
MERCHANT_KYB_NOT_QUALIFIED	F	由于商户的 KYB 状态，支付失败。商户要么未完成 KYB，要么 KYB 状态不适用于此交易。	详细原因请咨询 Antom 技术支持。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
NO_PAY_OPTIONS	F	没有可用的支付选项。	请联系 Antom 技术支持以获取详细原因。
ORDER_IS_CLOSED	F	您发起的请求具有与已关闭交易相同的 paymentRequestId。	使用新的 paymentRequestId 重新发起支付。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PAYMENT_AMOUNT_EXCEED_LIMIT	F	支付金额超过了合同或支付方式允许的最大金额。	检查支付金额是否超过限制，或使用较低金额再试一次。请联系 Antom 技术支持了解具体限制。
PAYMENT_COUNT_EXCEED_LIMIT	F	支付次数超过了支付方式规定的限制。	请联系 Antom 技术支持了解具体限制。
PAYMENT_NOT_QUALIFIED	F	商户不具备支付资格，可能是因为未注册、未签订自动扣款协议或被禁止支付。	详细原因请咨询 Antom 技术支持。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
RISK_REJECT	F	由于风险控制，交易无法进一步处理。如果用户已为交易付款，交易将被退款。	如果用户在两周内未收到退款，请联系 Antom 技术支持。
SUSPECTED_CARD	F	银行卡涉嫌欺诈。例如，银行卡可能被盗或受限。	使用新卡发起支付，或联系发卡行。
SUSPECTED_RISK	F	由于疑似安全问题，交易无法进一步处理。您可以等待一个工作日后重试交易。如果交易不安全且用户已付款，交易将被退款。	当满足以下条件之一时，请联系 Antom 技术支持：重试后交易无法进一步处理。用户在两周内未收到退款。
SYSTEM_ERROR	F	发生系统错误。	获取 Antom 技术支持前请勿重试。
USER_AMOUNT_EXCEED_LIMIT	F	支付金额超过了用户的支付限额。	使用不超过账户可用余额的金额创建新支付，或联系 Antom 技术支持。
USER_BALANCE_NOT_ENOUGH	F	由于对应支付方式的用户余额不足，支付无法完成。	请充值账户或选择其他支付方式。
USER_KYC_NOT_QUALIFIED	F	由于用户的 KYC 状态，支付失败。用户要么未完成 KYC，要么 KYC 状态不满足此交易要求（例如，支付金额或产品信息的限制）。	请先完成 KYC 验证。
USER_PAYMENT_VERIFICATION_FAILED	F	用户在支付方式端被限制支付。	请联系 Antom 技术支持了解具体原因。
USER_STATUS_ABNORMAL	F	用户在支付方式端的状态异常。	请联系 Antom 技术支持了解具体原因。
PAYMENT_IN_PROCESS	U	支付正在处理中。	对于收银台支付，您发起的请求中的 paymentRequestId 与已存在的交易（可能是成功或进行中的交易）相同。请检查响应中是否返回了 redirectActionForm.redirectUrl。如果返回了，将用户重定向到`redirectUrl`指定的地址以完成支付。如果没有返回，支付可能已经完成。详细结果处理逻辑请参阅相关说明。对于代扣，支付正在处理中。等待异步通知或调用支付结果查询接口来查询最终的支付状态。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	对于收银台支付，使用新的 paymentRequestId 再次调用支付接口来解决此问题。如果问题未解决，请联系 Antom 技术支持。对于代扣，可以再次调用支付（收银台）接口或调用支付结果查询接口来查询最终支付状态。如果问题仍未解决，请联系 Antom 技术支持。
CARD_NOT_SUPPORTED	F	用于交易的银行卡不被支持。	请使用其他银行卡支付交易。
INVALID_EXPIRATION_DATE	F	paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值无效。	检查 paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值是否正确：如果不正确，请传入正确值。如果正确，请联系 Antom 技术支持获取详细原因。
INVALID_CARD_NUMBER	F	用于交易的银行卡号无效。	检查支付（收银台）接口字段里的 paymentMethod.paymentMethodMetaData.cardNo 的值是否正确：如果值不正确，请传入正确值并重试。如果值正确，该卡不支持此交易，请使用其他卡进行支付。
DO_NOT_HONOR	F	支付被发卡行拒绝。	请尝试使用其他银行卡支付，或联系发卡行。

交易结果代码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	接口调用成功。从 refundStatus 获取退款状态。
ACCESS_DENIED	F	访问被拒绝。	详细原因请咨询 Antom 技术支持。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
CLIENT_INVALID	F	客户端 ID 无效。Antom 对客户端 ID 有限制。	检查客户端 ID 是否正确，或联系 Antom 技术支持获取详细原因。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_NOT_EXIST	F	订单不存在。	请在 15 秒后再次调用接口。如果尝试三次后仍没有返回结果，说明订单未创建成功。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入、无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
SYSTEM_ERROR	F	发生系统错误。	获取 Antom 技术支持前请勿重试。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口来解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。
PAYMENT_IN_PROCESS	U	支付正在处理中。	对于收银台支付，您发起的请求中 paymentRequestId 与已存在的交易（可能是成功或进行中的交易）相同。请检查响应中是否返回了 redirectActionForm.redirectUrl。如果返回了，将用户重定向到 redirectUrl 指定的地址以完成支付。如果没有返回，支付可能已经完成。详情请参阅结果处理逻辑。对于代扣，支付正在处理中。等待异步通知或调用支付结果查询接口来查询最终的支付状态。
AUTHENTICATION_REQUIRED	F	需要进行 3D Secure 验证。	重新初始化支付并重定向用户进行 3D Secure 验证。
PAYMENT_PROHIBITED	F	因商品在该国禁止销售，无法处理支付。	您不允许对这笔交易提出异议。
INVALID_AMOUNT	F	发卡行因各种原因拒绝交易，例如指定金额无效或超过最大金额限制。	请联络 Antom 技术支持获取详细原因。