Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Make a refund to a gift card

Make an in-store unreferenced refund to a gift card.

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 with PaymentType 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:

Make an unreferenced refund

To issue a refund to a gift card:

  1. 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.
  2. Make a POST request to a Terminal API endpoint, specifying:

    • PaymentRequest.SaleData. This includes:

      Parameter Required Description
      SaleTransactionID.TransactionID -white_check_mark- Your reference to identify this refund.
      SaleTransactionID.TimeStamp -white_check_mark- Date and time of the request, in UTC format.
      SaleReferenceID -white_check_mark- 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.
      SaleToAcquirerData
      • Optional for manually keying in the card number (MKE): maxLength and cardMask. Use these fields to specify card numbers with more than 24 digits.
      • Optional for Stored Value Solutions (SVS) gift cards: ssc. This is the secondary security code of the gift card, and allows up to 8 digits. For example, ssc: 1111.
        To add these, follow the instructions below.


      In SaleData.SaleToAcquirerData, specify the parameter in one of the following formats:

      • Option 1: a JSON object converted to a Base64 encoded string.
        Encode {"maxLength": "27", "cardMask": "****-****-****-****-****-****-***"} to Base64, and pass the resulting string:
        "SaleToAcquirerData": "eyJtYXhMZW5ndGgiOiAiMjciLCAiY2FyZE1hc2siOiAiKioqKi0qKioqLSoqKiotKioqKi0qKioqLSoqKiotKioqIn0="

      • Option 2: a key-value pair:
        "SaleToAcquirerData": "maxLength=27&cardMask=****-****-****-****-****-****-***"

      The format that you use here will also be the format of the AdditionalResponse that you receive. If there are more tender options (for example, ReceiptHandler ) or other data elements that you need to pass in the SaleToAcquirerData field, refer to Add information to a payment.

    • PaymentRequest.PaymentTransaction. This includes:

      Parameter Required Description
      AmountsReq -white_check_mark- The Currency and RequestedAmount being refunded to the gift card.
    • PaymentRequest.PaymentData. This includes:

      Parameter Required Description
      PaymentType -white_check_mark- Refund
      PaymentInstrumentData.PaymentInstrumentType -white_check_mark- StoredValue
      PaymentInstrumentData.StoredValueAccountID -white_check_mark- The gift card details:
      • StoredValueAccountType: GiftCard
      • StoredValueProvider: the gift card issuer: givex, svs, valuelink, or any Intersolve-supported card type.
      • IdentificationType: PAN.
      • EntryMode, StoredValueID and ExpiryDate: these parameters depend on the card entry method you are using. See the following table.
      Card entry Parameters
      Scan
      • EntryMode: Scanned
      • StoredValueID: gift card number.
      • ExpiryDate: expiry date of the gift card.
      Swipe
      • EntryMode: MagStripe
      • StoredValueID: include this parameter but don't provide a value.
      MKE
      • EntryMode: Keyed
      • StoredValueID: include this parameter but don't provide a value.

    The example below shows how you would issue a refund of 30.00 GBP to a scanned gift card.

    {
        "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 response as an event notification.

If the refund request is successful:

  • You receive a response with a PaymentResponse object that includes:

    The example below indicates that the refund of 30.00 GBP was successfully issued to the gift card.

    {
        "SaleToPOIResponse":{
            "PaymentResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-06-22T12:20:31.000Z",
                        "TransactionID":"u6W7001529670031000.NC6HT9CRT65ZGN82"
                    }
                },
                "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":"NC6HT9CRT65ZGN82"
                        },
                        "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"
            }
        }
    }

Next steps

See also