notifyPayment
入参
notifyType String REQUIRED
支付状态通知的类型。有效值包括:
PAYMENT_RESULT: 表示通知是关于支付结果的。PAYMENT_PENDING: 表示用户已完成支付。商家需要等待最终的支付结果。UPDATE_AMOUNT_RESULT:表示商户调用 updateAmount 接口后的异步通知。
result Result REQUIRED
支付结果的详细信息,如支付状态、结果代码和结果消息。
paymentRequestId String REQUIRED
商户为识别支付请求而分配的专属 ID。
更多信息:
- 最大长度:64 字符
paymentId String REQUIRED
Antom 为识别支付而分配的支付 ID。paymentId 与 paymentRequestId 之间存在一对一对应关系。
更多信息:
- 最大长度:64 字符
paymentAmount Amount REQUIRED
商家请求在订单币种中接收的支付金额。
paymentCreateTime Datetime REQUIRED
支付创建的日期和时间。
更多信息:
- 值遵循 ISO 8601 标准格式。例如,“2019-11-27T12:01:01+08:00”。
paymentTime Datetime
支付成功达到最终状态的日期和时间。
注意:此字段仅在支付达到最终成功状态(result.resultStatus 的值为
S)时返回。
更多信息:
- 值遵循 ISO 8601 标准格式。例如,“2019-11-27T12:01:01+08:00”。
pspCustomerInfo PspCustomerInfo
关于电子钱包的客户信息。
注意:当电子钱包能够提供相关信息时,此字段将返回。
customsDeclarationAmount Amount
用于海关报关的总额。
注意:此字段仅在支付成功且钱包为 AlipayCN 时返回。
grossSettlementAmount Amount
此字段的值等于交易金额乘以 settlementQuote 的值。
注意:当汇率在交易时被锁定时返回此参数。
settlementQuote Quote
结算币种与交易币种之间的汇率。
注意:当 grossSettlementAmount 返回时,此字段会被返回。
acquirerReferenceNo String
非 Antom 收单机构为交易分配的专属 ID。
更多信息:
- 最大长度:64 字符
paymentResultInfo PaymentResultInfo object
支付结果信息。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
Card
cardNo String
部分隐藏的卡号,仅显示卡号的一部分,可用于向用户展示。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:32 字符
cardBrand String
用于向用户展示的银行卡品牌。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:256 字符
cardToken String
银行卡的令牌,此参数的值在后续支付中用于 paymentMethodId 在 pay(单笔支付)接口中。
注意:当 paymentMethodType 在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD并且商户没有 PCI 合规时,此参数返回。
更多信息:
- 最大长度:128 字符
issuingCountry String
银行卡的发行国家。此参数的值是一个遵循 ISO 3166 国家代码标准的二位字母国家代码。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:2 字符
funding String
银行卡的资金类型。有效值为:
CREDIT:表示信用卡。DEBIT:表示借记卡。PREPAID: 表示预付卡。CHARGE: 表示充值卡。DEFERRED_DEBIT: 表示延期借记卡。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:32 字符
paymentMethodRegion String
代表支付方法所在国家或地区的地区代码。此参数的值是一个二位字母的 ISO 国家代码或 GLOBAL。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:6 字符
threeDSResult ThreeDSResult
3D Secure 认证的结果。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD且卡认证类型为 3D Secure 时返回此参数。
avsResultRaw String
原始的 AVS 结果。请参阅 AVS 结果代码 以检查有效值。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD且使用 3D Secure 或非 3D Secure 认证时,返回此参数。
更多信息:
- 最大长度:128 字符
cvvResultRaw String
原始的卡验证值 (CVV),卡安全码 (CSC),或卡验证码 (CVC)结果。请参阅 CVV 结果代码以检查有效值。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD并且使用了 3D Secure 或非 3D Secure 身份验证时,此参数返回。
更多信息:
- 最大长度:128 字符
networkTransactionId String
银行卡组织为识别交易而分配的交易 ID。 此参数的值在后续支付中用于 pay(单笔支付)接口请求的相同参数。
注意:当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD,并且使用 3D Secure 或非 3D Secure 认证时,返回此参数。
更多信息:
- 最大长度:128 字符
cardCategory string
支付卡类别。有效值为:
CONSUMER: 个人卡COMMERCIAL: 商务卡
当以下所有条件满足时,返回此参数:
- paymentMethodType 的值为
CARD。- cardNo 的值有效。
- 信息在 Antom 卡数据库中可用。
更多信息:
- 最大长度:32 字符
creditPayPlan creditPayPlan
分期付款的分期计划信息。
注意:当用户成功用卡进行分期付款时,返回此参数。
cardholderName String
持卡人姓名。
注意:针对指定地区的特定商户,当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:64 字符
cardBin String
银行卡号码的前六位数字,用于识别银行卡的发行银行和卡片类型。
注意:针对指定地区的特定商户,当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:8 字符
lastFour String
银行卡卡号后 4 位。
注意:针对指定地区的特定商户,当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:4 字符
expiryMonth String
银行卡的过期月份。传入表示月份的两位数字。例如,如果过期月份是二月,此参数的值为 02。
注意:针对指定地区的特定商户,当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:2 字符
expiryYear String
银行卡的到期年份。输入年份的最后两位数字。例如,如果到期年份是 2025,此参数的值为 25。
注意:针对指定地区的特定商户,当在 pay(单笔支付)接口或 createPaymentSession(单笔支付)接口中的 paymentMethodType 值为
CARD时,返回此参数。
更多信息:
- 最大长度:2 字符
refusalCodeRaw String
发卡行拒绝交易的响应代码。有效值请参阅 ISO codes。
当满足以下条件时返回此参数:
- 交易失败。
- 参数 paymentMethodType 的值为
CARD。- 发卡行有返回此数据。
更多信息:
- 最大长度:16 字符
refusalReasonRaw String
拒绝交易响应代码的错误信息。
当满足以下条件时返回此参数:
- 交易失败。
- 参数 paymentMethodType 的值为
CARD。- 发卡行有返回此数据。
更多信息:
- 最大长度:256 字符
merchantAdviceCode String
商户建议码(MAC)包含万事达卡交易详情及拒付原因说明。如遇支付失败,此代码会提示是否允许以及何时可发起重试。有效值请参阅 Merchant Advice Code。
注意:当参数 paymentMethodType 的值为
CARD且发卡行有返回此数据时,此字段返回。
更多信息:
- 最大长度:128 字符
credentialTypeUsed String
表示交易使用的是主账号(PAN)还是卡组令牌。有效值为:
PAN:表示交易使用了 PAN。NETWORK_TOKEN:表示交易使用了商户侧的卡组令牌或 Antom 侧的卡组令牌。
更多信息:
- 最大长度:8 字符
exemptionRequested String
对于授权交易,Antom 申请豁免所使用的豁免类别。有效值为:
lowValue:满足特定的累计金额和交易次数标准,30 欧元以下的小额交易或可豁免强客户认证要求。transactionRiskAnalysis:根据支付服务提供商的风险评估,若交易被认定为欺诈风险较低,则可能豁免强客户认证要求。
更多信息:
- 最大长度:64 字符
issuerName String
发卡行。
当 paymentMethodType 的值为
CARD时,系统会返回此参数。
更多信息:
- 最大长度:256 字符
authorizationCode String
支付方式授权成功后返回的授权码。
注意:当支付方法在支付过程中返回授权码时,返回该参数。
incrementalAuthorizationAvailable Boolean
表示本次预授权是否支持增量授权。有效值为:
true:表示本次预授权支持增量授权。false:表示本次预授权不支持增量授权。
注意:当 result.resultStatus 的值为
S时返回此参数。
extendedAuthorizationAvailable Boolean
表示本次预授权是否支持延长授权。有效值为:
true:表示本次预授权支持延长授权。false:表示本次预授权不支持延长授权。
注意:当 result.resultStatus 的值为
S时返回此参数。
refundOnAuthorizationAvailable Boolean
表示预授权成功后是否支持通过 paymentId 发起退款。有效值为:
true:表示支持后续退款通过 paymentId 进行。false:表示不支持后续退款通过 paymentId 进行,需要指定 captureId。
注意:当 result.resultStatus 的值为
S时返回此参数。
Wallet
funding String
钱包的充值类型。
当 paymentMethodType 的值为
GRABPAY_MY或GRABPAY_SG时返回此参数。有效值包括:
WALLETS:表示使用钱包余额的普通钱包支付。BNPL_POSTPAID:表示先买后付,用户需支付全额。BNPL_INSTALLMENT:表示先买后付,用户分期付款。
更多信息:
- 最大长度:20 字符
creditPayPlan CreditPayPlan
分期付款的分期计划信息。
注意:当 paymentResultInfo.funding 的值为
BNPL_INSTALLMENT时返回此参数。
promotionResult Array <PromotionResult>
优惠结果。
注意:当买家在订购流程中采用优惠措施时返回此参数。
authExpiryTime Datetime
预授权过期时间。
注意:
- 当在 pay(单笔支付)接口中的 paymentMethodType 值为
CARD时返回此参数。- 当 result.resultStatus 的值为
S时返回此参数。- 请款必须在该时间之前发起,超时授权自动失效。
- 本参数在首笔预授权返回后即锁定,后续通过 updateAmount 接口调额不会重置或延长该时间。
更多信息:
- 值遵循 ISO 8601 标准格式。例如,“2019-11-27T12:01:01+08:00”。
updateRequestId String
调用 updateAmount 接口后获得的请求号。
注意:当 notifyType 为
UPDATE_AMOUNT_RESULT时返回此参数。
更多信息:
- 最大长度:64 字符
出参
result Result REQUIRED
发送给 Antom 以确认收到通知的固定值。
请求
响应
更多信息
本节提供了关于关键参数的额外信息。请参阅以下参数以了解详情:
- paymentTime: Antom 成功执行此支付的时间,即支付达到最终成功状态的日期和时间。此值用作后续可取消和可退款时间的开始时间。例如,如果退款时间为 6 个月,接受退款的最终时间是 paymentTime 加上 6 个月。
结果处理逻辑
在收到 Antom 通知后,发送以下固定值的消息给 Antom,以确认收到 Antom 的通知:
如果由于操作问题或网络问题没有将此类消息返回给 Antom,Antom 会反复发送通知,直到商家返回所需消息。首次通知发送后的 24 小时内会进行重试。通知将重试最多八次,间隔为 0 秒, 2 分钟, 10 分钟, 10 分钟, 1 小时, 2 小时, 6 小时, 和 15 小时。
注意:沙箱环境中,如果您没有按照固定格式返回信息,Antom 将不会重新发送异步通知给您。
结果码
| 结果码 | 值 | 结果码信息 | 行动建议 |
|---|---|---|---|
| SUCCESS | S | 成功 | 付款成功,无需进一步操作。 |
| ACCESS_DENIED | F | 访问被拒绝。 | 请咨询 Antom 技术支持以获取详细原因。 |
| ACCOUNT_CLOSED | F | 账户已关闭。 请核实账户号码的准确性,同一银行卡号或令牌请勿再次处理。 | 请立即联系发卡行,或使用其他卡完成支付。 |
| AUTHENTICATION_REQUIRED | F | 需要 3D Secure 验证。 | 重新启动支付并引导用户进行 3D Secure 认证。 |
| BLOCKED_BY_CARDHOLDER | F | 该卡被用户锁定。 | 请立即联系发卡行,或使用其他卡完成支付。 |
| BLOCKED_FIRST_USED | F | 卡片可能因以下原因被临时冻结:未激活首次使用,或受特殊条件限制(例如新卡未激活)。 | 请持卡人激活新卡,或联系发卡行确认临时冻结状态及适用条件。 |
| CANNOT_VERIFY_PIN | F | 无法验证 PIN 码。 | 可尝试以非 PIN 交易方式完成交易。 |
| CARD_EXPIRED | F | 银行卡过期。 | 检查 paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryMonth 的值是否正确: 如果不正确,请输入正确的值。 如果正确,请联系 Antom 技术支持以获取详细原因。 |
| CARD_NOT_SUPPORTED | F | 用于交易的银行卡不被支持。 | 使用另一张银行卡支付交易。 |
| CURRENCY_NOT_SUPPORT | F | 币种不受支持。 | 请咨询 Antom 技术支持以获取详细原因。 |
| DOMESTIC_DEBIT_TRANSACTION_NOT_ALLOWED | F | 不允许国内借记卡交易(仅限区域使用) | 请立即联系发卡行,或使用其他卡完成支付。 |
| DO_NOT_HONOR | F | 付款被发卡行拒绝。 | 请尝试使用其他银行卡支付,或联系发卡行。 |
| EXCEEDS_PREAUTHORIZED_AMOUNT_LIMIT | F | 交易金额超出预授权限额。 | 请持卡人降低交易金额至限额内,或联系发卡行申请提高预授权限额。 |
| EXPIRED_CODE | F | 支付码已过期。 | 用户需要刷新支付码。 |
| FRAUD_REJECT | F | 由于风险控制,交易无法进一步处理。如果用户已为交易付款,交易将被退款。 | 当满足以下任一条件时,请联系 Antom 技术支持:
|
| INSTALLMENT_NOT_SUPPORTED | F | 该卡或商户不支持分期。 | 该卡不支持分期,请换卡支付。 |
| INVALID_ACCESS_TOKEN | F | 访问令牌已过期、被撤销或不存在。 | 检查 accessToken 是否已过期、被撤销或不存在。重新签署合同并重新启动授权签名流程。 |
| INVALID_AMOUNT | F | 交易因多种原因被发卡行拒绝,例如指定金额无效或超过最大限额。 | 请联系 Antom 技术支持以获取详细原因。 |
| INVALID_API | F | 调用的接口无效或未激活。 | 请联系 Antom 技术支持来解决问题。 |
| INVALID_CARD_NUMBER | F | 交易使用的卡号无效。 | 检查 paymentMethod.paymentMethodMetaData.cardno 的值是否正确:
|
| INVALID_CONTRACT | F | 合同中的参数值与当前交易不符。 | 检查合同中的参数值是否与当前交易匹配。如果匹配,请联系 Antom 技术支持以解决问题。 |
| INVALID_CPF | F | 提供的 CPF 号码无效。 | 请确认您的身份信息并重试。 |
| INVALID_CVV | F | CVV 代码无效。 | 提示用户检查输入的 CVV 是否正确。 |
| INVALID_EXPIRATION_DATE | F | paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值无效。 | 检查 paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值是否正确:
|
| INVALID_MCC | F | 无效的 MCC(商户类别代码)。 | 请勿重试,并联系 Antom 技术支持获取详情。 |
| INVALID_MERCHANT_STATUS | F | 由于存在限制,商户状态异常。 | 请咨询 Antom 技术支持以获取详细原因。 |
| INVALID_INSTALLMENT_PLAN | F | 分期付款次数或间隔不正确。 | 请修改分期数后重试。 |
| INVALID_ISSUER | F | 无法联系持卡人的发卡行进行交易授权。 | 请勿重试,并联系发卡行确认卡片状态。 |
| INVALID_PIN | F | 提供的 PIN 码不正确或不符合要求。 | 请确保持卡人输入正确的 PIN 码,并检查其长度和格式是否符合要求。 |
| INVALID_TRANSACTION | F | 无效交易。 | 请勿重试,并联系 Antom 技术支持获取详情。 |
| KEY_NOT_FOUND | F | 未找到 Antom 或商户的私钥或公钥。 | 检查私钥或公钥是否存在。如果不存在,请在 Antom 开发者中心上传私钥。 |
| LAW_VIOLATION | F | 发卡行拒绝了该交易。 | 持卡人应联系发卡行以确认原因,并在解决问题后重试。 |
| LIFECYCLE | F | 由于无效的卡片数据,交易被拒绝。 | 请确保持卡人输入正确的卡片信息,并检查其长度和格式是否符合要求。 |
| LOST_CARD | F | 挂失卡(欺诈账户)。 | 持卡人应联系发卡行以确认原因。 |
| MERCHANT_BALANCE_NOT_ENOUGH | F | 商户余额不足。 | 在商户余额充足后再次调用接口。 |
| NO_INTERFACE_DEF | F | 接口未定义。 |
检查链接是否正确。请参考接口文档中的端点。 |
| NO_PAY_OPTIONS | F | 没有可用的支付方式。 | 请联系 Antom 技术支持以获取详细原因。 |
| NO_SELECTED_ACCOUNT | F | 持卡人选择了不存在的指定账户。 | 可尝试使用正确的账户类型重试。 |
| ORDER_IS_CLOSED | F | 交易已关闭,无法再次支付。 | 使用新的 paymentRequestId 来发起支付。 |
| ORDER_NOT_EXIST | F | 订单不存在。 | 检查 paymentId 是否正确。 |
| PARAM_ILLEGAL | F | 缺少必需的参数,或者存在非法参数。例如,非数字输入,无效的日期,或者参数的长度和类型错误。 |
检查并验证当前接口所需的请求字段(包括头字段和正文字段)是否正确传递并有效。 |
| PAYMENT_AMOUNT_EXCEED_LIMIT | F | 支付金额超过了合同或支付方式允许的最大金额。 | 检查支付金额是否超过限制,或使用较低的金额再试一次请联系 Antom 技术支持了解具体限制。 |
| PAYMENT_COUNT_EXCEED_LIMIT | F | 支付次数超过了支付方式规定的最大限制。 | 请联系 Antom 技术支持了解具体限制。 |
| PAYMENT_METHOD_SYSTEM_ERROR | F | 支付方式系统错误。 | 发卡行系统错误,请联系发卡行。 |
| PAYMENT_NOT_QUALIFIED | F | 商户因未注册、未签订自动扣款协议或被禁止支付,不具备支付资格。 | 请联系 Antom 技术支持以获取详细原因。 |
| PAYMENT_PROHIBITED | F | 由于商品在该国禁止销售,无法处理支付。 | 您无权对此交易提出申诉。 |
| PICKUP_CARD | F | 发卡行要求商户扣留支付卡。 此类情况通常出现在疑似伪卡或盗刷场景中。 | 请立即联系发卡行,或使用其他卡完成支付。 |
| PIN_REQUIRED | F | 处理交易必须提供 PIN 码,但持卡人未提供。 | 请使用有效的 PIN 码重试。 |
| POLICY | F | 政策限制。 | 持卡人应联系发卡行以确认原因。 |
| PROCESS_FAIL | F | 发生了常见的业务失败。 | 获得 Antom 技术支持前请勿重试。 |
| RE_ENTER_TRANSACTION | F | 交易暂时无法处理。 | 持卡人应联系发卡行以确认原因,并在解决问题后重试。 |
| REFERRAL_ISSUER | F | 交易被发卡行拒绝。 | 持卡人应联系发卡行以确认原因,并在解决问题后重试。 |
| RESTRICTED_CARD | F | 发卡行限制了该卡的使用范围。 | 请立即联系发卡行,或使用其他卡完成支付。 |
| RISK_REJECT | F | 由于风险控制,交易无法进一步处理。如果用户已为交易付款,交易将被退款。 | 如果用户在两周内未收到退款,请联系 Antom 技术支持。 |
| SECURITY_REJECT | F | 由于发卡行检测到安全问题,交易被拒绝。 |
|
| STOLEN_CARD | F | 被盗卡(欺诈账户)。 | 持卡人应联系发卡行以确认原因。 |
| STOP_RECURRING_PAYMENT | F | 持卡人已取消复购。 | 持卡人已要求取消订阅。 |
| SURCHARGE_NOT_ALLOWED | F | 该卡不支持附加费。 | 持卡人应联系发卡行以确认原因。 |
| SUSPECTED_RISK | F | 由于疑似安全问题,交易无法进一步处理。您可以在工作日后一天重试交易。如果交易不安全且用户已付款,交易将被退款。 | 当满足以下条件之一时请联系 Antom 技术支持:
|
| SYSTEM_ERROR | F | 发生了系统错误。 | 获得 Antom 技术支持前请勿重试。 |
| TRANSACTION_NOT_ALLOWED_AT_TERMINAL | F | 终端不允许该交易。 | 持卡人应联系发卡行以确认原因,并在解决问题后重试。 |
| TRANSACTION_NOT_PERMITTED | F | 发卡行拒绝了该卡/账户的交易。 | 持卡人可选择其他支付方式或联系发卡行寻求帮助。 |
| USER_AMOUNT_EXCEED_LIMIT | F | 支付金额超过了用户的支付限额。 | 使用不超过账户可用余额的金额创建新支付,或联系 Antom 技术支持。 |
| USER_BALANCE_NOT_ENOUGH | F | 由于用户在相应支付方式中的余额不足,无法完成支付。 | 请为账户充值或选择其他支付方式。 |
| USER_KYC_NOT_QUALIFIED | F | 由于用户的 KYC 状态,支付失败。用户要么未完成 KYC,要么 KYC 状态不符合此交易要求(例如,支付金额或产品信息的限制)。 | 首先完成 KYC 验证。 |
| USER_AUTHENTICATION_NOT_FINISHED | F | 用户超时未完成核身。 当用户支付时,拉起 3D 安全页面后未完成核身时返回此错误码。 | 重新发起支付。 |
| USER_NOT_EXIST | F | 在钱包端用户不存在。 | 请联系 Antom 技术支持以获取详细原因。 |
| USER_NOT_SUBMITTED | F | 用户超时未提交支付。 当使用中间页/SDK 集成时,用户拉起支付要素填写页面后,未点提交会触发超时。 | 重新发起支付。 |
| USER_PAYMENT_VERIFICATION_FAILED | F | 用户在支付方式端被限制支付。 | 请联系 Antom 技术支持了解具体原因。 |
| USER_STATUS_ABNORMAL | F | 用户在支付方式端的状态异常。 | 请联系 Antom 技术支持了解具体原因。 |
| VERIFY_TIMES_EXCEED_LIMIT | F | 当前验证码在支付验证中失败次数过多。 | 用户必须获取新的验证代码。 |
| VERIFY_UNMATCHED | F | 验证码无效。 | 用户必须获取新的验证代码。 |