Antom, leading provider of tailored payment solutions

请款

默认情况下 Alipay+ 会为您自动完成请款。如果您在调用 支付 接口发起授权时指定 paymentFactor.captureMode 字段值为 MANUAL,此时需要您主动调用 请款 接口来完成请款。
  • 自动请款:买家授权完成后 Alipay+ 会自动立即发起请款。请款成功后,Alipay+ 会向您发送请款结果通知。请款模式在如下情况下均为自动请款:
  • 您指定 支付 接口的 paymentFactor.captureMode 字段的值为 AUTOMATIC。
  • 支付 接口的 paymentFactor.captureMode 字段为空或不传。
  • 手动请款:买家授权完成后的七天内,您需要自己通过 请款 接口发起请款请求,否则 Alipay+ 会自动将买家冻结的资金解除。需注意的是,请款的总金额需等于买家授权的金额。
【注意】卡支付场景下,建议您以请款成功作为发货依据。

手动发起请款

调用 请款 接口(POST/v1/payments/capture)时注意以下关键参数:
字段名
注意点
captureRequestId
在商户侧唯一的请款ID
paymentId
授权返回的蚂蚁侧订单ID
captureAmount
请款金额,应等于授权的金额
表 1. 请款接口请求关键参数

获取请款结果

在 请款 请求的响应中, resultStatus 参数的值为请款结果:
  • S:请款成功。
  • F:请款失败。
  • U,需通过接收异步通知(notifyCapture)或者发起主动查询获取请款结果。
您可以根据下图的逻辑对请款响应进行处理:
图 1. 请款响应中 resultStatus 的参数值含义

异步通知

通过接收 Alipay+ 发送给您的 请款结果通知(notifyCapture)可以获取请款结果。当请款到达终态后(即请款成功或失败时),Alipay+ 会利用 请款结果通知 向该地址发送异步通知;未达终态,则不会发送异步通知。收到异步通知后,请按 要求 进行回应,否则 Alipay+ 会重发异步通知。
异步通知关键字段:
字段名
注意点
notifyType
值为 CAPTURE_RESULT
paymentId
授权支付阶段返回的 Alipay+ 侧订单 ID
result
请款结果
acquirerReferenceNo
对于接入新加坡,香港地区卡支付的商户,会在通知中告知具体的收单站编号。
表 2. 异步通知返回的关键字段说明

配置异步通知接收地址:
为收到 请款结果通知 ,您需要提前通过以下两种方式之一配置异步通知的接收地址:
  • 通过 支付 接口中的参数 paymentNotifyUrl 设定异步通知地址。
  • 在开发者中心 Integration Settings 标签页下,编辑 Notification URL进行配置。

主动查询

请款 请求的响应及异步通知均有无法触达或延迟的可能性;建议您在服务端通过 查询支付结果 接口主动查询请款状态,该接口响应中的 transactions 字段的值为请款状态:
字段名
注意点
transactions.transationType
值为 CAPTURE,代表为请款的状态
transactions.transactionResult
请款结果
表 3. 主动查询响应中 transaction 字段关键信息说明
以下示例展示了支付查询接口的响应中,transactions 字段在不同情况下的返回值:
请款成功
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "SUCCESS",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
      }
    }
  ]
}
请款失败
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "FAIL",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionTime": "2022-09-29T07:13:50-07:00",
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "F",
        "resultCode": "PROCESS_FAIL",
        "resultMessage": "General business failure. No retry."
      }
    }
  ]
}
请款进行中
json
{
  "transactions": [
    {
      "transactionType": "CAPTURE",
      "transactionStatus": "PROCESSING",
      "transactionRequestId": "test_test_test_XXXX",
      "transactionAmount": {
        "currency": "BRL",
        "value": "110"
      },
      "transactionId": "2022XXXXXXXX",
      "transactionResult": {
        "resultStatus": "U",
        "resultCode": "PAYMENT_IN_PROCESS",
        "resultMessage": "payment in process"
      }
    }
  ]
}