/v2/payments/capture
POST /v2/payments/capture
The capture
API is used to capture the total authorized payment amount from a user's account, and then transfer the total amount of the payment to a merchant's account after the user confirms receipt.
Depending on different scenarios, the capture
API can be divided into the following two types:
- Full Capture
Capture the full amount of an authorized payment once. Full Capture is helpful for merchants who have a delayed order fulfillment process.
- Multiple Captures
Capture the full amount of an authorized payment multiple times. Multiple captures enable merchants to change the original authorization amount when the payment amount is changed due to shipping, taxes, or other factors.
Message structure
A message consists of a header and body. The following sections focus on the body structure. For the header structure, see:
Request
Response
Property | Data Type | Required | Description |
result | Yes | The request result, which contains information such as result status and error codes. | |
captureRequestId | String | No | The unique ID of a capture generated by a merchant. Max. length: 64 characters |
captureId | String | No | The unique ID for a capture request generated by the wallet. Max. length: 64 characters |
paymentId | String | No | The unique ID is assigned by a merchant to identify a payment request. Max. length: 64 characters |
captureAmount | Amount | No | The payment amount that is captured for a request. |
captureTime | Datetime | No | The processing time for a capture request. The format of the value follows the ISO 8601 standard. |
extendInfo | String | No | The extension information that wallets and merchants want to describe. Max. length: 4096 characters. |
Result process logic
In the response, the result.resultStatus
field indicates the result of processing a request. The following table describes each result status:
resultStatus | Description |
S | The capture is successful. The corresponding
|
U | The status of the capture is unknown. The corresponding
|
F | The capture fails. The corresponding |
Error codes
Error codes are usually classified into the following categories:
- Common error codes are common across all mini program's APIs. Â
- API-specific error codes: are listed in the following table.
resultCode | resultStatus | resultMessage |
SUCCESS | S | success |
AUTH_CANCELLED | F | The authorization on payment has been canceled. |
AUTH_EXPIRED | F | The authorization on payment is expired |
AUTH_NOT_FOUND | F | The authorization on payment is not found. |
CAPTURE_IN_PROCESS | U | The capture is processing. |
INVALID_TOKEN | F | The access token is invalid. |
CURRENCY_NOT_ SUPPORT | F | The currency of a user's payment is not supported by the merchant. |
USER_BALANCE_NOT_ ENOUGH | F | The user's balance is not enough for the payment. |
USER_STATUS_ ABNORMAL | F | The user status is abnormal. |
PAYMENT_AMOUNT_ EXCEED_LIMIT | F | The payment amount exceeds the limit. |
PAYMENT_COUNT_ EXCEED_LIMIT | F | The number of payments exceeds the limit. |
REPEAT_REQ_ INCONSISTENT | F | The submitted request is not consistent with the repeated one. |
USER_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the user's amount limit. |
RISK_REJECT | F | The payment is rejected due to risk control. |
KEY_NOT_FOUND | F | The key is not found. |
CLIENT_INVALID | F | The client is invalid. |
SIGNATURE_INVALID | F | The signature is invalid. |
METHOD_NOT_ SUPPORTED | F | The server does not implement the requested HTTP method. |
MEDIA_TYPE_NOT_ ACCEPTABLE | F | The server does not implement the media type that can be accepted by the client. |
CAPTURE_AMOUNT_ EXCEED_AUTH_LIMIT | F | The total capture amount exceeds the limit of the authorized payment amount. |
Samples
Request
{
"captureRequestId":"20191127190741010007013213156",
"paymentId":"20191127190741010007013213121",
"captureAmount": {
"value":"1000",
"currency":"USD"
}
}
Response
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S"
},
"captureRequestId":"20191127190741010007013213156",
"captureId":"201231231313123167",
"paymentId":"20191127190741010007013213121",
"captureAmount": {
"value":"1000",
"currency":"USD"
},
"captureTime":"2021-06-08T12:12:12+08:00"
}