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值发起的支付请求,如果达到最终状态(SF),则对请求返回相同的结果。
  • 最大长度: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,支付状态未知。您可以等待支付结果的异步通知,并不断调用 支付结果查询 接口查询支付结果,直到获取最终的支付结果。如果无法收到异步通知,或者从 支付结果查询 响应中没有得到确定的结果 (SF),则通过调用 取消支付 接口 终止交易,以保持您与用户之间的交易状态一致。

结果码

结果码结果码信息行动建议
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验证码无效。

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