Search

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 a point of sale unreferenced refund to a gift card.

If you want to return funds to a shopper's gift card, you can make a reversal request or a refund request:

  • Reversal: If you want to refund a payment made with the gift card, you should make a reversal request referencing the original payment. That is what we call a 'referenced refund', and it's described under Refund a payment. You can also make (multiple) partial refunds using reversal requests.

  • Refund: If you can't link the refund to a payment made with the gift card, for example in case of a 'merchandise return' when the shopper returns an unwanted gift, you should make a refund request. That's what we describe here on this page.

When the request has been processed, you receive a result indicating whether the refund was successful.

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:

Step 1: Make refund request

To issue a refund to a gift card:

  • Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageCategory: Payment
      • MessageType: Request
      • SaleID: 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: The Currency and RequestedAmount being refunded to the gift card.
      • PaymentData.PaymentType: Refund
      • PaymentData.PaymentInstrumentData.PaymentInstrumentType: StoredValue
      • PaymentData.PaymentInstrumentData.StoredValueAccountID: The gift card details:

        • StoredValueAccountType: GiftCard
        • ExpiryDate: The gift card expiry date.
        • EntryMode: MagStripe or Scanned
        • StoredValueProvider: The gift card issuer: givex, svs, or valuelink
        • IdentificationType: PAN or BarCode
        • StoredValueID: The gift card number.

    The example below shows how you would issue a refund of 30.00 GBP to a gift card with the number 6006491260550218066.

    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",
                      "EntryMode":[
                         "MagStripe"
                      ],
                      "StoredValueProvider":"givex",
                      "StoredValueID":"6006491260550218066",
                      "IdentificationType":"PAN",
                      "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("GN{");
    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.getEntryMode().add( EntryModeType.MAGSTRIPE );
    storedValueAccountID.setStoredValueProvider("givex");
    storedValueAccountID.setStoredValueID("6006491260550218066");
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.setExpiryDate("1117");
    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.

Step 2: Receive refund result

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 that contains a PaymentResponse object. This includes:

    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"
            }
        }
    }

Next steps