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.
paymentMethod	O	Payment method object.
paymentMethod.type	O	Must be card for this document's scenario.
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.

More details about the paymentMethod object:

1.paymentMethod.type: Set as card in your request.

2.paymentMethod.card.encryptedCardInfo: The encrypted card information. If you use EVO Cloud client-side solution to securely encrypt your user's card details, your frontend will get the value from EVO Cloud SDK, and you need to send it to your host, then your host needs to forward the original data to EVO Cloud.

3.paymentMethod.card.cardInfo: The raw data of the card information. If you collect and send raw card data to EVO Cloud, you need to specify the cardNumber, expiryDate, and cvc (optional),track2 and holderName in this object. For some of the UnionPay debit cards, the expiryDate is also optional. (If both paymentMethod.card.encryptedCardInfo and paymentMethod.card.cardInfo are present, paymentMethod.card.cardInfo will be applied.)

4.paymentMethod.cardfields

Field path	M/O	Condition	Description
paymentMethod.card	M	paymentMethod.type=card	Card-related transaction object.
paymentMethod.card.encryptedCardInfo	O	Approved encrypted-card integration	Encrypted card information.
paymentMethod.card.cardInfo	O	Approved card-information integration	Card information container.
paymentMethod.card.cardInfo.cardNumber	M	Manual/MOTO or final schema requirement	Card number. Never use a real value in examples or test fixtures.
paymentMethod.card.cardInfo.expiryDate	O	MOTO requirement	Expiration date in MMYY format.
paymentMethod.card.posEntryMode	O	POS card route	Card data input mode.
paymentMethod.card.pinFlag	O	Terminal supports PIN	true means the terminal can accept PIN; false means it cannot.
paymentMethod.card.termReadability	O	Terminal capability is provided	Terminal card-data input capability.
paymentMethod.card.icCardCondCode	O	UnionPay IC scenario	UnionPay card condition code.
paymentMethod.card.noSecretNoSignFlag	O	UnionPay scenario	UnionPay no-secret/no-sign indicator.
paymentMethod.card.cardInfo.track1	O	Magnetic or channel-specific requirement	Track 1 data. The final field name must follow the approved schema.
paymentMethod.card.cardInfo.track2	O	Magnetic, ICC, contactless, or fallback requirement	Track 2 data. Must not be stored or logged in plaintext.
paymentMethod.card.cardInfo.cardSequenceNum	O	ICC or contactless requirement	IC card sequence number.
paymentMethod.card.cardInfo.icCardData	O	ICC or contactless requirement	EMV/ICC TLV data.
paymentMethod.card.pin	O	PIN transaction	PIN container, if included in the final schema.
paymentMethod.card.pin.encryptedPin	M	PIN transaction	Encrypted PIN block. Never log or persist as plaintext.
paymentMethod.card.pin.pinEncryptMethod	M	PIN transaction	Approved PIN encryption method, for example 3DES, when supported.
paymentMethod.card.pin.checkValue	O	Key-version lookup is enabled	Value used to identify the applicable working-key version, when supported.

5.Card posEntryMode Modes

posEntryMode mode	Transaction activity	Typical conditional data
magnetic	Magnetic-stripe read	track2
ICC	Contact chip insertion	track2 、icCardData 、cardSequenceNum
contactless	NFC EMV tap	track2 、icCardData 、cardSequenceNum
contactless magnetic	Contactless transaction using a magnetic-stripe path	track2
fallback	EMV-to-magnetic fallback	track2
manual	Manual card entry	cardNumber 、expiryDate
MOTO	Mail order / telephone order	cardNumber 、expiryDate

The final API schema is the authority for exact field names, lengths, conditional requirements, and PSP-specific restrictions.

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:

1. cancel.status or refund.status: The status of the capture, required. The value can be Success, Failed, or Received. If you get a XXX.status with 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.

2. 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.