Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

支付（入口码支付）

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  

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

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

更多信息：

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

paymentRedirectUrl URL  

支付完成后用户被重定向到的链接。

更多信息：

  • 最大长度：2048 字符

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。

注意：当使用 Antom 全球网关（GGW）产品时，此字段是必需的。

更多信息：

  • 最大长度：2 字符

出参

result Result  REQUIRED

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

Show child parameters

paymentRequestId String  

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

更多信息：

  • 最大长度：64 字符

paymentId String  

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

更多信息：

  • 最大长度：64 字符

paymentAmount Amount  

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

Show child parameters

paymentTime Datetime  

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

更多信息：

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

paymentCreateTime 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  

提供有关重定向操作的信息。

Show child parameters

grossSettlementAmount Amount  

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

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

Show child parameters

settlementQuote Quote  

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

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

Show child parameters
API Explorer

请求

URL

请求体

响应

响应体

更多信息 

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

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

order:
参数order包含订单信息，如商户、商品、物流和购买环境。在支付过程中，这些信息主要用于 Antom 的风险控制或反洗钱检查。支付完成后，这些信息用于展示消费记录、监管报告等用途。
然而，Antom 不会校验 oreder 中的金额与支付请求中的金额是否一致，订单信息也不用于资金操作。如果需要 Antom 提供的风险控制功能，可以使用 env 字段。

订单字段示例

paymentMethod:
参数 paymentMethod 的值为 CONNECT_WALLET，表示 Antom 将通过 Antom 生成的二维码收取款项。

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

paymentFactor:
参数 paymentFactor.inStorePaymentScenario 的值为 EntryCode，表明 Antom 需要在此支付中生成一个跳转链接。

paymentId:
如果响应中未返回此字段，您可以使用 paymentRequestId 字段发起 支付结果查询（线下商店）和 取消支付 请求。

结果处理逻辑

调用 支付（入口码支付）接口后，可能会从 Antom 返回以下结果：

  • Antom 返回的结果中，result.resultStatus 为 S，表示商家需要根据表单中的参数进行跳转，从而继续支付流程。
  • Antom 返回的结果中，result.resultStatus 为 F，说明支付请求失败。
  • Antom 返回的结果中，result.resultStatus 为 U，商家需要再次调用 支付（入口码支付）接口。

结果码

结果码值结果码信息行动建议
SUCCESSS成功

支付成功，无需进一步操作。  

ACCESS_DENIEDF访问被拒绝。

请联系 Antom 技术支持以获取详细原因。 

INVALID_APIF调用的接口无效或未激活。

请联系 Antom 技术支持解决此问题。  

CLIENT_INVALIDF客户端 ID 无效。Antom 对客户端 ID 有限制。

请检查客户端 ID 是否正确，或联系 Antom 技术支持以获取详细原因。

 

CURRENCY_NOT_SUPPORT F货币不支持。

请联系 Antom 技术支持以获取详细原因。 

INVALID_CONTRACTF合同中的参数值与当前交易不符。

检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持解决问题。 

INVALID_MERCHANT_STATUSF商户状态异常，存在限制。

请联系 Antom 技术支持以获取详细原因。 

INVALID_SIGNATUREF签名验证失败。请求的私钥与 Antom 开发者中心的公钥不匹配。

检查用于签名请求的私钥是否与 Antom 开发者中心的公钥匹配。以下签名参考信息有用：

KEY_NOT_FOUNDF未找到 Antom 或商户的私钥或公钥。

检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。

MEDIA_TYPE_NOT_ACCEPTABLEF服务器不支持客户端可接受的媒体类型。

检查媒体类型是否正确，并使用 Antom 接受的媒体类型。

MERCHANT_KYB_NOT_QUALIFIEDF由于商户的 KYB 状态，支付失败。商户要么未完成 KYB，要么 KYB 状态不符合此交易要求。

请联系 Antom 技术支持以获取详细原因。 

MERCHANT_NOT_REGISTEREDF商户未注册。

请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。

METHOD_NOT_SUPPORTEDF服务器不支持请求的 HTTP 方法。仅支持 POST 方法。

确保 HTTP 方法为​POST​。

NO_INTERFACE_DEFF接口未定义。

检查链接是否正确。请参考接口文档中的端点信息。

NO_PAY_OPTIONSF交易不支持该货币。

请检查支付方式是否支持该货币，或者检查支付方式和货币是否与合约一致。如需详细原因，请联系 Antom 技术支持。

ORDER_IS_CANCELEDF您发起的请求具有与之前已支付并被取消的交易相同的 paymentRequestId。

使用新的 paymentRequestId 重新发起支付。

ORDER_IS_CLOSEDF您发起的请求具有与已存在并关闭的交易相同的 paymentRequestId。

使用新的 paymentRequestId 重新发起支付。

PARAM_ILLEGALF缺少必需参数，或存在非法参数。例如，非数字输入、无效日期，或参数的长度和类型错误。

检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。

PAYMENT_AMOUNT_EXCEED_LIMITF支付金额超过了合同或支付方式允许的最大金额。

检查支付金额是否超过限制，或者使用较低金额再试一次。请联系 Antom 技术支持了解具体限制。

PAYMENT_COUNT_EXCEED_LIMITF支付次数超过了支付方式指定的限制。

请联系 Antom 技术支持了解具体限制。

PAYMENT_NOT_QUALIFIEDF商户未获得支付资格，可能是因为未注册、未签订代扣协议，或被禁止支付。

请联系 Antom 技术支持以获取详细原因。 

PROCESS_FAILF发生了常见的业务失败。

获取 Antom 技术支持前请勿重试。

REPEAT_REQ_INCONSISTENTF金额或货币与先前请求不同。

确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起支付。

RISK_REJECTF因风险控制，请求被拒绝。

提示用户因风险控制失败，请求被拒绝。

SYSTEM_ERRORF发生系统错误。

获取 Antom 技术支持前请勿重试。

USER_NOT_EXISTF用户在钱包端不存在。

请联系 Antom 技术支持以获取详细原因。 

PAYMENT_IN_PROCESSU支付正在处理中。

使用新的 paymentRequestId 重新发起支付。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。

再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。

UNKNOWN_EXCEPTIONU由于未知原因，接口调用失败。

再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。