/v1/payments/capture

POST /v1/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. The capture can only be initiated once, whether it is partial or full amount.

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.

  • Partial Captures

Capture the patial amount of an authorized payment once.

Note: All monetary values in the fields of request and response in their smallest currency units, and for IQD, the smallest unit is fils. Thus, if a transaction amount is 150 IQD, the value will be gaven as 150000.

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

"1022188000000000001xxxx"

paymentId

String

Yes

The payment ID of the original authorization to be captured.

Max. length: 64 characters

"2023120611121280010016600090000xxxx"

captureAmount

Amount

No

The payment amount to be captured.

The captureAmount is mandatory in partial capture scenario.

The captureAmount is optional in full capture scenario.

{

   "value":"100",

   "currency":"IQD"

}

extendInfo

String

No

The extension information that wallets and merchants want to describe. The format shoud be JSON format.

Max. length: 2048 characters.

"extendInfo: This is additional information"

Response

Property

Data Type

Required

Description

Example

result

Result

Yes

The request result, which contains information such as result status and error codes.

{

   "resultCode": "SUCCESS",

   "resultStatus": "S",

   "resultMessage": "Success."  

 }

captureId

String

No

The unique ID for a capture request generated by the wallet.

Max. length: 64 characters

"2023120611121280160016600090000xxxx"

captureTime

Datetime

No

The processing time for a capture request. The format of the value follows the ISO 8601 standard.

"2023-07-08T12:12:12+08:00"

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

It means that the capture is successful.

The corresponding result.resultCode is "SUCCESS", and the 

result.resultMessage is "Success.".

U

It means that 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.

What needs to note is as follow:

  • U status (inquiry/retry still gets U)  can not set to fail or success on merchant/partner system.

If other response (almost never occur), the merchant/partner should process like U.

F

It means that 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.

resultStatus

resultCode

resultMessage

F

ORDER_UNSUPPORTED_OPERATION

The order is not support capture.

F

ORDER_STATUS_INVALID

The order status is invalid.

F

ORDER_NOT_EXIST

The order does not exist.

F

AUTH_CANCELLED

The authorization on payment has been canceled.

F

AUTH_EXPIRED

The authorization on payment is expired

F

AUTH_NOT_FOUND

The authorization on payment is not found.

U

CAPTURE_IN_PROCESS

The capture is processing.

F

CURRENCY_NOT_SUPPORT

The currency of a user's payment is not supported by the merchant.

F

USER_NOT_EXIST

The user does not exist.

F

USER_BALANCE_NOT_ENOUGH

The user's balance is not enough for the payment.

F

USER_STATUS_ABNORMAL

The user status is abnormal.

F

PARTNER_NOT_EXIST

The partner does not exist.

F

PARTNER_STATUS_ABNORMAL

The partner status is abnormal.

F

PAYMENT_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the limit.

F

PAYMENT_COUNT_EXCEED_LIMIT

The number of payments exceeds the limit.

F

REPEAT_REQ_

INCONSISTENT

The submitted request is not consistent with the repeated one.

F

USER_AMOUNT_EXCEED_LIMIT

The payment amount exceeds the user's amount limit.

F

RISK_REJECT

The payment is rejected due to risk control.

F

CLIENT_INVALID

The client is invalid.

F

SIGNATURE_INVALID

The signature is invalid.

F

METHOD_NOT_SUPPORTED

The server does not implement the requested HTTP method.

F

MEDIA_TYPE_NOT_ACCEPTABLE

The server does not implement the media type that can be accepted by the client.

F

CAPTURE_AMOUNT_EXCEED_AUTH_LIMIT

The total capture amount exceeds the limit of the authorized payment amount.

F

MUTEX_OPERATION_IN_PROCESSING

There is another payment void, confirm, or capture in processing.

Samples

For example, a wallet user authorizes a 1000 IQD to make a hotel reservation, and when the user leaves the hotel,  merchant/partner will call this capture API to the wallet to capture user‘s auth amount.

capture.png

  1. The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
  2. The E-wallet App service calls authorization service to processes the authorization information.
  3. The E-wallet backend verifies the authorization information, generates the authCode and returns.
  4. The E-wallet App service returns the authCode to the Mini Program.
  5. The Mini Program sends the authCode to the merchant backend.
  6. The merchant backend calls the applyToken API with authCode to apply the accessToken.
  7. The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
  8. The Mini Program creates an order with customerId.
  9. The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
  10. The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
  11. The merchant backend passes the payment detail information to the Mini Program.
  12. The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
  13. The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
  14. The user confirms the payment in the cashier page.
  15. The E-Wallet App Service calls payment service and execute the payment process.
  16. When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
  17. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
  18. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
  19. After the service or goods has been delivered, the user could confirm capture in the Mini Program or the merchant cashier (Step 21).
  20. The Mini Program sends the capture request to merchant backend, and the merchant backend calls the capture API to capture the money(Step 23).
  21. The E-Wallet backend returns the capture result to the merchant backend.
  22. And the Mini Program displays the capture result to the user(Step 26).
  23. When the E-Wallet backend returns the resultCode as CAPTURE_IN_PROCESS, the merchant can call inquiryPayment API to query capture result (Step 27).

Request

copy
{
 "captureRequestId":"20231127190741010007013213156",
 "paymentId":"2023120611121280010016600090000xxxx",
 "captureAmount": {
    "value":"1000",
    "currency":"IQD"
 }
}
  • captureRequestId is the unique ID of this capture request, generated by merchant/partner, merchant/partner should make sure it is unique, because wallet will use captureRequestId to do idempotent process.
  • paymentId is the unique Id of a payment generated by Wallet, which is the unique payment identifier associated with this capture.

Response

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success."
 },
 "captureRequestId":"20231127190741010007013213156",
 "captureId":"2023120611121280010016600090000xxxx",
 "captureTime":"2021-06-08T12:12:12+08:00"
}
  • result.resultStatus==S shows that the Wallet capture is successful.
  • captureId is generated by Wallet, uniquely identifies the capture.
  • captureTime describes the success date time of this capture.