Cancel or Refund
It is applicable to both EC and In-Store Scenario.
Merchant can use this interface to close or return the amount of the transaction, whatever the original transaction status. EVO Cloud will judge the transaction status and automatically initiate a cancellation or refund.
Make a cancel or refund request
Step 1: Make a cancel or refund request
When you get a payment result with payment.status
with Captured
or Authorised
, you can make an HTTP POST request from your server to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/cancelOrRefund
to refund the initial payment and specify the parameters below.
Query Parameter | Required | Description |
---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial payment. |
Body Parameter | Required | Description |
---|---|---|
merchantTransInfo | M | The reference for the refund, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
transAmount | O | The currency and value of the refund 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 and will be echoed back in the response. |
If the request is successful, the response will include a cancel or refund object and a payment object, providing the status and related information for the original payment.
Detail information about cancel or refund object:
cancel.status
orrefund.status
: The status of the capture, required. The value can beSuccess
,Failed
, orReceived
. If you get aXXX.status
withReceived
, 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.cancelOrRefund
: Used to indicate the transaction has been refunded or canceled.
Step 2: Retrieve the cancel or refund result
If you get a refund.status
or 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}/cancelOrRefund
and specify the parameter below.
Query Parameter | Required | Description |
---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial cancel or refund. |
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 cancelOrRefund request instead.