If you want to return funds to a shopper's gift card, you can make a referenced refund or an unreferenced refund:
-
Referenced refund: A
ReversalRequest
with a reference to the original payment. Use this if you want to refund a payment made with this gift card. You can also make (multiple) partial refunds in this way. - Unreferenced refund: A
PaymentRequest
withPaymentType
Refund. Use this if you can't connect the refund to a payment made with the gift card but still want to return the funds to this gift card. For example, in a 'merchandise return' where the shopper returns an unwanted birthday gift. That's what we describe here on this page.
If you want to give the balance of a gift card to a shopper in cash, you should make a cashback request instead.
Before you begin
Before you make any gift card transactions, make sure that you have:
- Built an integration that can make a payment.
- Completed the onboarding process with your gift card provider.
- Added the payment method to your Adyen account.
Make an unreferenced refund
To issue a refund to a gift card:
- Determine the card entry method:
- If you want to scan the card, do that first and use the obtained card details in your request.
- If you want to swipe the card or use manual keyed entry (MKE), send the request first. The payment terminal will show a prompt to swipe the card or enter the card details.
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: This follows the standardMessageHeader
structure, explained in Terminal API fundamentals, which includes:ProtocolVersion
: 3.0MessageCategory
: PaymentMessageType
: RequestSaleID
: Your unique ID for the cash register.ServiceID
: Your unique ID for this transaction attempt. This needs to be unique within the last 48 hours.POIID
: Unique ID of the terminal. This indicates which terminal the transaction will be routed to.
-
PaymentRequest
: The body for the refund request must include:SaleData.SaleTransactionID.TransactionID
: Your unique reference for this refund request.SaleData.SaleTransactionID.TimeStamp
: Date and time of the payment request, in UTC format.SaleData.SaleReferenceID
: Your reference to the order that you want to do a refund for. In the Customer Area, it will appear as the Merchant Order for the transaction.PaymentTransaction.AmountsReq
: TheCurrency
andRequestedAmount
being refunded to the gift card.PaymentData.PaymentType
: RefundPaymentData.PaymentInstrumentData.PaymentInstrumentType
: StoredValue-
PaymentData.PaymentInstrumentData.StoredValueAccountID
: The gift card details:StoredValueAccountType
: GiftCardStoredValueProvider
: The gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.IdentificationType
: PAN-
EntryMode
,StoredValueID
andExpiryDate
: These parameters depend on the card entry method you are using.Card entry Parameters Scan EntryMode
: ScannedStoredValueID
: Gift card number.ExpiryDate
: Expiry date of the gift card.
Swipe EntryMode
: MagStripe
MKE EntryMode
: KeyedStoredValueID
: xxxxxxxxxxxxxxxxxxx.
The example below shows how you would issue a refund of 30.00 GBP to a scanned gift card.
For more information on the Terminal API request structure, refer to the Terminal API fundamentals.
{ "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"9268", "SaleID":"POSSystem", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44741", "TimeStamp":"2019-06-22T12:20:27+00:00" }, "SaleReferenceID":"YOUR_ORDER_REFERENCE" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"GBP", "RequestedAmount":30 } }, "PaymentData":{ "PaymentType":"Refund", "PaymentInstrumentData":{ "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006491260550218066", "ExpiryDate":"1122" } } } } } }
String serviceID = "YOUR_UNIQUE_ATTEMPT_ID"; String saleID = "YOUR_CASH_REGISTER_ID"; String POIID = "YOUR_TERMINAL_ID"; String transactionID = "YOUR_UNIQUE_TRANSACTION_ID"; SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest(); MessageHeader messageHeader = new MessageHeader(); messageHeader.setProtocolVersion("3.0"); messageHeader.setMessageClass( MessageClassType.SERVICE ); messageHeader.setMessageCategory( MessageCategoryType.PAYMENT ); messageHeader.setMessageType( MessageType.REQUEST ); messageHeader.setServiceID(serviceID); messageHeader.setSaleID(saleID); messageHeader.setPOIID(POIID); saleToPOIRequest.setMessageHeader(messageHeader); PaymentRequest paymentRequest = new PaymentRequest(); SaleData saleData = new SaleData(); TransactionIdentification saleTransactionID = new TransactionIdentification(); saleTransactionID.setTransactionID(transactionID); saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar())); saleData.setSaleTransactionID(saleTransactionID); saleData.setSaleReferenceID("YOUR_ORDER_REFERENCE"); paymentRequest.setSaleData(saleData); PaymentTransaction paymentTransaction = new PaymentTransaction(); AmountsReq amountsReq = new AmountsReq(); amountsReq.setCurrency("GBP"); amountsReq.setRequestedAmount( BigDecimal.valueOf(30) ); paymentTransaction.setAmountsReq(amountsReq); paymentRequest.setPaymentTransaction(paymentTransaction); PaymentData paymentData = new PaymentData(); paymentData.setPaymentType( PaymentType.REFUND ); PaymentInstrumentData paymentInstrumentData = new PaymentInstrumentData(); paymentInstrumentData.setPaymentInstrumentType( PaymentInstrumentType.STORED_VALUE ); StoredValueAccountID storedValueAccountID = new StoredValueAccountID(); storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD ); storedValueAccountID.setStoredValueProvider("svs"); storedValueAccountID.setIdentificationType( IdentificationType.PAN ); storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED ); storedValueAccountID.setStoredValueID("6006491260550218066"); storedValueAccountID.setExpiryDate("1122"); paymentInstrumentData.setStoredValueAccountID(storedValueAccountID); paymentData.setPaymentInstrumentData(paymentInstrumentData); paymentRequest.setPaymentData(paymentData); saleToPOIRequest.setPaymentRequest(paymentRequest); terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);
-
The refund request is sent to the Adyen payments platform for processing.
Refund response
Once processed, your integration receives the refund result. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.
If your integration uses asynchronous cloud communications, you receive the result in a TENDER_FINAL display notification.
If the refund request is successful:
-
You receive a response with a
PaymentResponse
object that includes:POIData.POITransactionID.TransactionID
: Transaction identifier for the refund.PaymentReceipt
: Object containing data you can use to generate a receipt.Response.Result
: Success
The example below indicates that the refund of 30.00 GBP was successfully issued to the gift card.
For more information on the Terminal API response structure, refer to the Terminal API fundamentals.
{ "SaleToPOIResponse":{ "PaymentResponse":{ "POIData":{ "POITransactionID":{ "TimeStamp":"2019-06-22T12:20:31.000Z", "TransactionID":"u6W7001529670031000.9815296700362966" } }, "SaleData":{ "SaleTransactionID":{ "TimeStamp":"2019-06-22T12:20:27.000Z", "TransactionID":"44741" }, "SaleReferenceID":"SalesRefABC" }, "PaymentReceipt":[...], "PaymentResult":{ "PaymentAcquirerData":{ "AcquirerPOIID":"V400m-324688179", "AcquirerTransactionID":{ "TimeStamp":"2019-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.00, "Currency":"GBP" }, "PaymentType":"Refund" }, "Response":{ "Result":"Success", "AdditionalResponse":"..." } }, "MessageHeader":{ "ProtocolVersion":"3.0", "SaleID":"POSSystem", "MessageClass":"Service", "MessageCategory":"Payment", "ServiceID":"9268", "POIID":"V400m-324688179", "MessageType":"Response" } } }