Antom, leading provider of tailored payment solutions

notifyPayment

APO 使用此接口在支付处理完成时,将支付结果发送给商家。商家根据支付结果继续进行商家端的交易。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:
注意:将每个字段(除数组外)的数据类型设置为字符串。这意味字段值必须使用双引号(" ")括起来。例如:
  • 如果字段的数据类型为整数属性,且其值为 20,设置为 "20"。
  • 如果字段的数据类型为布尔属性,且其值为 true,设置为 "true"。


入参

notifyType String  REQUIRED

支付状态通知的类型。有效值包括:
  • PAYMENT_RESULT: 表示通知是关于支付结果的。
  • PAYMENT_PENDING: 表示买家已完成支付。商家需要等待最终的支付结果。 

result Result  REQUIRED

支付结果的详细信息,如支付状态、结果代码和结果消息。

paymentRequestId String  REQUIRED

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

更多信息:

  • 最大长度:64 字符

paymentId String  REQUIRED

APO 为识别支付而分配的支付 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  

支付结果信息。
注意:当 paymentMethodType 在 pay 接口中的值为 CARD 时,返回此参数。  

acquirerInfo AcquirerInfo  

处理该支付的收单机构信息。

出参

result Result  REQUIRED

发送给 APO 以确认收到通知的固定值。
API Explorer

请求

Case
json
{
  "acquirerInfo": {
    "acquirerMerchantId": "21811100024730H6",
    "acquirerName": "ALIPAY",
    "acquirerResultCode": "SUCCESS",
    "acquirerResultMessage": "success",
    "acquirerTransactionId": "202508201140108001001814F0276126015",
    "referenceRequestId": "PAYMENT_20250820143310572_AUTO"
  },
  "actualPaymentAmount": {
    "currency": "USD",
    "value": "30000"
  },
  "authExpiryTime": "2025-08-26T23:33:16-07:00",
  "cardInfo": {
    "cardBrand": "VISA",
    "cardCategory": "",
    "funding": "CREDIT",
    "issuingCountry": "US"
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "30000"
  },
  "paymentId": "202508201140108001001814F0276126015",
  "paymentMethodType": "CARD",
  "paymentRedirectUrl": "https://www.alipay.com",
  "paymentRequestId": "PAYMENT_20250820143310572_AUTO",
  "paymentResultCode": "SUCCESS",
  "paymentResultInfo": {
    "rrn": "487478137189",
    "avsResultRaw": "R",
    "cardBrand": "VISA",
    "cardCategory": "",
    "cardNo": "************0768",
    "cardBin": "541111",
    "credentialTypeUsed": "PAN",
    "cvvResultRaw": "X",
    "funding": "CREDIT",
    "issuingCountry": "US",
    "paymentMethodRegion": "GLOBAL",
    "threeDSResult": {
      "cavv": "",
      "challengeCancel": "",
      "challenged": false,
      "eci": "",
      "threeDSOffered": false,
      "threeDStransactionStatusReason": ""
    }
  },
  "paymentResultMessage": "success.",
  "paymentStatus": "SUCCESS",
  "paymentTime": "2025-08-19T23:33:16-07:00",
  "transactions": [
    {
      "acquirerInfo": {
        "acquirerMerchantId": "21811100024730H6",
        "acquirerName": "ALIPAY",
        "acquirerResultCode": "SUCCESS",
        "acquirerResultMessage": "success",
        "acquirerTransactionId": "202508201140108070001814F0284227145",
        "referenceRequestId": "PAYMENT_20250820143310572_AUTO"
      },
      "transactionAmount": {
        "currency": "USD",
        "value": "30000"
      },
      "transactionId": "202508201140108070001814F0284227145",
      "transactionRequestId": "PAYMENT_20250820143310572_AUTO",
      "transactionResult": {
        "resultCode": "SUCCESS",
        "resultMessage": "success",
        "resultStatus": "S"
      },
      "transactionStatus": "SUCCESS",
      "transactionTime": "2025-08-19T23:33:19-07:00",
      "transactionType": "CAPTURE"
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

响应

json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}

更多信息

本节提供了关于关键参数的额外信息。请参阅以下参数以了解详情:
  • paymentTime: APO 成功执行此支付的时间,即支付达到最终成功状态的日期和时间。此值用作后续可取消和可退款时间的开始时间。例如,如果退款时间为 6 个月,接受退款的最终时间是 paymentTime 加上 6 个月。

结果处理逻辑

在收到 APO 通知后,发送具有固定值的消息给 APO,以确认已收到 APO 的通知:
Sample Codetext
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}
如果由于操作问题或网络问题没有将此类消息返回给 APO,APO 会反复发送通知,直到商家返回所需消息。首次通知发送后的 24 小时内会进行重试。通知将重试最多八次,间隔为 0 秒, 2 分钟, 10 分钟, 10 分钟, 1 小时, 2 小时, 6 小时, 和 15 小时。

结果码

结果码值结果码信息行动建议
SUCCESSS成功
付款成功,无需进一步操作。
ACCESS_DENIEDF访问被拒绝。
请咨询 APO 技术支持以获取详细原因。
INVALID_APIF调用的接口无效或未激活。
请联系 APO 技术支持来解决问题。
CURRENCY_NOT_SUPPORTF货币不受支持。
请咨询 APO 技术支持以获取详细原因。
EXPIRED_CODEF支付码已过期。
买家需要刷新支付码。
FRAUD_REJECTF由于风险控制,交易无法进一步处理。如果用户已为交易付款,交易将被退款。
当满足以下任一条件时,请联系 APO 技术支持:
  • 您想要提出申诉。
  • 用户在两周内未收到退款。
INVALID_ACCESS_TOKENF访问令牌已过期、被撤销或不存在。
检查 accessToken 是否已过期、被撤销或不存在。重新签署合同并重新启动授权签名流程。
INVALID_CONTRACTF合同中的参数值与当前交易不符。
检查合同中的参数值是否与当前交易匹配。如果匹配,请联系 APO 技术支持以解决问题。
INVALID_MERCHANT_STATUSF由于存在限制,商户状态异常。
请咨询 APO 技术支持以获取详细原因。
KEY_NOT_FOUNDF未找到 APO 或商户的私钥或公钥。
检查私钥或公钥是否存在。如果不存在,请在 APO 开发者中心上传私钥。
MERCHANT_BALANCE_NOT_ENOUGHF商户余额不足。
在商户余额充足后再次调用接口。 
NO_INTERFACE_DEFF接口未定义。
检查链接是否正确。请参考接口文档中的端点。
NO_PAY_OPTIONSF没有可用的支付方式。
请联系 APO 技术支持以获取详细原因。
ORDER_IS_CLOSEDF交易已关闭,无法再次支付。
使用新的 paymentRequestId 来发起支付。
ORDER_NOT_EXISTF订单不存在。
检查 paymentId 是否正确。
PARAM_ILLEGALF缺少必需的参数,或者存在非法参数。例如,非数字输入,无效的日期,或者参数的长度和类型错误。
检查并验证当前接口所需的请求字段(包括头字段和正文字段)是否正确传递并有效。
PAYMENT_AMOUNT_EXCEED_LIMITF支付金额超过了合同或支付方式允许的最大金额。
检查支付金额是否超过限制,或使用较低的金额再试一次请联系 APO 技术支持了解具体限制。
PAYMENT_COUNT_EXCEED_LIMITF支付次数超过了支付方式规定的最大限制。
请联系 APO 技术支持了解具体限制。
PAYMENT_NOT_QUALIFIEDF商户因未注册、未签订令牌支付协议或被禁止支付,不具备支付资格。
请联系 APO 技术支持以获取详细原因。
PROCESS_FAILF发生了常见的业务失败。
获得 APO 技术支持前请勿重试。
RISK_REJECTF由于风险控制,交易无法进一步处理。如果买家已为交易付款,交易将被退款。
如果买家在两周内未收到退款,请联系 APO 技术支持。
PAYMENT_IN_PROCESSU支付正在处理中。
您发起的请求具有与现有交易(可能是成功或进行中的交易)相同的 paymentRequestId 。检查响应中是否返回了 redirectActionForm.redirectUrl。如果返回了,将用户重定向到 rediectUrl 指定的地址以完成支付。如果没有返回,支付可能已经完成。详细信息请参阅结果处理逻辑。
SUSPECTED_RISKF由于疑似安全问题,交易无法进一步处理。您可以在工作日后一天重试交易。如果交易不安全且用户已付款,交易将被退款。
当满足以下条件之一时请联系 APO 技术支持:
  • 重试后交易仍无法进一步处理。
  • 买家在两周内未收到退款。
SYSTEM_ERRORF发生了系统错误。
获得 APO 技术支持前请勿重试。
UNKNOWN_EXCEPTIONU由于未知原因,接口调用失败。
再次调用接口解决问题。如果问题仍未解决,请联系 APO 技术支持。 
USER_AMOUNT_EXCEED_LIMITF支付金额超过了用户的支付限额。
使用不超过账户可用余额的金额创建新支付,或联系 APO 技术支持。
USER_BALANCE_NOT_ENOUGHF由于用户在相应支付方式中的余额不足,无法完成支付。
请为账户充值或选择其他支付方式。
USER_KYC_NOT_QUALIFIEDF由于用户的 KYC 状态,支付失败。用户要么未完成 KYC,要么 KYC 状态不符合此交易要求(例如,支付金额或产品信息的限制)。
首先完成 KYC 验证。
USER_NOT_EXISTF在钱包端用户不存在。
请联系 APO 技术支持以获取详细原因。 
USER_PAYMENT_VERIFICATION_FAILEDF买家在支付方式端被限制支付。
请联系 APO 技术支持了解具体原因。
USER_STATUS_ABNORMALF买家在支付方式端的状态异常。
请联系 APO 技术支持了解具体原因。
VERIFY_TIMES_EXCEED_LIMITF当前验证码在支付验证中失败次数过多。
买家必须获取新的验证代码。  
VERIFY_UNMATCHEDF验证码无效。
买家必须获取新的验证代码。  
AUTHENTICATION_REQUIREDF需要 3D Secure 验证。
重新启动支付并引导买家进行 3D Secure 认证。 
PAYMENT_PROHIBITEDF由于商品在该国禁止销售,无法处理支付。
您无权对此交易提出申诉。  
CARD_NOT_SUPPORTEDF用于交易的银行卡不被支持。
使用另一张银行卡支付交易。 
INVALID_EXPIRATION_DATEFpaymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值无效。
检查 paymentMethod.paymentMethodMetaData.expiryYear 或 paymentMethod.paymentMethodMetaData.expiryDate 的值是否正确:
  • 如果不正确,请传入正确的值。
  • 如果正确,请联系 APO 技术支持以获取详细原因。 
INVALID_CARD_NUMBERF交易使用的卡号无效。
检查 paymentMethod.paymentMethodMetaData.cardno 的值是否正确:
  • 如果值不正确,请输入正确的值并重试。
  • 如果值正确,该卡不支持此交易,请使用其他卡进行支付。 
DO_NOT_HONORF付款被发卡行拒绝。
请尝试使用其他银行卡支付,或联系发卡行。
INVALID_AMOUNTF交易因多种原因被发卡行拒绝,例如指定金额无效或超过最大限额。
请联系 APO 技术支持以获取详细原因。