--- title: "Make a gift card payment" description: "Make a gift card payment at the point of sale." url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/payment" source_url: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/payment.md" canonical: "https://docs.adyen.com/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/payment" last_modified: "2022-01-11T18:52:00+01:00" language: "en" --- # Make a gift card payment Make a gift card payment at the point of sale. [View source](/point-of-sale/alternative-payment-methods/gift-cards-terminal-api/payment.md) After you have [activated a gift card](/point-of-sale/gift-cards-terminal-api/activate) and [loaded with a balance](/point-of-sale/gift-cards-terminal-api/load-a-balance), you can make a payment with the gift card. There are two gift card payment flows: one using partial authorizations and another that involves a balance check first. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with payment terminals. | | **Setup steps** | Before you begin:- [Add the payment method to your Adyen account](/point-of-sale/what-we-support/payment-methods/add-payment-methods). - Complete the onboarding process with the gift card provider. | ## How it works You can choose one of two payment flows: * A flow with one or more partial payment requests if you do not know the exact balance on the gift card: 1. Make a partial gift card payment request for the full amount due. 2. If the gift card balance is not enough, you [make a follow-up payment](/point-of-sale/gift-cards-terminal-api/payment#partial-authorisation) request to let the shopper pay the remainder with another card or cash. * A flow without partial authorizations where you first check the balance of the gift card: 1. [Make a balance request](/point-of-sale/gift-cards-terminal-api/query-the-balance#make-a-balance-inquiry) to check the balance on the gift card. 2. Decide what to do next: * If the balance is enough, you make a gift card payment request for the full amount due. * If the balance is not enough, you make a gift card payment request for the full balance, and then you make a regular payment request to let the shopper pay the remainder with a different card or cash. ## 1. Make the initial payment ##### Testing You can [test the partial authorization flow](/point-of-sale/partial-authorizations#testing-partial-authorizations) using an amount ending in **139**. To make a payment using a gift card where partial authorization is possible: 1. Determine the [card entry method](/point-of-sale/gift-cards-terminal-api#card-entry): * 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 key 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 payment request](/point-of-sale/basic-tapi-integration/make-a-payment#make-a-payment), specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [PaymentRequest.SaleData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-SaleData) object with: | Parameter | Required | Description | | -------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TransactionID`: your reference to identify a payment. We recommend using a unique value. In your Customer Area and Adyen reports, this will show as the **merchant reference** for the transaction. - `TimeStamp`: Date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleReferenceID` | | Unique reference, such as your order number plus a sequence number, that lets you identify partial authorizations that belong together. In your [Customer Area](https://ca-test.adyen.com/), this will appear as the **Merchant Order** for the transaction. For example, if the order number is *Order12345*, you specify **Order12345-1** in the first partial authorization request and **Order12345-2** in the second partial authorization request. | | `SaleToAcquirerData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | * The **AllowPartialAuthorisation** tender option. See the [instructions below](#sale-to-acquirer-data). * Optional for manually keying in the card number (MKE): **maxLength** and **cardMask**. Use these fields to specify card numbers with more than 24 digits. See the [example MKE gift card request](/point-of-sale/gift-cards-terminal-api/payment?tab=gift_card_payment_mke_2). * Optional for Stored Value Solutions (SVS) gift cards: **ssc**. This is the secondary security code of the gift card, and allows up to 8 digits. For example, `ssc`: **1111**. | []()\ 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 `{"tenderOption": "AllowPartialAuthorisation"}` to Base64, and pass the resulting string:\ `"SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQWxsb3dQYXJ0aWFsQXV0aG9yaXNhdGlvbiJ9"` * Option 2: a key-value pair:\ `"SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation"` 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](/point-of-sale/add-data). - The [PaymentRequest.PaymentTransaction](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-PaymentTransaction) object with: | Parameter | Required | Description | | ------------ | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes). - `RequestedAmount`: The purchase amount, with decimals. | - The [PaymentRequest.PaymentData.PaymentInstrumentData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-PaymentData-PaymentInstrumentData) object. This is where you indicate that a gift card is used.\ []() | Parameter | Required | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PaymentInstrumentType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **StoredValue** | | `StoredValueAccountID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The gift card details:- `StoredValueAccountType`: **GiftCard** - `StoredValueProvider`: the gift card issuer, such as **givex**, **svs**, **valuelink**, **genericgiftcard**, or **[any Intersolve-supported card type](/payment-methods/gift-cards#supported-gift-cards)**. - `IdentificationType`: **PAN** - `EntryMode`, `StoredValueID` and `ExpiryDate`: these parameters depend on the [card entry method](/point-of-sale/gift-cards-terminal-api#card-entry) you are using. See the following table. | | 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 do not provide a value. | | MKE | * `EntryMode`: **Keyed** * `StoredValueID`: include this parameter but do not provide a value. | Select the tabs below to see some example gift card payment requests. ### Tab: Gift card payment - Scanned This example shows a request for a EUR 25.99 payment with a scanned gift card with a secondary security code in the `SaleToAcquirerData` field. **Gift card payment with partial payment tender option** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"9267", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44740", "TimeStamp":"2019-03-26T09:13:41+00:00" }, "SaleReferenceID":"Order12345-1", "SaleToAcquirerData":"tenderOption=AllowPartialAuthorisation&ssc=1111" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":25.99 } }, "PaymentData":{ "PaymentInstrumentData":{ "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006490000000000", "ExpiryDate":"1122" } } } } } } ``` ### Tab: Gift card payment - MKE []()\ The following example shows a gift card payment request for manual key entry (`EntryMode` **Keyed**), where `SaleToAcquirerData` specifies the `maxLength` and `cardMask` for the gift card number. To ensure the entered numbers are visible, use `*` as card mask character. Using `x` hides entered numbers.\ If you expect the card number to be 24 characters or less, there is no need to include a maximum length and card mask. **MKE gift card payment request to allow an extra long card number** ```json { "SaleToPOIRequest":{ "MessageHeader":{...}, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44740", "TimeStamp":"2019-03-26T09:13:41+00:00" }, "SaleReferenceID":"Order12345-1", "SaleToAcquirerData":"maxLength=27&cardMask=****-****-****-****-****-****-***&tenderOption=AllowPartialAuthorisation" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":25.99 } }, "PaymentData":{ "PaymentInstrumentData":{ "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Keyed" ], "StoredValueID":"" } } } } } } ``` 3. In the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200), note the following: * `Response.Result`: If the payment was successful, **Success** indicates a full authorization, or **Partial** indicates a partial authorization. * `PaymentResult.AmountsResp.AuthorizedAmount`: The amount that was authorized. This may be less than the requested amount. * `AdditionalResponse`: Contains `posOriginalAmountValue` with the requested amount, and `posAuthAmountValue` with the authorized amount. * `SaleData.SaleReferenceID`: Your order number. If you are going to make another payment for the remainder, the `SaleReferenceID` of that other payment must be based on this one. The example below shows that the gift card payment was successful, but only EUR 10.00 of the original EUR 25.99 was authorized. **Response for a partial gift card payment** ```json { "SaleToPOIResponse": { "MessageHeader": {...}, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TimeStamp": "2021-11-16T11:26:19.000Z", "TransactionID": "CWf3001637061979001.M32P3JBKR65ZGN82" } }, "PaymentReceipt": [...], "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 10.00, "Currency": "EUR" }, ..., "PaymentAcquirerData": {...}, ... }, "PaymentInstrumentData": { "StoredValueAccountID":{ "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006490000000000", "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "ExpiryDate":"1122" }, "PaymentInstrumentType": "StoredValue" } }, "Response": { "AdditionalResponse": "...&posOriginalAmountValue=2599...&posAuthAmountValue=1000", "Result": "Partial" }, "SaleData": { "SaleReferenceID": "Order12345-1", "SaleTransactionID": { "TimeStamp": "2021-11-16T11:26:15.253Z", "TransactionID": "644" } } } } } ``` 4. If the `Response.Result` is **Partial**, [make a follow-up partial payment](#partial-authorisation) or let the customer pay the remainder in cash. ## 2. (Optional) Make a follow-up payment If the initial partial payment with the gift card didn't cover the full amount, you can follow up with another partial payment for the remainder: 1. Calculate the remaining amount after the initial partial authorization: subtract the `AuthorizedAmount` in the response from the `RequestedAmount` in the request.\ Alternatively, you can calculate the remaining amount using `posAuthAmountValue` and `posOriginalAmountValue` from the `AdditionalResponse`. 2. [Make a payment request](/point-of-sale/basic-tapi-integration/make-a-payment#make-a-payment), specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [PaymentRequest.SaleData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-SaleData) object with: | Parameter | Required | Description | | -------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleReferenceID` | | Unique reference, such as your order number plus a sequence number, that lets you identify partial authorizations that belong together.For example, if you specified **Order12345-1** in the first partial authorization request with the gift card, you'd specify **Order12345-2** in this second payment request. | | `SaleToAcquirerData` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The **AllowPartialAuthorisation** tender option.For the format, see the [initial partial authorization](#sale-to-acquirer-data). | - The [PaymentRequest.PaymentTransaction](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#request-PaymentTransaction) object with: | Parameter | Required | Description | | ------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes). - `RequestedAmount`: The calculated remaining amount. | This example shows a payment request for the remaining EUR 15.99. **Follow-up payment for the remainder** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"9267", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44740", "TimeStamp":"2019-03-26T09:13:45+00:00" }, "SaleReferenceID": "Order12345-2", "SaleToAcquirerData": "tenderOption=AllowPartialAuthorisation" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":15.99 } } } } } ``` 3. When you receive the response, check if the `Response.Result` is now **Success**. That means the amount due is paid in full. ## Alternative flow with the balance check In this flow you first check the balance on the gift card, and then adjust your payment request(s) accordingly. To illustrate this, we use an example where the purchase amount is EUR 25.99, and the shopper has a gift card with a balance of EUR 15.99. 1. [Check the balance](/point-of-sale/gift-cards-terminal-api/query-the-balance) on the gift card. In our example, that is EUR 15.99. 2. Make a gift card payment request for the available amount (EUR 15.99), including: * The [`PaymentInstrumentData` ](#payment-instrument-data)for the gift card. * A `RequestedAmount` that doesn't exceed the balance on the gift card. **Gift card payment request for the exact available balance of EUR 15.99** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"9267", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44740", "TimeStamp":"2019-03-26T09:13:41+00:00" }, "SaleReferenceID":"Order12345-1", }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":15.99 } }, "PaymentData":{ "PaymentInstrumentData":{ "PaymentInstrumentType":"StoredValue", "StoredValueAccountID":{ "StoredValueAccountType":"GiftCard", "StoredValueProvider":"svs", "IdentificationType":"PAN", "EntryMode":[ "Scanned" ], "StoredValueID":"6006490000000000", "ExpiryDate":"1122" } } } } } } ``` 3. Complete the payment by making a [regular payment request](/point-of-sale/basic-tapi-integration/make-a-payment) for the remaining EUR 10.00, or by asking the shopper for the remainder in cash. **Payment request of the remaining EUR 10.00** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "ServiceID":"9267", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179" }, "PaymentRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44740", "TimeStamp":"2019-03-26T09:13:41+00:00" }, "SaleReferenceID":"Order12345-1", }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":10.00 } } } } } } ``` ## See also * [Gift cards and other stored value cards](/point-of-sale/gift-cards-terminal-api) * [Activate a gift card](/point-of-sale/gift-cards-terminal-api/activate) * [Check the balance of a gift card](/point-of-sale/gift-cards-terminal-api/query-the-balance) * [Partial authorizations](/point-of-sale/partial-authorizations/)