支付(收银台)
入参
merchantRegion String
商户经营业务所在的国家或地区。该参数遵循 ISO 3166 国家代码标准,是一个二位字母的国家或地区代码。
可能的值包括 US
, SG
, HK
, PK
, JP
, CN
, BR
, AU
, 和 MY
。
注意:在使用全球收单网关(GAGW)产品时,此参数是必需的。
更多信息:
- 最大长度:2 字符
merchantAccountId String
用于标识商户账户的专属 ID。
注意:当您在多处使用单个客户端 ID 时,请指定此参数。
更多信息:
- 最大长度:32 字符
userRegion String
基于 ISO 3166 国家代码标准的 2 位国家或地区代码。此参数用于根据用户所在地区来排序 Alipay + 支付方式。例如,如果您的支付方式列表中同时有 ALIPAY_CN
和 KAKAOPAY
,且用户来自韩国,那么 KAKAOPAY
将优先在 Alipay + 收银台页面上列出。
注意:此参数仅适用于已集成 Alipay + 收银台页面的商户。
更多信息:
- 最大长度:2 字符
env Env REQUIRED
有关下单环境的信息,例如设备信息。
order Order REQUIRED
包括买家、商户、商品、金额、配送信息和购买环境的订单信息。此字段用于以下目的:
- 在支付过程中,主要用于 Antom 的风险控制或反洗钱。
- 支付完成后,用于记录和报告,如采购追踪和监管报告。
paymentRequestId String REQUIRED
商户为标识支付请求所分配的专属 ID。Antom 使用此字段进行幂等性控制。
更多信息:
- 此为幂等字段。对于使用相同 paymentRequestId ,且最终状态为
S
或F
发起的支付请求,应返回相同的结果。 - 最大长度:64 字符
paymentAmount Amount REQUIRED
商家在订单币种中请求接收的支付金额。
settlementStrategy SettlementStrategy REQUIRED
支付请求的结算策略。
paymentMethod PaymentMethod REQUIRED
商户或收单机构用于收款的支付方式。
paymentFactor PaymentFactor
影响支付的因素。这个字段用于表明支付场景。
注意:当 paymentMethodType 的值为
CARD
时,请指定此参数。
creditPayPlan CreditPayPlan
此次支付的分期付款计划信息。
注意:如果要支持分期付款,请指定此字段,并请联系 Antom 技术支持获取关于如何提供分期付款的详细信息。
appId String
Antom 为标识小程序分配的专属 ID。
注意:当 terminalType 为
MINI_APP
时,此字段是必填的。
更多信息:
- 最大长度:32 字符
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”。
paymentNotifyUrl URL
用于接收支付结果通知的链接。
注意:如果您希望接收支付结果的异步通知,请指定此参数。您也可以在 Antom Dashboard 中设置接收结果通知的链接。如果请求和 Antom Dashboard 中都指定了链接,则请求中的值优先。
更多信息:
- 最大长度:2048 字符
paymentRedirectUrl URL REQUIRED
用户完成支付后跳转到的商户页面链接。
更多信息:
- 最大长度:2048 字符
productCode String REQUIRED
表示正在使用的支付产品,这是在合同中规定的。对于结账支付,值设置为 CASHIER_PAYMENT
。
出参
result Result REQUIRED
接口调用的结果。
paymentRequestId String
商户为识别支付请求分配的专属 ID。
注意:当 resultCode 为
PAYMENT_IN_PROCESS
时,此字段将返回。
更多信息:
- 最大长度:64 字符
paymentId String
Antom 为识别一次支付分配的专属 ID。
注意:当 resultCode 为
PAYMENT_IN_PROCESS
时,此字段将返回。
更多信息:
- 最大长度:64 字符
paymentAmount Amount
商户请求以订单币种收取的支付金额。
注意:当 resultCode 为
PAYMENT_IN_PROCESS
时,此字段返回。
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
Alipay+ 支付方式的客户信息。
注意:当 Alipay+ 支付方式能够提供相关信息时,此字段将返回。
orderCodeForm OrderCodeForm
订单代码的相关信息。
注意:当支付方式支持提供相关信息时,此参数会被返回。
grossSettlementAmount Amount
此字段的值等于交易金额乘以 settlementQuote 的值。
注意:当币种兑换预先确定且交易时汇率被锁定时,返回此字段。
settlementQuote Quote
结算币种与交易币种之间的汇率。
注意:当返回 grossSettlementAmount 时,此字段会被返回。
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
时,可能会返回此参数。
promotionResult Array <PromotionResult>
优惠方案结果。
注意:当买家在下单过程中使用了优惠方案时,此参数会被生成。
请求
响应
更多信息
关于 order 字段:Antom 不会验证 order 字段中的金额与支付请求中的金额是否一致。订单信息也不应用于资金操作。此字段主要用于风险控制、监管、监管报告和消费记录显示。如果需要 Antom 提供的风险控制能力,可以使用 env 字段。
结果处理逻辑
对于不同的请求结果,需要采取不同的行动。详细信息如下:
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 | 找不到匹配的结算合同。 | 检查以下解决方案:
|
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 的值是否正确:
|