1. After Payment
Merchant Connect API
latest
  • latest
  • HASE
  • Version Record
  • Integration Guide
    • EC Payment
      • Merchant API
        • Overview
        • Payment
        • Payment Methods
        • Response code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
        • Features
          • Account Status Inquiry (ASI)
          • COF
          • Multi-Currency Transaction
          • Recurring
          • Smart Routing
          • Transaction Retry
          • Payout
          • Authentication
            • 3D Secure
            • FIDO Authentication
            • Authentication only
            • Authorization only
          • Tokenization
            • Gateway Tokenization
            • Create a gateway token
            • Network Tokenization
            • Pay with gateway token
            • Manage token
            • Network Token update notification
            • Card Based Network Token
    • In-store Payment
      • Merchant API（QR）
        • Payment
          • CPM
          • MPM
          • MPM static QR code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
      • Merchant API (Card)
        • ZPK
          • ZPK
        • Payment
          • Payment
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
  • API Explorer
    • API Rules
    • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
    • FXRateInquiry
      • FXRateInquiry
      • FXRateInquiry
    • Payment
      • Payment
      • Payment
      • Payment
    • Payout
      • Payout
      • Payout
    • Capture
      • Capture
      • Capture
    • Cancel
      • Cancel
      • Cancel
    • Refund
      • Refund
      • Refund
    • Cryptogram
      • Cryptogram
      • Cryptogram
    • Cancel or Refund
      • Cancel or Refund
      • Cancel or Refund
    • Notification
      • Notification for PaymentMethod
      • Notification for Payment
      • Notification for Capture
      • Notification for Cancel
      • Notification for Refund
      • Notification for DataSubmission
      • Notification for MPM Static QR Code
      • Notification for Token Status Update
      • Notification for Settlement
      • Notification for Reversal
      • Notification for Cryptogram
      • Notification for Payout
    • Appendix
      • Result Code
      • Payment Brands
      • Payment Method Variant
      • Currency list
      • Country and region list
      • Product Code
    • HealthCheck
      • HealthCheck
    • Coupon Write-off
      • Coupon Write-off
    • Coupon Reversal
      • Coupon Reversal
    • ZPK
      • ZPK
latest
  • latest
  • HASE
  1. After Payment

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 ParameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the initial payment.
Body ParameterRequiredDescription
merchantTransInfoMThe reference for the refund, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request.
transAmountMThe currency and value of the refund payment. The value must follow the currency's minor unit.
initiatingReasonOYou can state the reason for this request in this field.
webhookOThe URL to receive notification. Specify this to get the notification from EVO Cloud after the payment succeeds.
paymentMethodOPayment method object.
paymentMethod.typeOMust be card for this document's scenario.
metadataOA 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 pathM/OConditionDescription
paymentMethod.cardMpaymentMethod.type=cardCard-related transaction object.
paymentMethod.card.encryptedCardInfoOApproved encrypted-card integrationEncrypted card information.
paymentMethod.card.cardInfoOApproved card-information integrationCard information container.
paymentMethod.card.cardInfo.cardNumberMManual/MOTO or final schema requirementCard number. Never use a real value in examples or test fixtures.
paymentMethod.card.cardInfo.expiryDateOMOTO requirementExpiration date in MMYY format.
paymentMethod.card.posEntryModeOPOS card routeCard data input mode.
paymentMethod.card.pinFlagOTerminal supports PINtrue means the terminal can accept PIN; false means it cannot.
paymentMethod.card.termReadabilityOTerminal capability is providedTerminal card-data input capability.
paymentMethod.card.icCardCondCodeOUnionPay IC scenarioUnionPay card condition code.
paymentMethod.card.noSecretNoSignFlagOUnionPay scenarioUnionPay no-secret/no-sign indicator.
paymentMethod.card.cardInfo.track1OMagnetic or channel-specific requirementTrack 1 data. The final field name must follow the approved schema.
paymentMethod.card.cardInfo.track2OMagnetic, ICC, contactless, or fallback requirementTrack 2 data. Must not be stored or logged in plaintext.
paymentMethod.card.cardInfo.cardSequenceNumOICC or contactless requirementIC card sequence number.
paymentMethod.card.cardInfo.icCardDataOICC or contactless requirementEMV/ICC TLV data.
paymentMethod.card.pinOPIN transactionPIN container, if included in the final schema.
paymentMethod.card.pin.encryptedPinMPIN transactionEncrypted PIN block. Never log or persist as plaintext.
paymentMethod.card.pin.pinEncryptMethodMPIN transactionApproved PIN encryption method, for example 3DES, when supported.
paymentMethod.card.pin.checkValueOKey-version lookup is enabledValue used to identify the applicable working-key version, when supported.
5.Card posEntryMode Modes
posEntryMode modeTransaction activityTypical conditional data
magneticMagnetic-stripe readtrack2
ICCContact chip insertiontrack2 、icCardData 、cardSequenceNum
contactlessNFC EMV taptrack2 、icCardData 、cardSequenceNum
contactless magneticContactless transaction using a magnetic-stripe pathtrack2
fallbackEMV-to-magnetic fallbacktrack2
manualManual card entrycardNumber 、expiryDate
MOTOMail order / telephone ordercardNumber 、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:
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:
1.
refund.status: The status of this refund, required. The value can be Success, Failed, or Received. If you get a refund.status with Received, 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.
2.
refund.transAmount: The currency and value of the refund, required. It is echoed back from your request.
3.
refund.merchantTransInfo: The object that is a reference for the refund, generated by your host, required. It is echoed back from your request.
4.
refund.evoTransInfo: The object that is a reference for the refund, generated by EVO Cloud, required. It contains evoTransID, evoTransTime, and traceNum (optional) and retrievalReferenceNum for some PSPs such as Visa or Mastercard.
5.
refund.pspTransInfo: The object that is a reference for the refund, generated by PSP, optional. It contains pspTransID, pspTransTime, and authorizationCode. EVO Cloud forwards this information from PSP to your host if PSP returns.
6.
refund.billingAmount and refund.billingFXRate: The user's billing currency and value of the capture, and the FX rate between refund.transAmount.currency and refund.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.
7.
refund.convertTransAmount and refund.convertTransFXRate: The currency and value calculated by EVO Cloud based on transAmount and the FX rate from transAmount.currency to a different currency when the transaction is sent out to PSP, and the FX rate between refund.transAmount.currency and refund.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:

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 ParameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the initial refund.
The following example shows how you retrieve the refund result:
Here is an example of the GET response. The POST response is similar to the GET response.

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.
Previous
Cancel
Next
Cancel or Refund
Built with