支付

2024-09-02 06:31

POST /v1/payments/pay

使用此接口获取收银台页面地址。获取收银台页面地址后，您可以将用户重定向到收银台页面进行支付。

结构

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

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

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

入参

productCode String REQUIRED

表示正在使用的支付产品，这是在合同中规定的。对于结账支付，值设置为 CASHIER_PAYMENT。

paymentRequestId String REQUIRED

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

更多信息：

此为幂等字段。对于使用相同 paymentRequestId ，且最终状态为S或F发起的支付请求，应返回相同的结果。
最大长度：64 字符

order Order object REQUIRED

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

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

Show child parameters

paymentAmount Amount object REQUIRED

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

Show child parameters

paymentFactor PaymentFactor object

影响支付的因素。这个字段用于表明支付场景。

注意：当paymentMethodType的值为CARD时，需要指定此参数。

Show child parameters

paymentMethod PaymentMethod object REQUIRED

商户或收单机构用于收款的支付方式。

Show child parameters

paymentExpiryTime Datetime

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

注意:
对于银行转账支付，默认支付有效期是支付请求发送后的 48 小时。对于其他支付类别，通常默认支付有效期是支付请求发送后的 14 分钟。例如，如果请求在 2019-11-27T12:00:01+08:30 发送，支付有效期为 2019-11-27T12:14:01+08:30。
如果你想使用不同于默认时间的支付有效期，可以指定此字段。对于银行转账支付，指定的支付有效期必须在支付请求发送后的 48 小时内。对于其他支付类别，指定的支付有效期必须在支付请求发送后的 10 分钟内。

更多信息：

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

paymentRedirectUrl URL REQUIRED

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

更多信息：

最大长度：2048 字符

paymentNotifyUrl URL

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

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

更多信息：

最大长度：2048 字符

settlementStrategy SettlementStrategy object REQUIRED

支付请求的结算策略。

Show child parameters

userRegion String

基于 ISO 3166 国家代码标准的二位国家或地区代码。此参数用于根据用户所在地区对 Antom 支付方式排序。例如，如果您的支付方式列表中同时有ALIPAY_CN和KAKAOPAY，且用户来自韩国，那么在 Antom 收银台页面上，KAKAOPAY将被优先列出。

注意：此参数仅适用于已集成 Antom 收银台页面的商户。

更多信息：

最大长度：2 字符

creditPayPlan CreditPayPlan object

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

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

Show child parameters

appId String

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

注意：当 terminalType 为 MINI_APP时，此字段是必需的。

更多信息：

最大长度：32 字符

merchantRegion String

商户经营业务所在的国家或地区。该参数遵循 ISO 3166 国家代码标准，是一个二位字母的国家或地区代码。

可能的值包括 US, SG, HK, PK, JP, CN, BR, AU, 和 MY。

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

更多信息：

最大长度：2 字符

env Env object REQUIRED

下单的环境信息，例如设备信息。

Show child parameters

出参

result Result object REQUIRED

接口调用的结果。

Show child parameters

paymentRequestId String

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

注意：当 resultCode 为PAYMENT_IN_PROCESS时，此字段将返回。

更多信息：

最大长度：64 字符

paymentId String

Antom 为识别一次支付分配的专属 ID。

注意：当 resultCode 为PAYMENT_IN_PROCESS时，此字段将返回。

更多信息：

最大长度：64 字符

paymentAmount Amount object

商户请求以订单币种收取的支付金额。

注意：当 resultCode 为 PAYMENT_IN_PROCESS时，此字段返回。

Show child parameters

paymentData String

用于Antom client SDK中，渲染收银台页面。如果您应用集成了Antom client SDK，将返回此参数。收到此参数后，您可以调用Antom client SDK的 showPaymentSheet 接口。

更多信息：

最大长度：20000 字符

paymentCreateTime Datetime

创建支付的日期和时间。

注意：当 resultCode 为 PAYMENT_IN_PROCESS时，此字段将返回。

更多信息：

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

pspCustomerInfo PspCustomerInfo object

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

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

Show child parameters

orderCodeForm OrderCodeForm object

订单代码的相关信息。

注意：当支付方式支持提供相关信息时，此参数会被返回。

Show child parameters

grossSettlementAmount Amount object

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

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

Show child parameters

settlementQuote Quote object

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

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

Show child parameters

appIdentifier String

Android 应用用于打开收银台页面的包名。

注意：当 resultCode 为 PAYMENT_IN_PROCESS且 terminalType 为APP或 WAP时，此字段将返回。

更多信息：

最大长度：128 字符

applinkUrl URL

应用安装成功时，跳转应用的链接，安装失败则跳转至 WAP 页面。对于 Android，该链接是 Native App Link。对于 iOS，该链接是 Universal Link。

注意：当 resultCode 的值为 PAYMENT_IN_PROCESS时，必须返回 schemeUrl, applinkUrl, 或 normalUrl 中的至少一个。

更多信息：

最大长度：2048 字符

normalUrl URL

将用户重定向到默认浏览器或嵌入式 WebView 中的 WAP 或 WEB 页面的链接。

注意：当 resultCode 的值为 PAYMENT_IN_PROCESS 时，需要返回 schemeUrl、 applinkUrl、或 normalUrl 中的至少一个。

更多信息：

最大长度：2048 字符

schemeUrl URL

在 Android 或 iOS 系统中，应用安装完成后，将用户重定向到应用的 URL scheme。

注意：当 resultCode 的值为 PAYMENT_IN_PROCESS时，至少需要返回 schemeUrl、 applinkUrl、或 normalUrl之一。

更多信息：

最大长度：2048 字符

paymentResultInfo PaymentResultInfo

支付结果信息。

注意：当 paymentMethodType 的值为CARD时，可能会返回此参数。

Select scenario

API Explorer

示例代码沙箱运行

请求

URL

Payment method

AlipayCN

Terminal type

APP

Integration role

Acquirer-merchant Direct-merchant

请求体

响应

Case

Successful/In-process transaction exists

Case description

If a transaction with paymentStatus of PROCESSING or SUCCESS exists, and you initiate a request with the same paymentRequestId as that of the existing transaction, the response will be the same as the response of the existing transaction. The following response is returned:

响应体

结果处理逻辑

对于不同的请求结果，需要采取不同的行动。详细信息如下：

S: 当返回此值时，接口调用成功。
F: 当返回此值时，接口调用失败。根据相应的结果消息采取行动，或使用新的 paymentRequestId 值再次调用接口。如果问题持续存在，请联系 Antom 技术支持。
U: 当返回此值时，检查结果代码：

结果代码不是PAYMENT_IN_PROCESS: 接口调用失败。使用新的 paymentRequestId 值再次调用此接口。
结果代码是PAYMENT_IN_PROCESS: 检查是否返回了一个或多个（appLinkUrl, normalUrl, schemeUrl）链接：

返回了一个或多个链接: 交易创建成功。将用户重定向到链接指定的地址以完成支付。
没有返回链接: 交易创建失败。使用新的 paymentRequestId 值再次调用支付接口。如果问题持续存在，请联系 Antom 技术支持。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	支付成功，无需进一步操作。
ACCESS_DENIED	F	访问被拒绝。	请联络 Antom 技术支持获取详细原因。
AUTHENTICATION_REQUIRED	F	需要进行 3D Secure 验证。	重新初始化支付并引导用户进行 3D Secure 验证。
CURRENCY_NOT_SUPPORT	F	币种不受支持。	请联系 Antom 技术支持以获取详细原因。
DO_NOT_HONOR	F	支付被发卡行拒绝。	请尝试使用其他银行卡支付，或联系发卡行。
EXPIRED_CODE	F	支付码已过期。	用户需要刷新支付二维码。
FRAUD_REJECT	F	由于风险控制，交易无法进一步处理。如果用户已为交易付款，交易将被退款。	当满足以下条件之一时，请联系 Antom 技术支持：您想要提出申诉。用户在两周内未收到退款。
IDENTITY_AGE_NOT_ENOUGH	F	用户年龄未达到要求。	请确认您的身份信息并重试。
IDENTITY_VERIFY_FAILED	F	身份验证超时或无法获取结果。	请确认您的身份信息并重试。
INVALID_ACCESS_TOKEN	F	访问令牌已过期、被撤销或不存在。	检查 accessToken 是否正确。如果不正确，请传入正确值。如果正确，请联系 Antom 技术支持获取详细原因。
INVALID_AMOUNT	F	发卡行因各种原因拒绝交易，例如指定金额无效或超过最大金额限制。	请联络 Antom 技术支持获取详细原因。
INVALID_CPF	F	无效的 CPF。	请确认您的身份信息并重试。
INVALID_CONTRACT	F	合同中的参数值与当前交易不符。	检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持协助解决问题。
INVALID_IDENTITY_STATUS	F	身份状态异常。	请确认您的身份信息并重试。
INVALID_MERCHANT_STATUS	F	由于存在限制，商户状态异常。	请联络 Antom 技术支持获取详细原因。
INVALID_PAYMENT_CODE	F	Antom 无法接受此支付代码。	选择其他支付方式。如果支付方式支持，请联系 Antom 技术支持。
INVALID_PAYMENT_METHOD_META_DATA	F	支付方式元数据无效。	检查支付方式的元数据是否正确。如果正确，请联系 Antom 技术支持。
KEY_NOT_FOUND	F	找不到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
MERCHANT_KYB_NOT_QUALIFIED	F	由于商户的 KYB 状态，支付失败。商户要么未完成 KYB，要么 KYB 状态不适用于此交易。	请联络 Antom 技术支持获取详细原因。
MERCHANT_NOT_REGISTERED	F	商户未注册。	请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。
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 技术支持了解具体限制。
CARD_NOT_SUPPORTED	F	用于交易的银行卡不被支持。	使用另一张卡进行交易支付。
PAYMENT_NOT_QUALIFIED	F	商户不具备支付资格，可能是因为未注册、未签订自动扣款协议或被禁止支付。	请联系 Antom 技术支持以获取详细原因。
PROCESS_FAIL	F	发生了常见的业务失败。	获取 Antom 技术支持前请勿重试。
REPEAT_REQ_INCONSISTENT	F	金额或货币与先前请求不同。	确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起支付。
RISK_REJECT	F	由于风险控制，交易无法进一步处理。如果用户已为交易付款，交易将被退款。	如果用户在两周内未收到退款，请联系 Antom 技术支持。
SETTLE_CONTRACT_NOT_MATCH	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_NOT_EXIST	F	用户在支付方式端不存在。	请联系 Antom 技术支持获取详细原因。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。
INVALID_CARD_NUMBER	F	用于交易的银行卡号无效。	检查 paymentMethod.paymentMethodMetaData.cardno 的值是否正确：如果不正确，请传入正确值并重试。如果正确，该卡不支持此交易，请使用其他银行卡支付交易。
PAYMENT_IN_PROCESS	U	支付正在处理中。	获取任意一个链接（appLinkUrl, normalUrl, schemeUrl）并打开收银页面。如果没有返回链接，使用新的 paymentRequestId 值再次调用支付接口。如果问题仍然存在，请联系 Antom 技术支持。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过限制。	再次调用接口以解决问题。如果问题未解决，请联系 Antom 技术支持。
ORDER_NOT_EXIST	F	订单不存在。	检查 paymentId 是否正确。
ORDER_STATUS_INVALID	F	交易无法进一步处理，因为订单状态无效。	检查交易的订单状态，或联系 Antom 技术支持获取详细原因。
USER_PAYMENT_VERIFICATION_FAILED	F	用户在 OTP、PIN 等验证方式中未能通过支付验证。	请联系 Antom 技术支持了解具体原因。
USER_STATUS_ABNORMAL	F	用户在支付方式端的状态异常。	请联系 Antom 技术支持了解具体原因。
VERIFY_TIMES_EXCEED_LIMIT	F	当前验证码在支付验证中失败次数过多。	用户必须获取新的验证码。
VERIFY_UNMATCHED	F	验证码无效。	用户必须获取新的验证码。
SELECTED_CARD_BRAND_NOT_AVAILABLE	F	用户选择的支付银行卡品牌不可用。	用户选择的支付银行卡品牌不可用。
PAYMENT_PROHIBITED	F	因商品在该国禁止销售，无法处理支付。	您不允许对这笔交易提出异议。
INVALID_EXPIRATION_DATE	F	paymentMethod.paymentMethodMetaData.expiryYear 或paymentMethod.paymentMethodMetaData.expiryDate的值无效。	检查 paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值是否正确：如果不正确，请传入正确的值。如果正确，请联系 Antom 技术支持以获取详细原因。