Refund

Outlines how to make a refund to a gift card using the Terminal API.


Refund a balance to a customers gift card by making a payment request with the PaymentType set to Refund

Endpoint

The URL used to send  Terminal API  messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview .

Refund request

For a list of Payment Request fields, see PaymentRequest fields.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

{
   "SaleToPOIRequest":{
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "ServiceID":"0622142027",
         "SaleID":"POSSystem",
         "POIID":"P400Plus-540004072"
      },
      "PaymentRequest":{
         "SaleData":{
            "SaleTransactionID":{
               "TransactionID":"31039",
               "TimeStamp":"2018-06-22T12:20:27+00:00"
            },
            "SaleReferenceID":"SalesRefABC"
         },
         "PaymentTransaction":{
            "AmountsReq":{
               "Currency":"CAD",
               "RequestedAmount":30
            }
         },
         "PaymentData":{
            "PaymentType":"Refund",
            "PaymentInstrumentData":{
               "PaymentInstrumentType":"StoredValue",
               "StoredValueAccountID":{
                  "StoredValueAccountType":"GiftCard",
                  "EntryMode":[
                     "MagStripe"
                  ],
                  "StoredValueProvider":"givex",
                  "StoredValueID":"6006491260550218066",
                  "IdentificationType":"PAN",
                  "ExpiryDate":"1117"
               }
            }
         }
      }
   }
}

Response

For a list of Payment Response fields, see  PaymentResponse fields.
The transactionType as refund and the updated current balance on the card ( currentBalanceValue) are listed in the additionalResponse

 {
   "SaleToPOIResponse":{
      "PaymentResponse":{
         "POIData":{
            "POITransactionID":{
               "TimeStamp":"2018-06-22T12:20:31.000Z",
               "TransactionID":"u6W7001529670031000.9815296700362966"
            }
         },
         "SaleData":{
            "SaleTransactionID":{
               "TimeStamp":"2018-06-22T12:20:27.000Z",
               "TransactionID":"31039"
            },
            "SaleReferenceID":"SalesRefABC"
         },
         "PaymentReceipt":[
            {
               "RequiredSignatureFlag":false,
               "DocumentQualifier":"CashierReceipt",
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=Adyen&key=header1",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=www.adyen.com&key=header2",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=MERCHANT%20COPY&key=merchantTitle",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Date&value=22%2f06%2f18&key=txdate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Time&value=12%3a20%3a31&key=txtime",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a5498&key=pan",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Pref.%20name&key=preferredName",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card%20type&value=givex&key=cardType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20method&value=givex&key=paymentMethod",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20variant&value=givex&key=paymentMethodVariant",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Entry%20mode&value=MSR&key=posEntryMode",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=MID&key=mid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=TID&value=P400Plus-540004072&key=tid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=PTID&value=87253103&key=ptid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=ATC&key=atc",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Tender&value=u6W7001529670031000&key=txRef",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Reference&value=31039&key=mref",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Type&value=REFUND&key=txtype",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=TOTAL&value=CAD%2030.00%20%20&key=totalAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=APPROVED&key=approved",
                        "EndOfLineFlag":true
                     }
                  ]
               }
            },
            {
               "RequiredSignatureFlag":false,
               "DocumentQualifier":"CustomerReceipt",
               "OutputContent":{
                  "OutputFormat":"Text",
                  "OutputText":[
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=Adyen&key=header1",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=www.adyen.com&key=header2",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=CARDHOLDER%20COPY&key=cardholderHeader",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Date&value=22%2f06%2f18&key=txdate",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Time&value=12%3a20%3a31&key=txtime",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card&value=%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a%2a5498&key=pan",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Pref.%20name&key=preferredName",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Card%20type&value=givex&key=cardType",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20method&value=givex&key=paymentMethod",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Payment%20variant&value=givex&key=paymentMethodVariant",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Entry%20mode&value=MSR&key=posEntryMode",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=MID&key=mid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=TID&value=P400Plus-540004072&key=tid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=PTID&value=87253103&key=ptid",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=ATC&key=atc",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Tender&value=u6W7001529670031000&key=txRef",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Reference&value=31039&key=mref",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Type&value=REFUND&key=txtype",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=TOTAL&value=CAD%2030.00%20%20&key=totalAmount",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "CharacterStyle":"Bold",
                        "Text":"name=APPROVED&key=approved",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"key=filler",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Please%20retain%20for%20your%20records&key=retain",
                        "EndOfLineFlag":true
                     },
                     {
                        "Text":"name=Thank%20you&key=thanks",
                        "EndOfLineFlag":true
                     }
                  ]
               }
            }
         ],
         "PaymentResult":{
            "PaymentAcquirerData":{
               "AcquirerPOIID":"P400Plus-540004072",
               "AcquirerTransactionID":{
                  "TimeStamp":"2018-06-22T12:20:31.000Z",
                  "TransactionID":"9815296700362966"
               },
               "MerchantID":"TestMerchantPOS"
            },
            "PaymentInstrumentData":{
               "StoredValueAccountID":{
                  "IdentificationType":"PAN",
                  "EntryMode":[
                     "MagStripe"
                  ],
                  "StoredValueID":"603628173862001915498",
                  "StoredValueAccountType":"GiftCard",
                  "StoredValueProvider":"givex",
                  "ExpiryDate":"1249"
               },
               "PaymentInstrumentType":"StoredValue"
            },
            "AmountsResp":{
               "AuthorizedAmount":30,
               "Currency":"CAD"
            },
            "PaymentType":"Refund"
         },
         "Response":{
            "Result":"Success",
            "AdditionalResponse":"tid=87253103&transactionType=REFUND&pspReference=9815296700362966&currentBalanceCurrency=CAD&offline=false&giftcardTrack2=603628173862001915498&note=Direct%20API%20REQUIRES%20payload%20crypto%20on%20live%2c%20cleartext%20allowed%20for%20testing%20only&giftcardPAN=603628173862001915498&currentBalanceValue=9000"
         }
      },
      "MessageHeader":{
         "ProtocolVersion":"3.0",
         "SaleID":"POSSystem",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "ServiceID":"0622142027",
         "POIID":"P400Plus-540004072",
         "MessageType":"Response"
      }
   }
}

The POITransactionID returned by the Terminal API consists of a PSP reference and a Tender reference. The format of the TransactionID is: < tenderref>.<pspref>, for example, oLkO001503399575001.9815033996072250.

If a PSP reference has not yet been generated, the TransactionID will only consist of a tender reference. This could occur if the transaction was completed offline.