请款
授权成功之后的七天内,您需要通过调用 请款 接口(POST/v1/payments/capture),完成请款,否则 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 设定异步通知地址。
- 在 Alipay 开发者中心 Integration Settings 标签页下,编辑 Notification URL进行配置。
主动查询
请款 请求的响应及异步通知均有无法触达或延迟的可能性;建议您在服务端通过 查询支付结果 接口主动查询请款状态,该接口响应中的 transactions 字段的值为请款状态:
字段名 | 注意点 |
transactions.transationType | 值为 |
transactions.transactionResult | 请款结果 |
表 3. 主动查询响应中 transaction 字段关键信息说明
以下示例展示了支付查询接口的响应中,transactions 字段在不同情况下的返回值:
{
"transactions": [
{
"transactionType": "CAPTURE",
"transactionStatus": "SUCCESS",
"transactionRequestId": "test_test_test_XXXX",
"transactionAmount": {
"currency": "BRL",
"value": "110"
},
"transactionTime": "2022-09-29T07:13:50-07:00",
"transactionId": "2022XXXXXXXX",
"transactionResult": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success"
}
}
]
}