Refund
It is applicable to both EC and In-Store Scenario.
If you want to return the funds to your user, for example, if the user returns an item, you need to refund the payment.
You can only refund a payment after it has already been captured. Payment not captured yet has to be cancelled instead. See chapter Cancel for more details.
You can refund either the full captured amount or a part of the captured amount. You can also perform multiple refunds partially, if the summary doesn't exceed the captured amount.
The maximum refund time frame is 365 days from when the payment is completed.
Make a refund request
Step 1: Make a refund request
When you get a capture result with payment.status with Captured, you can make an HTTP POST request from your server to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/refund
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 | M | 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. |
paymentMethod | O | Payment method object. |
paymentMethod.type | O | Must be card for this document's scenario. |
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.
Here is an example of making a 10 USD refund:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/refund?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_REFUND",
10. "merchantTransTime": "2021-12-31T08:35:59+08:00"
11. },
12. "transAmount": {
13. "currency": "USD",
14. "value": "10.00"
15. },
16. "paymentMethod": {
17. "type": "card",
18. "card": {
19. "posEntryMode": "ICC",
20. "pinFlag": true,
21. "cardInfo": {
22. "cardNumber": "6222021234567890123",
23. "track2": "6222021234567890123=26122011234567890123",
24. "icCardData": "9F02069F03069F1A029F26089F27019F36029F37049F1008",
25. "cardSequenceNum": "001"
26. },
27. "pin": {
28. "encryptedPin": "base64encodedPinBlock==",
29. "pinEncryptMethod": "3DES",
30. "checkValue": "A1B2C3"
31. }
32. }
33. },
34. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
35. "initiatingReason": "Goods returned by customers",
36. "metadata": "This is a metadata" ,
37. "transInitiator": {
38. "platform": "POS",
39. "terminalID": "30100101",
40. "paymentScenario": "inStore"
41. }
42.}'If the request is successful, you will receive the response with a refund object and a payment object to show the status and related information for the refund and the original payment.
More details about refund object:
refund.status: The status of this refund, required. The value can beSuccess,Failed, orReceived. If you get arefund.statuswithReceived, you need to either make another HTTP GET request to get the final status of this refund (see Step 2 for more details), or wait for the notification webhook from EVO Cloud.refund.transAmount: The currency and value of the refund, required. It is echoed back from your request.refund.merchantTransInfo: The object that is a reference for the refund, generated by your host, required. It is echoed back from your request.refund.evoTransInfo: The object that is a reference for the refund, generated by EVO Cloud, required. It containsevoTransID,evoTransTime, andtraceNum(optional) andretrievalReferenceNumfor some PSPs such as Visa or Mastercard.refund.pspTransInfo: The object that is a reference for the refund, generated by PSP, optional. It containspspTransID,pspTransTime, andauthorizationCode. EVO Cloud forwards this information from PSP to your host if PSP returns.refund.billingAmountandrefund.billingFXRate: The user's billing currency and value of the capture, and the FX rate betweenrefund.transAmount.currencyandrefund.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.refund.convertTransAmountandrefund.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 betweenrefund.transAmount.currencyandrefund.convertTransAmount.currency, optional. The FX rate will be provided if you enable 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": "Refunding",
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. "refund": {
35. "status": "Received",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_REFUND",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "2cf248d44a0f4ed5991fa4f77879d71e",
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"
}Step 2: Retrieve the refund result
If you get a refund.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}/refund
| Query Parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial refund. |
The following example shows how you retrieve the refund result:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/refund?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_REFUND} \
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": "Refunded",
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. "refund": {
35. "status": "Success",
36. "merchantTransInfo": {
37. "merchantTransID": "YOUR_TRANS_ID_OF_INITIAL_REFUND",
38. "merchantTransTime": "2021-12-31T08:35:59+08:00"
39. },
40. "evoTransInfo": {
41. "evoTransID": "2cf248d44a0f4ed5991fa4f77879d71e",
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 cancel instead
If you initiate a refund request and get the B0012 result.code, double check the original transaction status in payment.status in the response message. If it is authorised, it means the payment has NOT been captured yet thus you fail to refund the payment. In this case, you need to initiate a cancel instead. See chapter Cancel 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.
