Activate a gift card

When issuing a new gift card to a shopper, you will need to make an activation request before the card can be used for transactions. While activating the gift card, you can also load an initial balance.

Gift card activation is also a fraud protection tool. If the card is not active, it cannot be redeemed.

When the activation request is processed, you receive a result indicating whether the activation was successful.

Before you begin

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

• Read and understood our Terminal API fundamentals.
• Built an integration that can make a payment.
• Completed the onboarding process with your gift card provider.
• Added the payment method to your Adyen account.

Step 1: Make activation request

To activate 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 activation 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: Activate

    • StoredValueData.StoredValueAccountID: The gift card details:

      • StoredValueAccountType: GiftCard
      • StoredValueProvider: The gift card issuer: givex, svs, or valuelink
      • IdentificationType: PAN

      • 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 or MKE	EntryMode: MagStripe StoredValueID: xxxxxxxxxxxxxxxxxxx. Do not include the ExpiryDate parameter.

    • StoredValueData.ItemAmount: Initial balance being loaded to the gift card.

    • StoredValueData.Currency: Currency of the initial balance.

  The example below shows how you would activate a scanned gift card, adding an initial balance of 10.00 GBP.

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

  https://docs.adyen.com/point-of-sale/payment-methods/gift-cards-terminal-api/activate#activate1.scan

  • JSON
  • Java

  {
      "SaleToPOIRequest":{
          "MessageHeader":{
              "MessageType":"Request",
              "MessageClass":"Service",
              "MessageCategory":"StoredValue",
              "SaleID":"POSSystemID12345",
              "POIID":"V400m-324688179",
              "ProtocolVersion":"3.0",
              "ServiceID":"9264"
          },
          "StoredValueRequest":{
              "SaleData":{
                  "SaleTransactionID":{
                      "TransactionID":"44738",
                      "TimeStamp":"2019-09-29T14:44:32+00:00"
                  }
              },
              "StoredValueData":[
                  {
                      "StoredValueTransactionType":"Activate",
                      "StoredValueAccountID":{
                          "StoredValueAccountType":"GiftCard",
                          "StoredValueProvider":"svs",
                          "IdentificationType":"PAN",
                          "EntryMode":[
                              "Scanned"
                          ],
                          "StoredValueID":"6006491260550218066",
                          "ExpiryDate":"1122"
                      },
                      "ItemAmount":10.00,
                      "Currency":"GBP"
                  }
              ]
          }
      }
  }

  String saleID = "YOUR_CASH_REGISTER_ID";
  String POIID = "YOUR_TERMINAL_ID";
  String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
  String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
  
  SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
  MessageHeader messageHeader = new MessageHeader();
  messageHeader.setMessageType( MessageType.REQUEST );
  messageHeader.setMessageClass( MessageClassType.SERVICE );
  messageHeader.setMessageCategory( MessageCategoryType.STORED_VALUE );
  messageHeader.setSaleID(saleID);
  messageHeader.setPOIID(POIID);
  messageHeader.setProtocolVersion("3.0");
  messageHeader.setServiceID(serviceID);
  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.ACTIVATE );
  StoredValueAccountID storedValueAccountID = new StoredValueAccountID();
  storedValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );
  storedValueAccountID.setStoredValueProvider("svs");
  storedValueAccountID.setIdentificationType( IdentificationType.PAN );
  storedValueAccountID.getEntryMode().add( EntryModeType.SCANNED );
  storedValueAccountID.setExpiryDate("1122");
  storedValueAccountID.setStoredValueID("6006491260550218066");
  storedValueData.setStoredValueAccountID(storedValueAccountID);
  storedValueData.setItemAmount( BigDecimal.valueOf(10.00) );
  storedValueData.setCurrency("GBP");
  storedValueRequest.setStoredValueData(storedValueData);
  saleToPOIRequest.setStoredValueRequest(storedValueRequest);
  terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

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

Step 2: Receive activation result

Once processed, your integration receives an activation result indicating whether the gift card was successfully activated. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.

If the activation is successful:

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

  • POIData.POITransactionID.TransactionID: Transaction identifier for the gift card activation.

  • StoredValueResult:

    • StoredValueTransactionType: Activate

    • ItemAmount and Currency: Current value and currency associated with the card.

  • Response.Result: Success

  The example below indicates that the gift card was successfully activated, and an initial balance of 10.00 GBP loaded to the card.

  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":"oLkO001522056689002.9815220566972551"
          }
        },
        ...
        "StoredValueResult":[
          {
            "StoredValueTransactionType":"Activate",
            "ItemAmount":10.00,
            "Currency":"GBP"
          }
        ],
        "Response":{
          "Result":"Success"
        }
      },
      "MessageHeader":{
        "ProtocolVersion":"3.0",
        "SaleID":"POSSystemID12345",
        "MessageClass":"Service",
        "MessageCategory":"StoredValue",
        "ServiceID":"9264",
        "POIID":"V400m-324688179",
        "MessageType":"Response"
      }
    }
  }

Next steps

See also