支付（反扫支付）

2025-04-08 03:15

POST /v1/payments/pay

使用此接口向Antom发起支付，并根据返回的状态和操作指示处理支付结果。

结构

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

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

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

入参

productCode String REQUIRED

根据商户与 Antom之间的合同，商户可以使用的支付产品。对于反扫支付，该值固定为IN_STORE_PAYMENT。

paymentRequestId String REQUIRED

商户为识别支付请求而分配的专属 ID。Antom 使用此字段进行幂等性控制。

更多信息：

此为幂等字段。商户使用 paymentRequestId 字段来实现幂等性控制。对于使用相同 paymentRequestId 值发起的支付请求，如果达到最终状态（S或F），则对同一请求应返回相同的结果。
最大长度：64 字符

order Order REQUIRED

订单信息，如买家信息、商户信息、订单描述和订单金额。

此参数也用于风险控制、监管、报告、用户支付结果展示等。

Show child parameters

paymentAmount Amount REQUIRED

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

Show child parameters

paymentMethod PaymentMethod REQUIRED

由商户或收单机构用来收取支付的支付方式。

Show child parameters

paymentExpiryTime Datetime

支付有效期是一个特定时间，超过这个时间后，支付将失效。支付有效期过后，收单机构或商户必须终止订单处理。默认的支付有效期由合同约定。如果你想使用不同于默认时间的支付有效期，可以在此字段中指定。

注意：通常对于反扫支付，合同中的默认支付有效期是支付请求发送后的 10 分钟。例如，如果请求在 2019-11-27T12:00:01+08:30 时发送，支付有效期则为 2019-11-27T12:10:01+08:30。

更多信息：

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

paymentNotifyUrl URL REQUIRED

用于接收支付结果通知的链接。

更多信息：

最大长度：2048 字符

paymentFactor PaymentFactor

指示支付场景。

Show child parameters

settlementStrategy SettlementStrategy

支付请求的结算策略。

注意：在满足以下任一条件时指定此字段：

已签署多个结算合约，且有多个结算合约支持此交易。在这种情况下，使用此字段指定结算货币，以便从所有已签署的结算合约中选择用于此交易的合约。
当 paymentMethodType 的值为 CONNECT_WALLET 时。

Show child parameters

merchantRegion String

商户或二级商户开展业务所在的国家或地区。遵循 ISO 3166 国家代码标准的二位字母国家/地区代码。目前仅支持US,JP,PK,SG。

注意：使用全球收单网关（GAGW）产品时，此字段是必需的。

更多信息：

最大长度：2 字符

出参

result Result REQUIRED

请求结果包含状态和错误代码等信息。

Show child parameters

paymentRequestId String

商家为标识支付请求分配的专属 ID。

更多信息：

最大长度：64 字符

paymentId String

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

更多信息：

最大长度：64 字符

paymentAmount Amount

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

Show child parameters

actualPaymentAmount Amount

实际支付金额，等于支付金额乘以支付汇率。

注意：当支付货币与支付服务提供商的实际支付货币匹配时，该字段的值等于支付金额。

Show child parameters

paymentQuote Quote

交易时支付货币与实际支付货币之间的汇率。

注意：当支付货币与支付服务提供商的实际支付货币相同时，该字段为空。

Show child parameters

paymentTime Datetime

支付成功或失败的最终状态发生的时间和日期。

更多信息：

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

pspCustomerInfo PspCustomerInfo

顾客的 Alipay+支付方式信息。

注意: Alipay+ 移动支付提供商，是参与Alipay+ 核心服务的移动支付合作伙伴，也是与蚂蚁集团成员合作、面向用户或发卡机构提供支付服务的其他支付服务提供商。

Show child parameters

challengeActionForm ChallengeActionForm

当支付结果未处于成功或失败的最终状态时，提供关于验证操作的信息。

Show child parameters

redirectActionForm RedirectActionForm

关于重定向操作的信息：

当用户重定向方法为GET (method=GET)时，redirectUrl 的值是一个可用于用户重定向的完整链接。
当用户重定向方法为POST (method=POST)时，redirectUrl 的值是用户应被重定向到的完整链接的一部分。其他构建完整链接所需的参数在参数字段中提供。

注意：此字段仅在接口调用成功时返回。

Show child parameters

grossSettlementAmount Amount

净结算金额，等于交易金额乘以 settlementQuote 的值。

注意：当结算货币与交易货币相同时，此字段为空。

Show child parameters

settlementQuote Quote

交易时结算货币与交易货币之间的汇率，仅在锁定汇率的情况下提供。

注意：当结算货币与交易货币相同时，此字段为空。

Show child parameters

API Explorer

请求

URL

请求体

响应

响应体

更多信息

本节提供了关于其他参数的额外信息。请参阅以下参数以了解详情：

productCode：
此参数的值是商家根据与 Antom 之间的合同用于收款的支付产品。当商家可以使用多个产品时，此参数是必需的。

order:
order 参数包含商户、商品、物流和购买环境等信息。在支付过程中，这些订单信息主要用于风险控制或反洗钱。支付完成后，这些信息用于展示消费记录、监管报告等目的。然而， Antom 不会验证 order 中的金额与支付请求中的金额是否一致，订单信息也不应用于资金操作。如果需要使用 Antom 提供的风险控制能力，请使用env字段
在这种情况下，order.merchant.referenceMechantId，order.merchant.merchantMCC，order.merchant.store.referenceStoreId 和 order.merchant.store.storeMcc 是必需的。建议指定 order.env.storeTerminalRequestTime 和 order.env.storeTerminalId。

Sample for the order field

paymentMethod:
paymentMethod 的值为 CONNECT_WALLET，表示 Antom 从用户的支付码（由 Antom 生成）中收款。

paymentMethodId:
用户支付工具的专属 ID。对于反扫支付，此字段是必需的，商户可以据此决定调用哪个支付服务来处理支付。更多信息请参阅支付码规范。

paymentExpiryTime:
支付执行方必须确保在过期时间后支付不会成功。如果请求中未指定此参数，则过期时间由支付执行方决定。

paymentFactor：
paymentFactor.inStorePaymentScenario 的值为 PaymentCode, 表示使用支付代码进行支付。

支付代码规范

一个 Antom 的支付代码是 16 到 24 位的数字，以 25 到 30 之间的数字开头。

对于反扫支付，使用以下规则来确定调用哪个支付服务：

如果使用了 Antom 的支付代码进行支付，商家需要将支付路由到 Antom。
如果使用了非 Antom 的支付代码进行支付，商家需要将支付路由到该非 Antom 支付代码对应的支付提供者。
如果一个与 Antom 集成的商户也与遵循 Antom 支付码规则的其他本地支付方式（如澳门钱包或 PayPay 钱包）进行了集成，当使用这些本地支付方式的支付码时，商户需要将支付路由到本地支付系统。或者使用 Antom 的支付码时，则需要将支付路由到 Antom。要判断支付码属于 Antom 还是本地支付方式，应遵循以下规则：

亚洲

支付代码规则			支付服务
长度	前两位数字	特殊规则	支付服务
24	25 - 30	第四、五、六位数字为8、0、1。	PayPay
16~24	25 - 30	无	Antom

支付代码规则			支付服务
长度	前两位数字	特殊规则	支付服务
16~24	25 - 30	第四、五、六位数字为0、0、3。	澳门钱包
16~24	25 - 30	无	Antom

支付代码规则			PaymentService
长度	前两位数字	特殊规则	PaymentService
16~24	25 - 30	无	Antom

支付代码规则			PaymentService
长度	前两位数字	特殊规则	PaymentService
16~24	25 - 30	无	Antom

结果处理逻辑

调用 支付 (反扫支付）接口后，可能会从 Antom 返回以下结果，或者商户未收到任何结果：

Antom 返回的 result.resultStatus 为S，表示交易成功，资金已成功扣款。
Antom 返回的 result.resultStatus 为F，商户需要根据 result.resultCode 中的错误信息采取进一步行动。
Antom 返回的 result.resultStatus 为U，商户需要使用 支付结果查询（线下商店）接口查询支付结果。查询请求可以发送 10 到 20 次，每次间隔 3 秒。
如果在发送支付请求后 5 秒内，没有从 Antom 收到异步通知和支付结果，商家需要使用 支付结果查询（线下商店）接口查询支付结果。查询请求可以发送 10 到 20 次，每次间隔 3 秒。
当调用 支付结果查询（线下商店） 接口，如果查询请求超过最大次数仍无法获取支付结果，商家需要调用 取消支付 接口取消交易。如果超出可取消时间段，商家无法使用 取消支付 接口取消交易，可以调用 退款（线下商店）接口进行退款。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	支付成功，无需进一步操作。
ACCESS_DENIED	F	访问被拒绝。	请联系 Antom 技术支持以获取详细原因。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
CLIENT_INVALID	F	客户端 ID 无效。Antom 对客户端 ID 有限制。	检查 clientId 是否正确，或联系 Antom 技术支持以获取详细原因。
CURRENCY_NOT_SUPPORT	F	货币不支持。	请联系 Antom 技术支持以获取详细原因。
EXPIRED_CODE	F	支付码已过期。	用户需要刷新支付码。
INVALID_CONTRACT	F	合同中的参数值与当前交易不符。	检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持解决问题。
INVALID_MERCHANT_STATUS	F	商户状态异常，存在限制。	请联系 Antom 技术支持以获取详细原因。
INVALID_PAYMENT_CODE	F	支付码无法被 Antom 接受。	选择其他支付方式。如果支持的支付方式，请联系 Antom 技术支持。
INVALID_SIGNATURE	F	签名验证失败。请求的私钥与 Antom 开发者中心的公钥不匹配。	检查用于签名请求的私钥是否与 Antom 开发者中心的公钥匹配。以下签名参考信息有用：请求头中的签名字段如何生成签名
KEY_NOT_FOUND	F	未找到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
MEDIA_TYPE_NOT_ACCEPTABLE	F	服务器不支持客户端可接受的媒体类型。	检查媒体类型是否正确，并使用 Antom 接受的媒体类型。
MERCHANT_KYB_NOT_QUALIFIED	F	由于商户的 KYB 状态，支付失败。商户要么未完成 KYB，要么 KYB 状态不符合此交易要求。	请联系 Antom 技术支持以获取详细原因。
MERCHANT_NOT_REGISTERED	F	商户未注册。	请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。
METHOD_NOT_SUPPORTED	F	服务器不支持请求的 HTTP 方法。仅支持 POST 方法。	确保 HTTP 方法为`POST`。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点信息。
NO_PAY_OPTIONS	F	交易不支持该货币。	请检查钱包是否支持该货币，或者检查钱包和货币是否与合约一致。如需详细原因，请联系 Antom 技术支持。
ORDER_IS_CANCELED	F	您发起的请求具有与之前已支付并被取消的交易相同的 paymentRequestId。	使用新的 paymentRequestId 重新发起支付。
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 技术支持前请勿重试。
REPEAT_REQ_INCONSISTENT	F	金额或货币与先前请求不同。	确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起支付。
RISK_REJECT	F	因风险控制，请求被拒绝。	提示用户因风险控制失败，请求被拒绝。
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_NOT_EXIST	F	用户在支付方式端不存在。	请联系 Antom 技术支持以获取详细原因。
USER_PAYMENT_VERIFICATION_FAILED	F	用户在支付方式端被限制支付。	用户验证失败，如 OTP 或 PIN 验证。请重新下单。
USER_STATUS_ABNORMAL	F	用户在支付方式端的状态异常。	请联系 Antom 技术支持以了解具体原因。
PAYMENT_IN_PROCESS	U	支付正在处理中。	等待异步通知，或调用支付结果查询（线下商店）接口查询订单的最终状态。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过了限制。	再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。