Capture
APO automatically handles funds capture for you by default. If you specify the value of paymentFactor.captureMode to MANUAL
when calling the pay API or createPaymentSession API, you must capture the funds of the payment by calling the capture API.
- Automatic capture: APO automatically captures funds immediately after the user authorizes the payment. The capture result is then communicated to you via an asynchronous notification. Automatic capture is activated when one of the following conditions is met:
- You set the value of paymentFactor.captureMode in the pay API or createPaymentSession API to
AUTOMATIC
. - You leave the value of paymentFactor.captureMode in the pay API or createPaymentSession API empty or you do not pass in this parameter.
- Manual capture: You must initiate fund capture by calling the capture API after successful authorization. The total capture amount must be equal to the total authorized amount.
Note: For card payments, it is recommended to confirm the successful capture result before shipping.
Manually initiate a capture request
The key request parameters in the capture API (POST/v1/payments/capture) are shown in the following table:
Parameter | Description |
captureRequestId | A unique identifier that you assign to a capture request. |
paymentId | A unique identifier that Alipay+ assigns to an order. |
captureAmount | The capture amount, which must be equal to the total authorized amount. |
Table 1. Key parameters in the capture API
Obtain a capture result
In the response returned through the capture API, the value of the resultStatus parameter indicates the capture result.
S
: The capture is successful.F
: The capture failed.U
: You need to obtain the capture result by receiving an asynchronous notification through the notifyCapture notification or inquiring about the capture result.
You can handle the response according to the logic shown in the following figure:
Figure 1. Values of resultStatus in the response
Asynchronous notification
You can obtain the capture result by receiving an asynchronous notification through the notifyCapture notification. When a final capture status is achieved (that is, when the capture is successful or failed), APO sends you the asynchronous notification through the notifyCapture notification. When you receive the notification, you must return a response as instructed in Requirements. Otherwise, APO resends the notification until a correct response is received.
Key parameters in the asynchronous notification:
Parameter | Description |
notifyType | The value is |
paymentId | The unique identifier that APO assigns to an order. |
result | The capture result. |
acquirerReferenceNo | The relevant information of the acquiring institution handling this transaction, including the institution name, transaction number on the institution side |
Table 2. Key parameters in the notifyCapture notification
Configure a notification receiving address:
To receive the asynchronous notification, you must configure the notification address in either of the following two ways:
- Specify paymentNotifyUrl in the pay API.
- Edit Notification URL in the Integration Settings tab of Developer Center.
Inquire about the capture status
The asynchronous notification and the synchronous redirection can both fail to be received or implemented. We recommend that you inquire about the capture status by calling the inquiryPayment API. In the response returned through the inquiryPayment API, transactions indicates the capture status. See the following table for details:
Parameter | Description |
transactions.transationType | The value is |
transactions.transactionResult | The capture result. |
Table 3. Key child parameters of transactions
The value of transactions indicates the capture status. See the following code samples for details:
{
"transactions": [
{
"transactionType": "CAPTURE",
"transactionStatus": "SUCCESS",
"transactionRequestId": "test_test_test_XXXX",
"transactionAmount": {
"currency": "BRL",
"value": "110"
},
"transactionId": "2022XXXXXXXX",
"transactionResult": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "success"
}
}
]
}