Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Deactivate or cash out a gift card

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:

Cash 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.

To make a gift card cashback request:

  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. Check the balance remaining on the gift card.
  3. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:
      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • PaymentRequest.SaleData. This includes:

      Parameter Required Description
      SaleTransactionID.TransactionID -white_check_mark- Your reference to identify this cashback request. We recommend using a unique value.
      SaleTransactionID.TimeStamp -white_check_mark- Date and time of the cashback request, in UTC format.
      SaleReferenceID -white_check_mark- 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.
      SaleToAcquirerData -white_check_mark- redemptionType=cashback


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

      • Option 1: a JSON object converted to a Base64 encoded string.
        Encode {"redemptionType": "cashback"} to Base64, and pass the resulting string:
        "SaleToAcquirerData": "eyJyZWRlbXB0aW9uVHlwZSI6ICJjYXNoYmFjayJ9"

      • Option 2: a key-value pair:
        "SaleToAcquirerData": "redemptionType=cashback"

      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 given back to the shopper. To cash out the full amount, you can either specify that exact amount, or specify a zero (0) amount.
    • PaymentRequest.PaymentData. This includes:

      Parameter Required Description
      PaymentType -white_check_mark- Normal
      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 table below.
      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 initiate a 4.50 GBP cashback request for a scanned gift card.

    {
      "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",
                "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");
    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.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 cashback request is sent to the Adyen payments platform for processing. Once processed, your integration receives the cashback result.

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

If the cashback request is successful:

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

    The example below indicates that the cashback request was successful, and 4.50 GBP was removed from the balance of the gift card.

    {
        "SaleToPOIResponse":{
            "PaymentResponse":{
                "POIData":{
                    "POITransactionID":{
                        "TimeStamp":"2019-06-22T12:55:24.000Z",
                        "TransactionID":"u6W7001529672124004.NC6HT9CRT65ZGN82"
                    }
                },
                "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":"NC6HT9CRT65ZGN82"
                        },
                        "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 a gift card

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

To make a deactivation request:

  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:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:
      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- StoredValue
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
    • StoredValueRequest.SaleData.SaleTransactionID. This includes:

      Parameter Required Description
      TransactionID Your reference to identify this deactivation request. We recommend using a unique value.
      TimeStamp Date and time of the deactivation request, in UTC format.
    • StoredValueRequest.StoredValueData. This includes:

      Parameter Required Description
      StoredValueTransactionType Unload
      StoredValue.StoredValueAccountID The gift card details:
      • StoredValueAccountType: GiftCard
      • StoredValueProvider: the gift card issuer: givex, svs, or valuelink.
      • IdentificationType: PAN
      • ItemCount: 0
      • Currency: currency of the gift card.
      • EntryMode, StoredValueID and ExpiryDate: these parameters depend on the card entry method you are using.
      Card entry Parameters
      Scan
      • EntryMode: Scanned
      • StoredValueID: gift card number.
      • ExpiryDate: expiry date of the gift card.
      Swipe
      • EntryMode: MagStripe
      MKE
      • EntryMode: Keyed
      • StoredValueID: xxxxxxxxxxxxxxxxxxx.

    The example below shows how you would request the deactivation of a scanned gift card.

    {
      "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",
                "IdentificationType": "PAN",
                "EntryMode": [
                  "Scanned"
                ],
                "StoredValueID": "6006491260550218066",
                "ExpiryDate": "1122"
              },
              "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.setIdentificationType( IdentificationType.PAN );
    storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
    storedValueAccountID.setStoredValueID("6006491260550218066");
    storedValueAccountID.setExpiryDate("1122");
    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.

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

If the card is deactivated:

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

    • POIData.POITransactionID.TransactionID: transaction identifier for the deactivation.
    • StoredValueResult

      • StoredValueTransactionType: Unload
      • StoredValueAccountStatus.CurrentBalance: current balance on the gift card, which is 0 because the card was deactivated.

    • 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.

    {
      "SaleToPOIResponse":{
        "StoredValueResponse":{
          "POIData":{
            "POITransactionID":{
              "TimeStamp":"2019-05-17T14:13:03.000Z",
              "TransactionID":"oLkO001526566383000.KHQC5N7G84BLNK43"
            }
          },
          ...
          "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