Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Activate a gift card

Activate a gift card at the point of sale, so a shopper can use it.

When issuing a new gift card to a shopper, you need to make an activation request before the shopper can use the card 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, the shopper can't redeem it.

Before you begin

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

Make an activation request

To activate a gift card:

  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 cash register.
      POIID -white_check_mark- The unique ID of the terminal that you want to send this request to. Format: [device model]-[serial number].
    • StoredValueRequest: the request body for the activation request. This 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, valuelink, or any Intersolve-supported card type.
        • 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
          • 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.
      • 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, see the Terminal API fundamentals.

    {
        "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.

Activation response

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 your integration uses asynchronous cloud communications, you receive the payment response as an event notification.

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, see the Terminal API fundamentals.

    {
      "SaleToPOIResponse":{
        "StoredValueResponse":{
          "POIData":{
            "POITransactionID":{
              "TimeStamp":"2019-03-26T09:31:29.000Z",
              "TransactionID":"oLkO001522056689002.NC6HT9CRT65ZGN82"
            }
          },
          ...
          "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