Cancel
It is applicable to both EC and In-Store Scenario.
If you have authorized a payment but do not wish to capture it (e.g., due to goods being out of stock or a system timeout error), you need to cancel the payment.
- Applicable Payment Methods: You can only cancel the payment with methods that support separate authorization and capture, and this must be done before the payment is captured.
- Timing: It is recommended to send the cancel request within 7 days after authorization, as most issuers will expire the authorization after this period.
- Cancel Amount: The cancel amount is always the same as the initial payment amount, so you do not need to specify an amount parameter in your cancel request.
Make cancel request
Step 1: Make a cancel request
When you get a payment result with the payment.status with Authorised, Pending or Verifying, or if the payment is timeout, you can make an HTTP POST request from your server to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/cancel
to cancel the payment,
and specify the parameters below.
| Parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial payment. |
| Parameter | Required | Description |
|---|---|---|
merchantTransInfo | M | A reference for the cancellation, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
initiatingReason | O | Optional reason for this request. |
webhook | O | The URL to receive notifications. Specify this to get notifications from EVO Cloud after the payment succeeds. |
metadata | O | Self-defined reference information that will be echoed back in the response. The metadata in notifications matches the request metadata. |
Here is an example of a cancel request:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/cancel?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_TRANS_ID_OF_INITIAL_CANCEL",
10. "merchantTransTime": "2021-12-31T08:35:59+08:00"
11. },
12. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
13. "initiatingReason": "Customer cancels order",
14. "metadata": "This is a metadata"
15.}'If the request is successful, the response will include a cancel object and a payment object, providing the status and related information for both the cancel and the original payment.
cancel.status: The status of this cancel, required. The value can beSuccess,Failed, orReceived. If you get acancel.statuswithReceived, you need to either make another HTTP GET request to get the final status of this cancel (see Step 2 for more details), or wait for the notification webhook from EVO Cloud.cancel.merchantTransInfo: The object that is a reference for the cancel, generated by your host, required. It is echoed back from your request.cancel.evoTransInfo: The object that is a reference for the cancel, generated by EVO Cloud, required. It containsevoTransIDandevoTransTime.cancel.pspTransInfo: The object that is a reference for the cancel, generated by PSP, optional. It containspspTransIDandpspTransTime. EVO Cloud forwards this information from PSP to your host if PSP returns.
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": "Cancelling",
16. "merchantTransInfo": {
17. "merchantTransID": "37693fac0946498f8afe35b9ffdcfe89",
18. "merchantTransTime": "2021-12-31T08:30:59+08:00"
19. },
20. "evoTransInfo": {
21. "evoTransID": "ecf19b3be090407b97d74884077f08a4",
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. "cancel": {
35. "status": "Received",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CANCEL",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "a36a6c5c6b224eaf923ca2c93ff3e63a",
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 cancel result
If you get a cancel.status with Received and you don't use the notification webhook, you can retrieve the final result from EVO Cloud.
From your server, make an HTTP GET request to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/cancel
and specify the parameter below.
| Parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial cancellation. |
Here is an example of retrieving the cancel result:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/cancel?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_CANCEL} \
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"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": "Cancelled",
16. "merchantTransInfo": {
17. "merchantTransID": "37693fac0946498f8afe35b9ffdcfe89",
18. "merchantTransTime": "2021-12-31T08:30:59+08:00"
19. },
20. "evoTransInfo": {
21. "evoTransID": "ecf19b3be090407b97d74884077f08a4",
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. "cancel": {
35. "status": "Success",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_CANCEL",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "a36a6c5c6b224eaf923ca2c93ff3e63a",
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.}Make a refund instead
If you initiate a cancel request and get the B0012 result.code, double check the original transaction status in payment.status in the response. If it is Captured, it means the payment has already been captured thus you fail to cancel the payment. In this case, you need to initiate a refund instead. See chapter Refund for more details.
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 cancel request instead.
