Capture
It is applicable to both EC and In-Store Scenario.
For some payment methods, the payment process is completed in two steps:
- Authorization: Verifies the payment details of the user and reserves the funds.
- Capture: Transfers the reserved funds from the user’s account to your account.
- For instant payment methods, the payment is captured immediately after authorization.
- For non-instant payment methods that support separate authorization and capture, you can capture the payment later. This allows for cancellation in case of any issues.
Here is the matrix for the payment methods and whether separate authorization and capture are supported.
| Payment Method | Payment Brand | Support |
|---|---|---|
| Token & Card | VISA | Yes |
| Mastercard | Yes | |
| AMEX | Yes | |
| JCB | Yes | |
| Diners / Discover | Yes | |
| UnionPay | Yes | |
| TPN | Yes | |
| E-Wallet | ALL | No |
| Online Banking | ALL | No |
| Points | ALL | No |
| Bank Transfer | ALL | No |
| By Now Pay Later | ALL | No |
| Carrier Billing | ALL | No |
| Cash | ALL | No |
| Prepaid Card | ALL | No |
| Google Pay™️ | ALL | Yes |
Manual capture
To capture a payment, make an HTTP POST request to the EVO Cloud endpoint: /g2/v1/payment/mer/{sid}/capture Key Points:
Default Behavior: If you do NOT specify the
captureAfterHoursfield in the initial payment request to/g2/v1/payment/mer/{sid}/payment, the default capture setting will apply for payment methods that support separate authorization and capture.No Separate Capture: For payment methods that do not support separate authorization and capture, the
captureAfterHoursfield is ignored, as payments are captured immediately after authorization.Timing: It is recommended to send the capture request within 7 days after authorization, as most issuers will expire the authorization after this period.
Amount Limit: The capture amount CANNOT exceed the initial payment amount.
Automatic capture
Payment can be captured automatically by EVO Cloud after authorization, which means you do NOT need to request for capture endpoint.
You need to specify the captureAfterHours field when you make an HTTP POST request to EVO Cloud endpoint (/g2/v1/payment/mer/{sid}/payment) to enable this feature. Then EVO Cloud backend will setup an automatic capture task according to the captureAfterHours you specified.
0 to 168 is the valid range for captureAfterHours, meaning that you can set up to 168 hours (7 days) later for automatic capture after authorization. 0 means capture the payment immediately after authorization.
Setting up a delay between authorization and capture allows you to cancel the payment before it is captured, for example, when the good is out of stock. EVO Cloud will cancel the backend automatic capture task if you cancel the payment.
Even a payment is authorized with automatic capture mode, you can choose to capture it manually following the manual capture mode before it is automatically captured by EVO Cloud. If the capture is triggered manually in this way, the backend automatic capture task in EVO Cloud will be cancelled to avoid double capture.
Partial capture
With some payment methods, you can also capture a payment partially. Here is the matrix for the payment methods and Payment Brands that support partial capture.
| Payment Method | Payment Brand |
|---|---|
| Token & Card | VISA |
| Mastercard | |
| AMEX | |
| JCB | |
| Diners / Discover | |
| UnionPay | |
| TPN | |
| Google Pay™️ | ALL |
INFO
Please note that you can only capture a payment once, and if you partially capture it, any unclaimed amount left will be automatically cancelled.
Make capture request
Step 1: Make a capture request
When you get a payment result with the payment.status with Authorised, you can make an HTTP POST request from your server to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/capture
to manual capture the payment,
and specify the parameters below.
| Parameter | Required | Description |
|---|---|---|
| merchantTransID | M | The merchantTransInfo.merchantTransID of the initial payment. |
| merchantTransInfo | M | The reference for the capture, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
| transAmount | M | The currency and value of the payment. The value must follow the currency's minor unit. |
| initiatingReason | O | You can state the reason for this request in this field. |
| webhook | O | The URL to receive notification. Specify this to get the notification from EVO Cloud after the payment succeeds. |
| metadata | O | A self-defined reference information that you can specify in the request, echoed back in the response. Metadata |
Here is an example of making a 10 USD capture:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/capture?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_PAYMENT}\
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "YOUR_CAPTURE_TRANS_ID",
10. "merchantTransTime": "2021-12-31T08:35:59+08:00"
11. },
12. "transAmount": {
13. "currency": "USD",
14. "value": "10.00"
15. },
16. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
17. "initiatingReason": "This order is completed",
18. "metadata": "This is a metadata"
19.}'If the request is successful, the response will include a capture object and a payment object. Here are the details of the capture object:
Detail information about capture object:
capture.status: The status of the capture, required. The value can be Success, Failed, or Received. If you get acapture.statuswith Received, you need to either make another HTTP GET request to get the final status of the capture (see Step 2 for more details), or wait for the notification webhook from EVO Cloud.capture.transAmount: The currency and value of the capture, required. It is echoed back from your request.capture.merchantTransInfo: The object that is a reference for the capture, generated by your host, required. It is echoed back from your request.capture.evoTransInfo: The object that is a reference for the capture, generated by EVO Cloud, required. It containsevoTransID,evoTransTime, andtraceNum(optional) andretrievalReferenceNumfor some PSPs such as Visa or Mastercard.capture.pspTransInfo: The object that is a reference for the capture, generated by PSP, optional. It containspspTransID,pspTransTime, andauthorizationCode. EVO Cloud forwards this information from PSP to your host if PSP returns.capture.billingAmountandcapture.billingFXRate: The user's billing currency and value of the capture, and the FX rate betweencapture.transAmount.currencyandcapture.billingAmount.currency, optional. EVO Cloud forwards this information from PSP to your host if PSP returns. This is applied to some E-Wallet payment when PSP conducts the currency conversion, or to some card payment when you enable the DCC feature. You can contact EVO Cloud account manager for more details.capture.convertTransAmountandcapture.convertTransFXRate: The currency and value calculated by EVO Cloud based ontransAmountand the FX rate fromtransAmount.currencyto a different currency when the transaction is sent out to PSP, and the FX rate betweencapture.transAmount.currencyandcapture.convertTransAmount.currency, optional. The FX rate will be provided if you enable the currency conversion feature in EVO Cloud and this capture applies currency conversion. You can contact EVO Cloud account manager for more details.
Here is an example of a successful response:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethod": {
7. "card": {
8. "first6No": "476134",
9. "last4No": "0019",
10. "paymentBrand": "Visa",
11. "fundingType": "credit"
12. }
13. },
14. "payment": {
15. "status": "Capturing",
16. "merchantTransInfo": {
17. "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
18. "merchantTransTime": "2021-12-31T08:30:59+08:00"
19. },
20. "evoTransInfo": {
21. "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",
22. "evoTransTime": "2021-12-31T00:30:59Z"
23. },
24. "pspTransInfo": {
25. "pspTransTime": "2021-12-31T08:30:59+08:00",
26. "authorizationCode": "091410",
27. "retrievalReferenceNum": "135616370503"
28. },
29. "transAmount": {
30. "currency": "USD",
31. "value": "10.00"
32. }
33. },
34. "capture": {
35. "status": "Received",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CAPTURE",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "d9e9022475f84ef09932becef13f7113",
42. "evoTransTime": "2021-12-31T08:35:59+08:00"
43. },
44. "transAmount": {
45. "currency": "USD",
46. "value": "10.00"
47. }
48. },
49. "pspData": {
50. "name": "Visa"
51. },
52. "metadata": "This is a metadata"
53.}Step 2: Retrieve the capture result
If you get a capture.status with Received and you don't use the Accept Notification webhook, you can retrieve the final result from EVO Cloud.
From your server, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/capture
and specify the parameter below.
| Parameter | Required | Description |
|---|---|---|
| merchantTransID | M | The merchantTransInfo.merchantTransID of the initial capture. |
Here is an example of retrieving the capture result:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/capture?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_CAPTURE} \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"Here is an example of the GET response. The POST response is similar to the GET response.
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethod": {
7. "card": {
8. "first6No": "476134",
9. "last4No": "0019",
10. "paymentBrand": "Visa",
11. "fundingType": "credit"
12. }
13. },
14. "payment": {
15. "status": "Captured",
16. "merchantTransInfo": {
17. "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
18. "merchantTransTime": "2021-12-31T08:30:59+08:00"
19. },
20. "evoTransInfo": {
21. "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",
22. "evoTransTime": "2021-12-31T00:30:59Z"
23. },
24. "pspTransInfo": {
25. "pspTransTime": "2021-12-31T08:30:59+08:00",
26. "authorizationCode": "091410",
27. "retrievalReferenceNum": "135616370503"
28. },
29. "transAmount": {
30. "currency": "USD",
31. "value": "10.00"
32. }
33. },
34. "capture": {
35. "status": "Success",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CAPTURE",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "d9e9022475f84ef09932becef13f7113",
42. "evoTransTime": "2021-12-31T08:35:59+08:00"
43. },
44. "pspTransInfo": {
45. "pspTransTime": "2021-12-31T08:35:59+08:00"
46. },
47. "transAmount": {
48. "currency": "USD",
49. "value": "10.00"
50. }
51. },
52. "pspData": {
53. "name": "Visa"
54. },
55. "metadata": "This is a metadata"
56.}Error handling
For HTTP POST request to EVO Cloud:It is suggested to wait at least 45 seconds after the request is sent to EVO Cloud. If you don’t get the response within the time frame, you need to retrieve the result from EVO Cloud. See Step 2 to initiate the request. For HTTP GET request to EVO Cloud: You can initiate the request several times until get the result, and it is suggested to wait at least 45 seconds before you initiate the next request. If you still fail to get the result after several times of the request, you can initiate another capture request instead.
