Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Deactivate or cash out

Disable or cash out a gift card at the point of sale.

When the balance of a gift card has gone below a certain amount or when you suspect fraud, you may want to stop further use of the card. You can:

  • Make a cashback request to take funds off the gift card and give this back to the shopper as cash. If you cash out the full remaining balance, the card is no longer active and cannot be used again.
  • Make a deactivation request to disable the card without cashing it out. You can only do this for gift cards provided by Givex.

Before you begin

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

Cashing back a gift card

Your options with a cashback request depend on the gift card provider, the scheme rules, and the applicable law. If cashbacks are allowed, you can normally only cash out the full amount remaining on the card. But if the gift card was provided by Givex, it is possible in some cases to give a cashback for a partial amount.

The funds taken off the gift card can be given back to the shopper in cash, or transferred to their credit or debit card by making an unreferenced refund.

Step 1: Make cashback request

To give cashback from a gift card:

  1. Check the balance remaining on the gift card.
  2. 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 request body for the cashback request must include:

      • SaleData.SaleTransactionID.TimeStamp: Date and time of the cashback request, in UTC format.
      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this cashback request.
      • SaleData.SaleReferenceID: Optional parameter to provide your order number. You can use this to connect different gift card transactions to the same order. In the Customer Area, it will appear as the Merchant Order for the transaction.
      • SaleData.SaleToAcquirerData: redemptionType=cashback
      • PaymentTransaction.AmountsReq: The Currency and RequestedAmount being given back to the shopper. To cash out the full amount, you can either specify that exact amount, or specify a zero (0) amount.
      • PaymentData.PaymentType: Normal
      • PaymentData.PaymentInstrumentData.PaymentInstrumentType: StoredValue
      • PaymentData.PaymentInstrumentData.StoredValueAccountID: The gift card details:

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

    The example below shows how you would initiate a 4.50 GBP cashback request for the card with the ID 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": "9269",
          "SaleID": "POSTerminal",
          "POIID": "V400m-324688179"
        },
        "PaymentRequest": {
          "SaleData": {
            "SaleTransactionID": {
              "TransactionID": "44750",
              "TimeStamp": "2019-06-22T12:55:20+00:00"
            },
            "SaleReferenceID": "YOUR_ORDER_REFERENCE",
            "SaleToAcquirerData": "redemptionType=cashback"
          },
          "PaymentTransaction": {
            "AmountsReq": {
              "Currency": "GBP",
              "RequestedAmount": 4.50
            }
          },
          "PaymentData": {
            "PaymentType": "Normal",
            "PaymentInstrumentData": {
              "PaymentInstrumentType": "StoredValue",
              "StoredValueAccountID": {
                "StoredValueAccountType": "GiftCard",
                "EntryMode": [
                  "MagStripe"
                ],
                "StoredValueProvider": "svs",
                "StoredValueID": "9826150911219687",
                "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");
    saleData.setSaleToAcquirerData("redemptionType=cashback");
    paymentRequest.setSaleData(saleData);
    
    PaymentTransaction paymentTransaction = new PaymentTransaction();
    AmountsReq amountsReq = new AmountsReq();
    amountsReq.setCurrency("GBP");
    amountsReq.setRequestedAmount( BigDecimal.valueOf(4.50) );
    paymentTransaction.setAmountsReq(amountsReq);
    paymentRequest.setPaymentTransaction(paymentTransaction);
    
    PaymentData paymentData = new PaymentData();
    paymentData.setPaymentType( PaymentType.NORMAL );
    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("svs");
    storedValueAccountID.setStoredValueID("9826150911219687");
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.setExpiryDate("1122");
    paymentInstrumentData.setStoredValueAccountID(storedValueAccountID);
    paymentData.setPaymentInstrumentData(paymentInstrumentData);
    paymentRequest.setPaymentData(paymentData);
    saleToPOIRequest.setPaymentRequest(paymentRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

The cashback request is sent to the Adyen payments platform for processing. Once processed, your integration receives the cashback result.

Step 2: Receive cashback result

Once processed, your integration receives a response containing the result of the requesd. 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 cashback request is successful:

  • You receive a response that contains a PaymentResponse object. This includes:

    The example below indicates that the cashback request was successful, and 4.50 GBP was removed from the balance of 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:55:24.000Z",
                        "TransactionID":"u6W7001529672124004.9815296721273135"
                    }
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2019-06-22T12:55:20.000Z",
                        "TransactionID":"44742"
                    },
                    "SaleReferenceID":"YOUR_ORDER_REFERENCE"
                },
                "PaymentReceipt":[...],
                "PaymentResult":{
                    "PaymentAcquirerData":{
                        "AcquirerPOIID":"V400m-324688179",
                        "AcquirerTransactionID":{
                            "TimeStamp":"2019-06-22T12:55:24.000Z",
                            "TransactionID":"44750"
                        },
                        "MerchantID":"TestMerchantPOS"
                    },
                    "PaymentInstrumentData":{
                        "StoredValueAccountID":{
                            "IdentificationType":"PAN",
                            "EntryMode":[
                                "MagStripe"
                            ],
                            "StoredValueID":"9826150911219687",
                            "StoredValueAccountType":"GiftCard",
                            "StoredValueProvider":"svs",
                            "ExpiryDate":"1122"
                        },
                        "PaymentInstrumentType":"StoredValue"
                    },
                    "AmountsResp":{
                        "AuthorizedAmount":4.50,
                        "Currency":"GBP"
                    },
                    "PaymentType":"Normal"
                },
                "Response":{
                    "Result":"Success",
                    "AdditionalResponse":"..."
                }
            },
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "SaleID":"POSTerminal",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "ServiceID":"9269",
                "POIID":"V400m-324688179",
                "MessageType":"Response"
            }
        }
    }

You store staff can hand the funds that were deducted from the card to the shopper as cash.

Deactivate gift card

If the gift card was issued by Givex, you can make a deactivation request to disable the card.

Step 1: Make deactivation request

To deactivate 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: StoredValue
      • 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.
    • StoredValueRequest: The request body for the deactivation request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this deactivation request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the deactivation request, in UTC format.
      • StoredValueData.StoredValueTransactionType: Unload
      • StoredValueData.StoredValue.StoredValueAccountID: The gift card details:

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

        • ItemCount: 0
        • Currency: Currency of the gift card.

    The example below shows how you would request the deactivation of the card with the ID 6006491260550218157.

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

    {
      "SaleToPOIRequest": {
        "MessageHeader": {
          "ProtocolVersion": "3.0",
          "MessageClass": "Service",
          "MessageCategory": "StoredValue",
          "MessageType": "Request",
          "ServiceID": "9270",
          "SaleID": "POSSystemID12345",
          "POIID": "P400Plus-275008713"
        },
        "StoredValueRequest": {
          "SaleData": {
            "SaleTransactionID": {
              "TransactionID": "44743",
              "TimeStamp": "2019-05-17T14:13:03+00:00"
            }
          },
          "StoredValueData": [
            {
              "StoredValueTransactionType": "Unload",
              "StoredValueAccountID": {
                "StoredValueAccountType": "GiftCard",
                "StoredValueProvider": "givex",
                "ExpiryDate": "1122",
                "StoredValueID": "6006491260550218157",
                "EntryMode": [
                  "MagStripe"
                ],
                "IdentificationType": "PAN"
              },
              "ItemAmount": 0,
              "Currency": "GBP"
            }
          ]
        }
      }
    }
    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.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.UNLOAD );
    StoredValueAccountID storedValueAccountID = new StoredValueAccountID();
    storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );
    storedValueAccountID.setStoredValueProvider("givex");
    storedValueAccountID.setExpiryDate("1122");
    storedValueAccountID.setStoredValueID("6006491260550218157");
    storedValueAccountID.getEntryMode().add( EntryModeType.MAGSTRIPE );
    storedValueAccountID.setIdentificationType( IdentificationType.PAN );
    storedValueData.setStoredValueAccountID(storedValueAccountID);
    storedValueData.setItemAmount( BigDecimal.valueOf(0) );
    storedValueData.setCurrency("GBP");
    storedValueRequest.setStoredValueData(storedValueData);
    saleToPOIRequest.setStoredValueRequest(storedValueRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

The deactivation request is sent to the Adyen payments platform for processing. Once processed, your integration receives a response indicating whether the gift card has been deactivated.

Step 2: Receive deactivation response

Once processed, your integration receives a response containing the result of the request. 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 card is deactivated:

  • You receive a response that contains a StoredValueResponse object. This includes:

    • POIData.POITransactionID.TransactionID: Transaction identifier for the deactivation.
    • PaymentResponse.Response.Result: Success

    The example below indicates that the deactivation request was successful, and card 6006491260550218157 was deactivated. This card now has a balance of 0 GBP.

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

    {
        "SaleToPOIResponse":{
            "StoredValueResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-05-17T14:13:03.000Z",
                        "TransactionID":"oLkO001526566383000.9815265664093834"
                    }
                },
                "SaleData":{
                    "SaleTransactionID":{
                        "TimeStamp":"2019-05-17T14:13:03.000Z",
                        "TransactionID":"44743"
                    }
                },
                "PaymentReceipt":[...],
                "StoredValueResult":[
                    {
                        "StoredValueTransactionType":"Unload",
                        "ItemAmount":0,
                        "StoredValueAccountStatus":{
                            "StoredValueAccountID":{
                                "IdentificationType":"PAN",
                                "EntryMode":[
                                    "MagStripe"
                                ],
                                "StoredValueID":"6006491260550218157",
                                "StoredValueAccountType":"GiftCard",
                                "ExpiryDate":"1122"
                            },
                            "CurrentBalance":0
                        },
                        "Currency":"GBP"
                    }
                ],
                "Response":{
                    "Result":"Success",
                    "AdditionalResponse":"..."
                }
            },
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "SaleID":"POSSystemID12345",
                "MessageClass":"Service",
                "MessageCategory":"StoredValue",
                "ServiceID":"9270",
                "POIID":"V400m-324688179",
                "MessageType":"Response"
            }
        }
    }

See also