Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

支付（代扣）

POST /v1/payments/pay

在用户同意授权后，使用此接口发起代扣支付，并根据 Antom 返回的状态和操作指示处理支付结果。

结构

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


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

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

入参

order Order  REQUIRED

包括买家、商家、商品、金额、配送信息和购买环境的订单信息。此字段用于以下目的：

  • 在支付过程中，此字段主要用于 Antom 的风险控制或反洗钱。
  • 支付完成后，此字段用于记录和报告，如采购追踪和监管报告。
Show child parameters

paymentRequestId String  REQUIRED

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

更多信息：

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

paymentAmount Amount  REQUIRED

交易货币，遵循 ISO 4217 标准的3位字母的货币代码。

Show child parameters

settlementStrategy SettlementStrategy  

支付请求的结算策略。

Show child parameters

paymentMethod PaymentMethod  REQUIRED

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

Show child parameters

creditPayPlan CreditPayPlan  

此支付的分期付款计划信息。

注意：如果要支持分期付款，请指定此字段，并请联系 Antom 技术支持获取关于如何提供分期付款的详细信息。

Show child parameters

appId String  

Antom 为识别小程序应用分配的专属 ID。

注意：当 terminalType 为MINI_APP时指定此字段。

更多信息：

  • 最大长度：32 字符

paymentExpiryTime Datetime  

支付有效期是一个特定时间，超过这个时间后，支付将失效，收单机构或商户必须终止订单处理。默认的支付有效期由合同确定。

注意事项：

  • 如果要使用不同于默认时间的支付有效期，请指定此字段。指定的支付有效期必须在支付请求发送后的一分钟内，并且必须遵循正确的格式。
  • 通常对于自动扣款，合同中的默认支付有效期是在支付请求发送后的一分钟。例如，如果请求在 2019-11-27T12:00:01+08:30 时发送，支付有效期为 2019-11-27T12:01:01+08:30。

更多信息：

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

paymentNotifyUrl URL  

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

注意：如果希望接收自动扣款结果的异步通知，请设置此字段。您也可以在 Antom Dashboard 中设置接收支付结果通知的链接。如果请求和 Antom Dashboard 中都指定了支付通知链接，则请求中指定的值优先。

更多信息：

  • 最大长度：2048 字符

productCode String  REQUIRED

表示合同中规定的正在使用的支付产品。 对于自动扣款，值设置为 AGREEMENT_PAYMENT。 

出参

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+ 支付方式能够提供相关信息时，此字段返回。

Show child parameters

grossSettlementAmount Amount  

此字段的值等于交易金额乘以 settlementQuote 的值。当货币兑换预先确定且汇率在交易时锁定时，会返回此字段。 

Show child parameters

settlementQuote Quote  

结算货币与交易货币之间的汇率。当 grossSettlementAmount 返回时，此字段会返回。 

Show child parameters
API Explorer
示例代码沙箱运行

请求

URL

请求体

响应

响应体

更多信息 

本节提供有关其他参数的额外信息。详细信息如下：

  • order: Antom 不会验证 order 字段中的金额与支付请求中的金额的一致性。订单信息也不应用于资金操作。此字段主要用于风险控制、监管、监管报告和消费记录显示。如果需要 Antom 提供的风险控制能力，请使用 env 字段。
order 字段示例
  • paymentTime: Antom 成功执行此支付的时间，即支付达到最终成功状态的日期和时间。此值用作后续可取消和可退款时间的开始时间。例如，如果退款期为 6 个月，接受退款的最终截止时间为 paymentTime 加上 6 个月。

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详细信息如下：

  • 如果 result.resultStatus 的值为 S，支付成功。
  • 如果 result.resultStatus 的值为 F，支付失败。
  • 如果 result.resultStatus 的值为 U，支付状态未知。您可以等待支付结果的异步通知，并不断调用 支付结果查询 接口查询支付结果，直到获取最终的支付结果。如果无法收到异步通知，或者从 支付结果查询 响应中没有得到确定的结果 (S 或 F)，则通过调用 取消支付 接口 终止交易，以保持您与用户之间的交易状态一致。

结果码

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

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

ACCESS_DENIEDF访问被拒绝。

详细原因请咨询 Antom 技术支持。

CURRENCY_NOT_SUPPORTF货币不受支持。

详细原因请咨询 Antom 技术支持。

EXPIRED_CODEF支付码已过期。

用户需要刷新支付码。  

INVALID_ACCESS_TOKENF访问令牌已过期、被撤销或不存在。

检查访问令牌是否已过期、被撤销或不存在。重新签署协议并重新初始化授权签名流程。

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

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

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

详细原因请咨询 Antom 技术支持。

INVALID_PAYMENT_CODEFAntom 无法接受此支付代码。

选择其他支付方式。如果支持该支付方式，请联系 Antom 技术支持。 

INVALID_PAYMENT_METHOD_META_DATAF支付方式元数据无效。

检查支付方式的元数据是否正确。如果正确，请联系 Antom 技术支持。   

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

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

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

详细原因请咨询 Antom 技术支持。

MERCHANT_NOT_REGISTEREDF商户未注册。

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

NO_INTERFACE_DEFF接口未定义。

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

NO_PAY_OPTIONSF没有可用的支付选项。

如需详细原因，请联系 Antom 技术支持。 

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

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

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

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

ORDER_NOT_EXISTF订单不存在。

检查 paymentId 是否正确。 

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因风险控制，请求被拒绝。

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

SETTLE_CONTRACT_NOT_MATCHF找不到匹配的结算合同。

检查以下解决方案：

  • 从商户注册的多种货币中指定一种结算货币。
  • 检查结算货币是否在结算合同中指定。
  • 商户未签署结算合同。请联系 Antom 技术支持。 
SYSTEM_ERRORF发生系统错误。

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

USER_AMOUNT_EXCEED_LIMITF支付金额超过了用户的支付限额。

使用不超过账户可用余额的金额创建新支付，或联系 Antom 技术支持。 

USER_BALANCE_NOT_ENOUGHF由于对应支付方式的用户余额不足，支付无法完成。

请充值账户或选择其他支付方式。

USER_KYC_NOT_QUALIFIEDF由于用户的 KYC 状态，支付失败。用户要么未完成 KYC，要么 KYC 状态不满足此交易要求（例如，支付金额或产品信息的限制）。

请先完成 KYC 验证。

USER_NOT_EXISTF用户在支付方式端不存在。

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

USER_PAYMENT_VERIFICATION_FAILEDF用户在 OTP、PIN 等验证方式中未能通过支付验证。

请联系 Antom 技术支持了解具体原因。  

USER_STATUS_ABNORMALF用户在支付方式端的状态异常。

请联系 Antom 技术支持了解具体原因。

PAYMENT_IN_PROCESSU支付正在处理中。

等待异步通知或调用查询支付接口查询最终支付状态。 

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过限制。

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

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

调用查询支付接口查询最终支付状态。如果问题未解决，请联系 Antom 技术支持。

VERIFY_TIMES_EXCEED_LIMITF当前验证码在支付验证中失败次数过多。

用户必须获取新的验证码。  

VERIFY_UNMATCHEDF验证码无效。

用户必须获取新的验证码。