/v2/payments/capture

2022-11-17 04:34

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	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 `result.resultCode`is "SUCCESS" and the `result.resultMessage` is "Success".
U	The status of the capture is unknown. The corresponding `result.resultCode` is `UNKNOWN_EXCEPTION`, and `result.resultMessage` is "An API calling is failed, which is caused by unknown reasons". For details, see the Common error codes section.
F	The capture fails. The corresponding `result.resultCode` and `result.resultMessage` may vary based on different situations. For details, see the Error codes section.

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

copy
{
 "captureRequestId":"20191127190741010007013213156",
 "paymentId":"20191127190741010007013213121",
 "captureAmount": {
    "value":"1000",
    "currency":"USD"
 }
}

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S"
 },
 "captureRequestId":"20191127190741010007013213156",
 "captureId":"201231231313123167",
 "paymentId":"20191127190741010007013213121",
 "captureAmount": {
    "value":"1000",
    "currency":"USD"
 },
 "captureTime":"2021-06-08T12:12:12+08:00"
}