Gift Cards

Gift cards are prepaid payment cards with a stored monetary value. They can be used for making payments and, depending on the provider, can also be loaded with more funds, cashed out, or are disabled.

Availability and Restrictions

Epay is a leading global payment and prepaid solutions provider specializing in the issuance and distribution of gift cards, online payment services, and mobile payment solutions for various brands worldwide. The management of these gift cards requires a specific set of operations handled between the Point of Sale (POS) and the Payment Terminal (POI).

The full lifecycle of an Epay gift card is managed by specific API requests that confirm the card's status and value:

Activation: Loads initial value onto a new physical or digital gift card, making it active and ready for use.
Payment: Retrieves the current unused balance remaining on the gift card before a purchase.
Reversal: Processes a transaction to credit funds back onto the gift card following a customer return or error.

This table summarizes the various Epay Gift Card product models available, defining the primary distinctions in how value is loaded, how security is enforced, and the specific functionality supported during the sale process. By understanding these differences, integrators can correctly map the physical card product to the required API transaction type.

Card Type	Main Attribute / Difference
Gift cards	Gift cards come in several types which are defined by : The profile : identifies how the card type works. The product : identifies a product that is part of a profile
POSA	Product requesting activation. One EAN scan product and one PAN scan (activation barcode). Example : Gift boxes (Smartbox, ...), Blackhawk branded cards (Xbox, ...), POSA epay cards (MS Office), Other brands (Maison de la literie, Carrefour Plus Card, ...). Note : a POSA product can be of variable amount, in which case, a credit amount is sent by the cash register.
PIN Printing	a PIN for a specified product is requested. The most common usage is the PIN used for reloading a mobile phone account. Such products contain only an EAN-13. Only one EAN scan product, then a ticket with the PIN code asked is printed. Example : phone top-ups, Pin on Receipt Blackhawk (Xbox codes, ...) Note : the Pin Printing cards can be of variable amount, in which case, a credit amount is sent by the cash register.

Card Type

Main Attribute / Difference

Gift cards

Gift cards come in several types which are defined by :

The profile : identifies how the card type works.
The product : identifies a product that is part of a profile

POSA

Product requesting activation. One EAN scan product and one PAN scan (activation barcode).
Example : Gift boxes (Smartbox, ...), Blackhawk branded cards (Xbox, ...), POSA epay cards (MS Office), Other brands (Maison de la literie, Carrefour Plus Card, ...).
Note : a POSA product can be of variable amount, in which case, a credit amount is sent by the cash register.

PIN Printing

a PIN for a specified product is requested. The most common usage is the PIN used for reloading a mobile phone account. Such products contain only an EAN-13. Only one EAN scan product, then a ticket with the PIN code asked is printed.

Example : phone top-ups, Pin on Receipt Blackhawk (Xbox codes, ...)
Note : the Pin Printing cards can be of variable amount, in which case, a credit amount is sent by the cash register.

1. Activation and Top-Up

The Activation and Top-up section details the essential process of loading value onto a gift card, using the StoredValueRequest message to transition the card from an inactive state to an active, usable prepaid instrument. The core operation is defined by setting the required MessageCategory to StoredValue in the message header.

Each Card Type has a specific activation, select the method which matches the Card Type when doing an Activation

Activation of a POSA and Gift cards

This table details the essential fields needed for the POS to successfully load value onto a POSA gift card. The primary operation is defined by the StoredValueTransactionType attribute.

For these cards, the EAN-13 and EAN-128 barcodes are scanned. Depending on the card, amount is fixed or variable.

The MessageCategory field for the activation request must be set to StoredValue because the operation involves managing the value held within a prepaid instrument, which is the technical classification for gift cards and similar products.

Parent Object	Description
`StoredValueTransactionType`	CRITICAL: Defines the action as `Activate` (or `Load`), initiating the value transfer.
`ItemAmount`	Enter the exact value to be loaded onto the gift card. Mandatory field, even for fixed card value. Expected amount will be loaded regardless of the amount provided for the fixed value card.
`Currency`	The currency of the loaded amount (e.g., EUR).
`StoredValueAccountID.StoredValueAccountType`	Specifies the instrument type; must be `GiftCard`.
`StoredValueAccountID.EntryMode`	The method used to enter the card data (e.g., `Scanned`).
`StoredValueAccountID.IdentificationType`	Specifies the format of the card identifier: - `PAN` for the EAN value - `ISOTrack2` for the barcode activation
`StoredValueAccountID.Value`	The unique identifier of the gift card being activated.

This payload initiates the activation (loading) of value onto a POSA or Gift card, using the StoredValueRequest schema.

Activation request example for POSA and Gift cards

This payload initiates the activation (loading) of value onto a POSA and Gift card, using the StoredValueRequest schema.

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "StoredValue",
      "MessageType": "Request",
      "ServiceID": "6296",
      "SaleID": "123",
      "POIID": "321"
    },
    "StoredValueRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "123",
          "TimeStamp": "2025-12-04T17:02:09Z"
        }
      },
      "StoredValueData": [
        {
          "StoredValueTransactionType": "Activate",
          "ItemAmount": "12.34",
          "Currency": "EUR",
          "StoredValueAccountID": {
            "StoredValueAccountType": "GiftCard",  // EAN
            "EntryMode": "Scanned",
            "IdentificationType": "PAN",
            "Value": "5404014500016"
          }
        },
        {
          "StoredValueTransactionType": "Activate",
          "ItemAmount": "12.34",
          "Currency": "EUR",
          "StoredValueAccountID": {
            "StoredValueAccountType": "GiftCard",  // PAN
            "EntryMode": "Scanned",
            "IdentificationType": "ISOTrack2",
            "Value": "2398001464500020428"
          }
        }
      ]
    }
  }
}

For Carrefour Gift Cards:
{
  "MessageHeader": {
    "MessageCategory": "StoredValue",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "StoredValueRequest": {
    "SaleData": {
      "SaleTransactionID": {
        "TransactionID": "9991",
        "TimeStamp": "2025-11-28T14:12:59.6+01:00"
      }
    },
    "StoredValueData": [
      {
        "StoredValueTransactionType": "Activate",
        "ItemAmount": "10",
        "Currency": "EUR",
        "StoredValueAccountID": {
          "StoredValueAccountType": "GiftCard",
          "EntryMode": "Scanned",
          "IdentificationType": "PAN",
          "StoredValueId": "3523670260590" // EAN
        }
      },
      {
        "StoredValueTransactionType": "Activate",
        "ItemAmount": "10",
        "Currency": "EUR",
        "StoredValueAccountID": { 
          "StoredValueAccountType": "GiftCard",
          "EntryMode": "Scanned",
          "IdentificationType": "ISOTrack2",
          "StoredValueId": "50320004235545705171548"  // PAN
        }
      },
      {
        "StoredValueTransactionType": "Activate",
        "ItemAmount": "10",
        "Currency": "EUR",
        "StoredValueAccountID": {
          "StoredValueAccountType": "GiftCard",
          "EntryMode": "Scanned",
          "IdentificationType": "BarCode",
          "StoredValueId": "CRFGIFTCRD"
        }
      }
    ]
  }
}

Review the full schema on the API specification page for required fields.

Activation of a PIN Printing card

This table details the essential fields needed for the POS to successfully load value onto a PIN Printing card. The primary operation is defined by the StoredValueTransactionType attribute.

Parent Object	Description
`StoredValueTransactionType`	CRITICAL: Defines the action as `Activate` (or `Load`), initiating the value transfer.
`ItemAmount`	The exact value to be loaded onto the gift card.
`Currency`	The currency of the loaded amount (e.g., EUR).
`StoredValueAccountID.StoredValueAccountType`	Specifies the instrument type; must be `GiftCard`.
`StoredValueAccountID.EntryMode`	The method used to enter the card data (e.g., `Scanned`).
`StoredValueAccountID.IdentificationType`	Specifies the format of the card identifier (e.g., `PAN` - Primary Account Number).
`StoredValueAccountID.Value`	The unique identifier of the gift card being activated.

This payload initiates the activation (loading) of value onto a PIN Printing card, using the StoredValueRequest schema.

Activation request example for PIN Printing cards

This payload initiates the activation (loading) of value onto a PIN Printing card, using the StoredValueRequest schema.

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "StoredValue",
      "MessageType": "Request",
      "ServiceID": "102",
      "SaleID": "POS_01",
      "POIID": "POI_01"
    },
    "StoredValueRequest": {
      "SaleData": {
        "SaleTransactionID": {
          "TransactionID": "123",
          "TimeStamp": "2025-12-04T16:58:44Z"
        }
      },
      "StoredValueData": {
        "StoredValueTransactionType": "Activate",
        "ItemAmount": "12.34",
        "Currency": "EUR",
        "StoredValueAccountID": {
          "StoredValueAccountType": "GiftCard",
          "EntryMode": "Scanned",
          "IdentificationType": "PAN",
          "Value": "5391515728950"
        }
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

2. Balance inquiry

Request

This table details the fields essential for successfully requesting a gift card balance, which are placed within the BalanceInquiryRequest body.

Parent Object	Description
`LoyaltyAccountID.Value`	The unique identifier of the gift card (Barcode number).
`LoyaltyAccountID.EntryMode`	The method used to enter the card data (e.g., `Scanned`).
`LoyaltyAccountID.IdentificationType`	Specifies the format of the identifier (e.g., `BarCode`).
`MarketpayPaymentExtensions.Operation`	Explicitly defines the action requested on the Epay server as a `GiftCardBalanceInquiry`.
`MarketpayPaymentExtensions.CardId2`	A duplicate of the card identifier, used by some processors for routing and validation.

This payload requests the balance for a specific gift card identified by a scanned barcode.

Balance request example (JSON example)

This payload request the balance for a specific gift card identified by a scanned barcode.

<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <MessageHeader MessageClass="Service" MessageCategory="BalanceInquiry" MessageType="Request" ServiceID="6306" SaleID="123" POIID="321"></MessageHeader>
   <BalanceInquiryRequest>
       <LoyaltyAccountReq>
           <LoyaltyAccountID EntryMode="Scanned" IdentificationType="BarCode">50320004235545705171548</LoyaltyAccountID>
       </LoyaltyAccountReq>
       <MarketpayPaymentExtensions Operation="GiftCardBalanceInquiry" CardId2="50320004235545705171548"></MarketpayPaymentExtensions>
   </BalanceInquiryRequest>
 </SaleToPOIRequest>

Review the full schema on the API specification page for required fields.

Balance request example (HTTP example)

This payload request the balance for a specific gift card identified by a scanned barcode.

{
    "MessageHeader": {
        "MessageCategory": "BalanceInquiry",
        "MessageClass": "Service",
        "MessageType": "Request",
        "POIID": "POI_01",
        "ProtocolVersion": "3.1",
        "SaleID": "POS_01",
        "ServiceID": "0"
    },
    "BalanceInquiryRequest": {
        "LoyaltyAccountReq": {
            "loyaltyAccountID": {
                "EntryMode": "Scanned",
                "IdentificationType": "BarCode",
                "LoyaltyID": "50320004235545705171548"
            }
        }
    }

Review the full schema on the API specification page for required fields.

Response

This table lists the critical data points the POS must extract from the BalanceInquiryResponse to display the information and proceed with the payment flow.

Field Name	Purpose for POS
`Response.Result`	Status Confirmation: Must be `"Success"` to proceed.
`LoyaltyAccountStatus.CurrentBalance`	The amount available on the gift card. Display to the customer; used as the maximum authorized amount for a subsequent payment.
`LoyaltyAccountStatus.Currency`	The currency code of the available balance.
`LoyaltyAccountStatus.LoyaltyAccountID`	The identification of the gift card.

This payload response shows the balance for a specific gift card identified by a scanned barcode.

Balance response example (JSON Example)

This payload response the balance for a specific gift card identified by a scanned barcode.

<SaleToPOIResponse>
    <BalanceInquiryResponse>
       <LoyaltyAccountStatus Currency="EUR" CurrentBalance="49.39">
          <LoyaltyAccount>
             <LoyaltyAccountID EntryMode="Scanned" IdentificationType="BarCode">50320004235545705171548</LoyaltyAccountID>
          </LoyaltyAccount>
       </LoyaltyAccountStatus>
       <MarketpayPaymentExtensions>
          <CRFPaymentExtension/>
       </MarketpayPaymentExtensions>
       <Response Result="Success"/>
    </BalanceInquiryResponse>
    <MessageHeader MessageCategory="BalanceInquiry" MessageClass="Service" MessageType="Response" POIID="321" ProtocolVersion="3.1" SaleID="123" ServiceID="6306"/>
 </SaleToPOIResponse>

Review the full schema on the API specification page for required fields.

Balance response example (HTTP example)

This payload response the balance for a specific gift card identified by a scanned barcode.

{
    "BalanceInquiryResponse": {
        "LoyaltyAccountStatus": {
            "Currency": "EUR",
            "CurrentBalance": "195.00",
            "LoyaltyAccount": {
                "LoyaltyAccountID": {
                    "EntryMode": "Scanned",
                    "IdentificationType": "BarCode",
                    "LoyaltyID": "50320004235545705171548"
                }
            }
        },
        "MarketpayPaymentExtensions": {
            "CRFPaymentExtension": {}
        },
        "Response": {
            "Result": "Success"
        }
    },
    "MessageHeader": {
        "MessageCategory": "BalanceInquiry",
        "MessageClass": "Service",
        "MessageType": "Response",
        "POIID": "POI_01",
        "ProtocolVersion": "3.1",
        "SaleID": "POS_01",
        "ServiceID": "0"
    }
}

Review the full schema on the API specification page for required fields.

3. Payment

The Payment Request used for gift card payment follows the standard payment request, allowing the Point of Sale (POS) to process the gift card redemption using the same established logic as any other primary payment method.

This table details the specific fields from PaymentRequest needed to redeem value from the Epay gift card.

Field Name	Description
`PaymentData.MarketpayPaymentExtensions.CardId2`	The unique identifier of the gift card (e.g., the barcode or PAN) being used for the payment.
`PaymentData`	Sent as an empty object (`{}`) but required to define the transaction data context.

This payload requests the balance for a specific gift card identified by a scanned barcode.

Payment request example

{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "102",
      "SaleID": "POS_01",
      "POIID": "POI_01"
    },
    "PaymentRequest": {
      "SaleData": {

        "SaleTransactionID": {
          "TransactionID": "123",
          "TimeStamp": "2025-12-04T17:13:31Z"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "1.00"
        }
      },
      "PaymentData": {},
      "MarketpayPaymentExtensions": {
        "CardId2": "50320004251718522779761002"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

Response

The Point of Sale (POS) can process a gift card transaction using the same reconciliation logic as a standard payment, as the terminal returns a PaymentResponse object containing a final Result status and the AmountsResp for the authorized amount. While specific fields in the MarketpayPaymentExtensions may differ to identify the gift card scheme, the developer should refer to the standard payment response documentation for handling transaction status, amounts, and receipts.

Abort

The immediate cancellation of an in-progress Gift Card payment follows the standard /abort mechanism, requiring the POS to send the command to terminate the current processing thread.

Reversal

Undoing a completed Gift Card financial transaction (like a Payment or Reservation) follows the standard /reversal procedure, requiring the POS to initiate an asynchronous reversal message that links back to the original transaction ID.