{"title":"Check the balance of a gift card","category":"default","creationDate":1779533779,"content":"<p>You can check the funds remaining on an <a href=\"\/point-of-sale\/gift-cards-terminal-api\/activate\">activated gift card<\/a>, by making a balance request. This allows you to verify the gift card's value before a transaction and determine if a partial payment is needed.<\/p>\n<h2>Requirements<\/h2>\n<p>Before you begin, take into account the following requirements, limitations, and preparations.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\">A <a href=\"\/point-of-sale\/design-your-integration\/terminal-api\">Terminal API<\/a> integration with payment terminals.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Setup steps<\/strong><\/td>\n<td style=\"text-align: left;\">Before you begin: <ul><li> <a href=\"\/point-of-sale\/what-we-support\/payment-methods#add-payment-methods-to-your-account\">Add the payment method to your Adyen account<\/a>. <\/li><li>Complete the onboarding process with the gift card provider. <\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Make a balance inquiry<\/h2>\n<p>To see the funds remaining on a gift card:<\/p>\n<ol>\n<li>\n<p>Determine the <a href=\"\/point-of-sale\/gift-cards-terminal-api#card-entry\">card entry method<\/a>:<\/p>\n<ul>\n<li>If you want to scan the card, do that first and use the obtained card details in your request.<\/li>\n<li>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.<\/li>\n<\/ul>\n<\/li>\n<li>\n<p>Make a <a href=\"\/point-of-sale\/design-your-integration\/terminal-api\">Terminal API<\/a> balance inquiry request, specifying:<\/p>\n<ul>\n<li>\n<p>The standard <a href=\"\/point-of-sale\/design-your-integration\/terminal-api#request-message-header\">\n  <code>SaleToPOIRequest.MessageHeader<\/code>\n<\/a> object, with <code>MessageClass<\/code> set to <span translate=\"no\"><strong>Service<\/strong><\/span> and <code>MessageCategory<\/code> set to <span translate=\"no\"><strong>BalanceInquiry<\/strong><\/span>.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>ProtocolVersion<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><strong>3.0<\/strong><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageClass<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>Service<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageCategory<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>BalanceInquiry<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageType<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>Request<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>ServiceID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (<code>POIID<\/code>) being used.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>SaleID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Your unique ID for the POS system component to send this request from.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>POIID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The unique ID of the terminal to send this request to. Format: <em>[device model]-[serial number]<\/em>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n<li>\n<p>The  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/terminal-api\/latest\/post\/balanceinquiry#request-PaymentAccountReq-PaymentInstrumentData\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">BalanceInquiryRequest.PaymentAccountReq.PaymentInstrumentData<\/a> object with:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>ProtectedCardData<\/code><\/td>\n<td style=\"text-align: center;\"><\/td>\n<td style=\"text-align: left;\">Optional secondary security (SSC) code for SVS gift cards. The SSC allows up to 8 digits. For example, <code>ssc=1111<\/code>. <p> If the secondary security code is required, encode it to Base64 and pass the resulting string. For example, <code>{\"ssc=1111\"}<\/code> needs to be passed as <code>\"ProtectedCardData\": \"eyJzc2MiOiIxMTExIn0=\"<\/code><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>PaymentInstrumentType<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>StoredValue<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>StoredValueAccountID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The gift card details: <ul> <li><code>StoredValueAccountType<\/code>: <span translate=\"no\"><strong>GiftCard<\/strong><\/span><\/li> <li><code>StoredValueProvider<\/code>: the gift card issuer: <span translate=\"no\"><strong>givex<\/strong><\/span>, <span translate=\"no\"><strong>svs<\/strong><\/span>, <span translate=\"no\"><strong>valuelink<\/strong><\/span>, or <strong><a href=\"\/payment-methods\/gift-cards#supported-gift-cards\">any Intersolve-supported card type<\/a><\/strong>.<\/li> <li><code>IdentificationType<\/code>: <span translate=\"no\"><strong>PAN<\/strong><\/span><\/li> <li><code>EntryMode<\/code>, <code>StoredValueID<\/code> and <code>ExpiryDate<\/code>: these parameters depend on the <a href=\"\/point-of-sale\/gift-cards-terminal-api#card-entry\">card entry method<\/a> you are using. See the following table.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Card entry<\/th>\n<th style=\"text-align: left;\">Parameters<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Scan<\/td>\n<td style=\"text-align: left;\"><ul><li><code>EntryMode<\/code>: <span translate=\"no\"><strong>Scanned<\/strong><\/span><\/li><li><code>StoredValueID<\/code>: gift card number.<\/li><li><code>ExpiryDate<\/code>: expiry date of the gift card.<\/li><\/ul><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">Swipe<\/td>\n<td style=\"text-align: left;\"><ul><li><code>EntryMode<\/code>: <span translate=\"no\"><strong>MagStripe<\/strong><\/span><\/li><li><code>StoredValueID<\/code>: include this parameter but do not provide a value.<\/li><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\">MKE<\/td>\n<td style=\"text-align: left;\"><ul><li><code>EntryMode<\/code>: <span translate=\"no\"><strong>Keyed<\/strong><\/span><\/li><li><code>StoredValueID<\/code>: include this parameter but do not provide a value.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n<\/ul>\n<p>The example below shows how to check the balance for a scanned gift card. It includes an optional <code>ProtectedCardData<\/code> field required for stored value solution gift cards with the SSC converted to a Base64-encoded string.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"''\" :id=\"'query-the-balance_0'\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"JSON\",\"content\":\"{\\n    \\\"SaleToPOIRequest\\\":{\\n        \\\"MessageHeader\\\":{\\n            \\\"ProtocolVersion\\\":\\\"3.0\\\",\\n            \\\"MessageClass\\\":\\\"Service\\\",\\n            \\\"MessageCategory\\\":\\\"BalanceInquiry\\\",\\n            \\\"MessageType\\\":\\\"Request\\\",\\n            \\\"ServiceID\\\":\\\"9266\\\",\\n            \\\"SaleID\\\":\\\"POSSystemID12345\\\",\\n            \\\"POIID\\\":\\\"V400m-324688179\\\"\\n        },\\n        \\\"BalanceInquiryRequest\\\":{\\n            \\\"PaymentAccountReq\\\":{\\n                \\\"PaymentInstrumentData\\\":{\\n                    \\\"ProtectedCardData\\\": \\\"eyJzc2MiOiIxMTExIn0=\\\",\\n                    \\\"PaymentInstrumentType\\\":\\\"StoredValue\\\",\\n                    \\\"StoredValueAccountID\\\":{\\n\\n                        \\\"StoredValueAccountType\\\":\\\"GiftCard\\\",\\n                        \\\"StoredValueProvider\\\":\\\"svs\\\",\\n                        \\\"IdentificationType\\\":\\\"PAN\\\",\\n                        \\\"EntryMode\\\":[\\n                            \\\"Scanned\\\"\\n                        ],\\n                        \\\"StoredValueID\\\":\\\"6006491260550218066\\\",\\n                        \\\"ExpiryDate\\\":\\\"1122\\\"\\n                    }\\n                }\\n            }\\n        }\\n    }\\n}\"},{\"language\":\"java\",\"tabTitle\":\"Java\",\"content\":\"String serviceID = \\\"YOUR_UNIQUE_ATTEMPT_ID\\\";\\nString saleID = \\\"YOUR_CASH_REGISTER_ID\\\";\\nString POIID = \\\"YOUR_TERMINAL_ID\\\";\\n\\nSaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();\\nMessageHeader messageHeader = new MessageHeader();\\nmessageHeader.setProtocolVersion(\\\"3.0\\\");\\nmessageHeader.setMessageClass( MessageClassType.SERVICE );\\nmessageHeader.setMessageCategory( MessageCategoryType.BALANCE_INQUIRY );\\nmessageHeader.setMessageType( MessageType.REQUEST );\\nmessageHeader.setServiceID(serviceID);\\nmessageHeader.setSaleID(saleID);\\nmessageHeader.setPOIID(POIID);\\nsaleToPOIRequest.setMessageHeader(messageHeader);\\n\\nBalanceInquiryRequest balanceInquiryRequest = new BalanceInquiryRequest();\\nPaymentAccountReq paymentAccountReq = new PaymentAccountReq();\\nPaymentInstrumentData paymentInstrumentData = new PaymentInstrumentData();\\npaymentInstrumentData.setPaymentInstrumentType( PaymentInstrumentType.STORED_VALUE );\\nStoredValueAccountID storedValueAccountID = new StoredValueAccountID();\\nstoredValueAccountID.setStoredValueAccountType( StoredValueAccountType.GIFT_CARD );\\nstoredValueAccountID.setStoredValueProvider(\\\"svs\\\");\\nstoredValueAccountID.setIdentificationType( IdentificationType.PAN );\\nstoredValueAccountID.getEntryMode().add( EntryModeType.SCANNED );\\nstoredValueAccountID.setStoredValueID(\\\"6006491260550218066\\\");\\nstoredValueAccountID.setExpiryDate(\\\"1122\\\");\\npaymentInstrumentData.setStoredValueAccountID(storedValueAccountID);\\npaymentAccountReq.setPaymentInstrumentData(paymentInstrumentData);\\nbalanceInquiryRequest.setPaymentAccountReq(paymentAccountReq);\\nsaleToPOIRequest.setBalanceInquiryRequest(balanceInquiryRequest);\\nterminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>In the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/terminal-api\/latest\/post\/balanceinquiry#responses-200-Response\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">BalanceInquiryResponse<\/a>, check the following:<\/p>\n<ul>\n<li><code>PaymentAccountStatus.CurrentBalance<\/code>: the value of the gift card balance.<\/li>\n<li><code>PaymentAccountStatus.Currency<\/code>: the currency of the gift card balance.<\/li>\n<\/ul>\n<p>The example below indicates that the gift card has a balance of GBP&nbsp;98.75.<\/p>\n<pre><code class=\"language-json\">{\n  \"SaleToPOIResponse\":{\n    \"BalanceInquiryResponse\":{\n      \"Response\":{\n        \"Result\":\"Success\"\n      },\n      \"PaymentAccountStatus\":{\n        \"CurrentBalance\":98.75,\n          \"PaymentAcquirerData\":{\n            \"AcquirerPOIID\":\"V400m-324688179\"\n          },\n        \"Currency\":\"GBP\"\n      }\n    },\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",\n      \"SaleID\":\"POSSystemID12345\",\n      \"MessageClass\":\"Service\",\n      \"MessageCategory\":\"BalanceInquiry\",\n      \"ServiceID\":\"9266\",\n      \"POIID\":\"V400m-324688179\",\n      \"MessageType\":\"Response\"\n    }\n  }\n}<\/code><\/pre>\n<\/li>\n<\/ol>\n<h2 id=\"see-also\">See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/point-of-sale\/gift-cards-terminal-api\"\n                        target=\"_self\"\n                        >\n                    Gift cards and other stored value cards\n                <\/a><\/li><li><a href=\"\/point-of-sale\/gift-cards-terminal-api\/activate\"\n                        target=\"_self\"\n                        >\n                    Activate a gift card\n                <\/a><\/li><li><a href=\"\/point-of-sale\/gift-cards-terminal-api\/load-a-balance\"\n                        target=\"_self\"\n                        >\n                    Load funds to a gift card\n                <\/a><\/li><li><a href=\"\/point-of-sale\/gift-cards-terminal-api\/payment\"\n                        target=\"_self\"\n                        >\n                    Make a gift card payment\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/point-of-sale\/alternative-payment-methods\/gift-cards-terminal-api\/query-the-balance","articleFields":{"description":"Query the balance of a gift card at the point of sale.","id":"36196868","type":"page","_expandable":{"operations":""},"status":"current","last_edit_on":"01-10-2019 11:43"},"algolia":{"url":"https:\/\/docs.adyen.com\/point-of-sale\/alternative-payment-methods\/gift-cards-terminal-api\/query-the-balance","title":"Check the balance of a gift card","content":"You can check the funds remaining on an activated gift card, by making a balance request. This allows you to verify the gift card's value before a transaction and determine if a partial payment is needed.\nRequirements\nBefore you begin, take into account the following requirements, limitations, and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nA Terminal API integration with payment terminals.\n\n\nSetup steps\nBefore you begin:  Add the payment method to your Adyen account. Complete the onboarding process with the gift card provider. \n\n\n\nMake a balance inquiry\nTo see the funds remaining on a gift card:\n\n\nDetermine the card entry method:\n\nIf you want to scan the card, do that first and use the obtained card details in your request.\nIf 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.\n\n\n\nMake a Terminal API balance inquiry request, specifying:\n\n\nThe standard \n  SaleToPOIRequest.MessageHeader\n object, with MessageClass set to Service and MessageCategory set to BalanceInquiry.\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nProtocolVersion\n\n3.0\n\n\nMessageClass\n\nService\n\n\nMessageCategory\n\nBalanceInquiry\n\n\nMessageType\n\nRequest\n\n\nServiceID\n\nYour 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.\n\n\nSaleID\n\nYour unique ID for the POS system component to send this request from.\n\n\nPOIID\n\nThe unique ID of the terminal to send this request to. Format: [device model]-[serial number].\n\n\n\n\n\nThe  BalanceInquiryRequest.PaymentAccountReq.PaymentInstrumentData object with:\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nProtectedCardData\n\nOptional secondary security (SSC) code for SVS gift cards. The SSC allows up to 8 digits. For example, ssc=1111.  If the secondary security code is required, encode it to Base64 and pass the resulting string. For example, {\"ssc=1111\"} needs to be passed as \"ProtectedCardData\": \"eyJzc2MiOiIxMTExIn0=\"\n\n\nPaymentInstrumentType\n\nStoredValue\n\n\nStoredValueAccountID\n\nThe 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 following table.\n\n\n\n\n\n\nCard entry\nParameters\n\n\n\n\nScan\nEntryMode: ScannedStoredValueID: gift card number.ExpiryDate: expiry date of the gift card.\n\n\nSwipe\nEntryMode: MagStripeStoredValueID: include this parameter but do not provide a value.\n\n\nMKE\nEntryMode: KeyedStoredValueID: include this parameter but do not provide a value.\n\n\n\n\n\nThe example below shows how to check the balance for a scanned gift card. It includes an optional ProtectedCardData field required for stored value solution gift cards with the SSC converted to a Base64-encoded string.\n\n\n\n\n\nIn the  BalanceInquiryResponse, check the following:\n\nPaymentAccountStatus.CurrentBalance: the value of the gift card balance.\nPaymentAccountStatus.Currency: the currency of the gift card balance.\n\nThe example below indicates that the gift card has a balance of GBP&nbsp;98.75.\n{\n  \"SaleToPOIResponse\":{\n    \"BalanceInquiryResponse\":{\n      \"Response\":{\n        \"Result\":\"Success\"\n      },\n      \"PaymentAccountStatus\":{\n        \"CurrentBalance\":98.75,\n          \"PaymentAcquirerData\":{\n            \"AcquirerPOIID\":\"V400m-324688179\"\n          },\n        \"Currency\":\"GBP\"\n      }\n    },\n    \"MessageHeader\":{\n      \"ProtocolVersion\":\"3.0\",\n      \"SaleID\":\"POSSystemID12345\",\n      \"MessageClass\":\"Service\",\n      \"MessageCategory\":\"BalanceInquiry\",\n      \"ServiceID\":\"9266\",\n      \"POIID\":\"V400m-324688179\",\n      \"MessageType\":\"Response\"\n    }\n  }\n}\n\n\nSee also\n\n\n                    Gift cards and other stored value cards\n                \n                    Activate a gift card\n                \n                    Load funds to a gift card\n                \n                    Make a gift card payment\n                \n","type":"page","locale":"en","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"In-person payments","lvl2":"Alternative payment methods","lvl3":"Gift cards and other stored value cards","lvl4":"Check the balance of a gift card"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/point-of-sale","lvl2":"https:\/\/docs.adyen.com\/point-of-sale\/alternative-payment-methods","lvl3":"https:\/\/docs.adyen.com\/point-of-sale\/alternative-payment-methods\/gift-cards-terminal-api","lvl4":"\/point-of-sale\/alternative-payment-methods\/gift-cards-terminal-api\/query-the-balance"},"levels":5,"category":"In-person payments","category_color":"green","tags":["Check","balance"]},"articleFiles":{"query-the-balance_0.json":"<p alt=\"\">query-the-balance_0.json<\/p>"}}