/v2/payments/capture

2021-07-21 11:23

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

Property	Data Type	Required	Description	Example
captureRequestId	String	Yes	The unique ID of a capture generated by merchants. Max. length: 64 characters	capture_2089760038715669_202775745075671
paymentId	String	Yes	The payment ID of the original authorization to be captured. Max. length: 64 characters	20190612114010800100188820200355883
captureAmount	Amount	No	The payment amount to be captured. The default value is `full capture`. For a full capture, it's optional to transmit this property.	copy `{ "currency": "USD", "value": "50" }`
isLastCapture	boolean	No	The last time of capture. The default value is `true`, which means the capture for the last time. Change the value to `false` will trigger another capture.	false
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo" }`

Response

Property	Data Type	Required	Description	Example
result	Result	Yes	The request result, which contains information such as result status and error codes.	copy `{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }`
captureRequestId	String	No	The unique ID of a capture generated by a merchant. Max. length: 64 characters	capture_2089760038715669_202775745075671
captureId	String	No	The unique ID for a capture request is generated by the wallet. Max. length: 64 characters	201811291907410100070000004444
paymentId	String	No	The unique ID is assigned by a merchant to identify a payment request. Max. length: 64 characters	20190612114010800100188820200355883
captureAmount	Amount	No	The payment amount that is captured for a request.	copy `{ "currency": "USD", "value": "50" }`
captureTime	Datetime	No	The processing time for a capture request. The format of the value follows the ISO 8601 standard.	2019-06-12T14:07:05+08:00
extendInfo	String	No	The extended information that wallets and merchants want to describe. Max. length: 4096 characters.	copy `{ "memo": "memo" }`

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 wallet.
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 last 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"
}