Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Undo a load transaction to a gift card

Reverse a transaction that loaded funds to a gift card.

With an undo request, you can reverse a gift card transaction that loaded funds to a gift card. The amount loaded is taken off the gift card balance. However, you can only undo the most recent load transaction and this transaction must be from the past 24 hours.

You identify the transaction you want to undo by its transaction identifier. Undoing transactions is a synchronous operation, but in an asynchronous cloud integration you receive the result asynchronously in a notification.

You can't use an undo request to cancel a gift card payment or to make a refund to a gift card.
See Cancel a payment and Make a refund to a gift card.

Before you begin

Before you make any gift card transactions, make sure that you have:

Undo a transaction

To undo the most recent load transaction made in the past 24 hours on 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
      • MessageClass: Service
      • MessageCategory: StoredValue
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt, consisting of 1-10 alphanumeric characters. 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.

    • StoredValueRequest: The request body for the reversal request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the request, in UTC format.
      • StoredValueData.StoredValueTransactionType: Reverse
      • StoredValueData.OriginalPOITransaction: The details of the transaction that you want to undo:

        • POITransactionID.TransactionID: Transaction identifier of the original transaction, in one of the following formats:

          Format Example
          tenderReference.pspReference A7sM001574852436000.8815748524464271

          Recommended format

          .pspReference .8815748524464271

          This works from terminal software version 1.44. Don't forget the leading dot (.).

          tenderReference A7sM001574852436000

          Only when using the same terminal as for the original transaction.

        • POITransactionID.TimeStamp: Date and time of the original transaction.

    For more information on the Terminal API request structure, refer to the Terminal API fundamentals.

    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "MessageType":"Request",
          "MessageClass":"Service",
          "MessageCategory":"StoredValue",
          "SaleID":"POSSystemID12345",
          "POIID":"V400m-324688179",
          "ProtocolVersion":"3.0",
          "ServiceID":"9265"
          },
        "StoredValueRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"44739",
              "TimeStamp":"2019-12-22T10:10:34+00:00"
              }
          },
          "StoredValueData": [
            {
              "StoredValueTransactionType": "Reverse",
              "OriginalPOITransaction": {
                "POITransactionID": {
                  "TransactionID": "A7sM001574852436000.8815748524464271",
                  "TimeStamp": "2019-12-22T09:01:15+00:00"
                }
              }
            }
          ]
        }
      }
    }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.SERVICE );
    messageHeader.setMessageCategory( MessageCategoryType.STORED_VALUE );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    saleToPOIRequest.setMessageHeader(messageHeader);
    
    StoredValueRequest storedValueRequest = new StoredValueRequest();
    SaleData saleData = new SaleData();
    TransactionIdentification saleTransactionID = new TransactionIdentification();
    saleTransactionID.setTransactionID(transactionID);
    saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    saleData.setSaleTransactionID(saleTransactionID);
    storedValueRequest.setSaleData(saleData);
    
    StoredValueData storedValueData = new StoredValueData();
    storedValueData.setStoredValueTransactionType( StoredValueTransactionType.REVERSE );
    OriginalPOITransaction originalPOITransaction = new OriginalPOITransaction();
    TransactionIdentification pOITransactionID = new TransactionIdentification();
    pOITransactionID.setTransactionID(transactionID);
    pOITransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
    originalPOITransaction.setPOITransactionID(pOITransactionID);
    storedValueData.setOriginalPOITransaction(originalPOITransaction);
    storedValueRequest.setStoredValueData(storedValueData);
    saleToPOIRequest.setStoredValueRequest(storedValueRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

The undo request is sent to the Adyen payments platform for processing.

Response

Once processed, your integration receives a result indicating the current state or balance of the gift card. 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 reversal is successful:

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

    • POIData.POITransactionID.TransactionID: Transaction identifier for the undo request.
    • StoredValueResult:

      • StoredValueTransactionType: Reverse
      • StoredValueAccountStatus: The CurrentBalance remaining on the card after undoing a load request.

    • Response.Result: Success
    • Response.AdditionalResponse: Additional transaction data. You'll receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object.

    For more information on the Terminal API response structure, refer to the Terminal API fundamentals.

    {
      "SaleToPOIResponse":{
        "StoredValueResponse":{
          "POIData":{
            "POITransactionID":{
              "TimeStamp":"2019-03-26T09:31:29.000Z",
              "TransactionID":"pZjO001522056689002.851577784437432H"
            }
          ...,
          "StoredValueResult":[
            {
              "StoredValueTransactionType":"Reverse",
              "StoredValueAccountStatus": {
                "CurrentBalance":265.79
              }
            }
          ],
          "Response":{
            "Result":"Success",
            "AdditionalResponse":"tid=46742566&transactionType=REFUND&backendGiftcardIndicator=false&posAmountGratuityValue=0&giftcardIndicator=true&pspReference=851577784437432H&storedValueApi=true&currentBalanceCurrency=USD&txtime=10%3a27%3a20&iso8601TxDate=2019-12-31T09%3a27%3a20.0000000%2b0000&posOriginalAmountValue=0&txdate=31-12-2019&merchantReference=17322&transactionReferenceNumber=851577784437432H&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&posAmountCashbackValue=0&posAuthAmountValue=0&currentBalanceValue=26579"
          }
        },
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "SaleID":"POSSystemID12345",
          "MessageClass":"Service",
          "MessageCategory":"StoredValue",
          "ServiceID":"9264",
          "POIID":"V400m-324688179",
          "MessageType":"Response"
        }
      }
    }

See also