# Balance Enquiry ## Query the balance on a card > This retrieves the current balance on a gift/prepaid card. ```json {"openapi":"3.0.0","info":{"title":"Verifone eCommerce API","version":"2.38.1"},"servers":[{"url":"https://emea.gsc.verifone.cloud/oidc","description":"EMEA Production"},{"url":"https://us.gsc.verifone.cloud/oidc","description":"Americas Production"},{"url":"https://nz.gsc.verifone.cloud/oidc","description":"New Zealand Production"},{"url":"https://cst.test-gsc.vfims.com/oidc","description":"Global Sandbox"},{"url":"https://uscst-gb.gsc.vficloud.net/oidc","description":"Americas Sandbox"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"EncryptedCardBalancePaymentRequest":{"type":"object","properties":{"payment_provider_contract":{"type":"string","description":"The identifier of payment provider contract you want to process the transaction request with.","format":"uuid-flexible","title":"paymentProviderContractId"},"customer":{"type":"string","description":"The ID of a customer.","format":"uuid-flexible","title":"Customer ID"},"dynamic_descriptor":{"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on bank statement of the customer. Please refer to the integration guide for the format requirements.","maxLength":25,"title":"Dynamic Descriptor"},"invoice_number":{"type":"string","title":"Invoice Number","description":"Optional. The invoice number to track this payment.","maxLength":127},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50,"title":"Merchant Reference"},"shopper_interaction":{"type":"string","description":"Determines the sales channel the shopper gives their card details through:\n\n * `ECOMMERCE` Online transactions where the cardholder is present.\n\n * `MAIL` order transactions where the shopper is in contact with the merchant via email.\n\n * `TELEPHONE` order transactions where the shopper is in contact with the merchant via telephone.","enum":["ECOMMERCE","MAIL","TELEPHONE","PHONE"],"default":"ECOMMERCE","title":"Ecommerce Shopper Interaction"},"currency_code":{"type":"string","title":"Currency Code","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD.\nValues correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). \n\n **Deprecated :** `BYR` (replaced by BYN), `FRF` (replaced by EUR), `LTL` (replaced by EUR), `LVL` (replaced by EUR), `MRO` (replaced by MRU), `STD` (replaced by STN), `USS` (no replacement), `VEF` (replaced by VES), `ZMK` (replaced by ZMV) and `BTC` (Bitcoin only supported as Crypto Amount).","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","FRF","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LVL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","USS","UYI","UYU","UYW","UZS","VEF","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMK","ZMW","ZWL","BTC"]},"card_brand":{"$ref":"#/components/schemas/CardBrand"},"encrypted_card":{"type":"string","title":"Client encrypted cardholder data","description":"The cardholder data encrypted using the Verifone provided public key. This can be obtained using either Verifone.JS solution or Verifone Checkout in capture mode.\n\n The data to encrypt is a JSON with possible tags being cardNumber, sequenceNumber, cardholderName, startMonth, startYear, expiryMonth, expiryYear, cvv. \n\n Additionally a tag called captureTime must be presenting indicating the time the card was captured in UTC in format RFC 3339, section 5.6. eg. 2019-08-24T14:15:22Z \n\n Sample JSON to encrypt: \n \n {\n \"cardNumber\": \"4929123123123127\",\n \"cardholderName\": \"MR J HOLDER\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"2021\",\n \"cvv\": \"123\",\n \"svcAccessCode\": \"4848448\",\n \"captureTime\": \"2019-08-24T14:15:22Z\"\n }"},"public_key_alias":{"type":"string","title":"Public Key Alias","description":"The alias for the public key used to encrypt this card. \n card/cvv/svc access code."},"token_preference":{"allOf":[{"$ref":"#/components/schemas/TokenPreferenceDto","title":"Token Preference","description":"Contains the properties required to create a token"}]},"pay_with_points":{"$ref":"#/components/schemas/payWithPoint"}},"required":["payment_provider_contract","currency_code","encrypted_card","public_key_alias"]},"CardBrand":{"type":"string","title":"The Card Type","description":"Represents a Card type or brand. It should correspond to a consistent name, the list of standard names is as follows:\n\nValue | Description\n------|-------------\nAMEX|American Express\nCB|Carte Bancaires\nDINERS|Diners Club International\nDISCOVER|Diners Club Discover\nJCB|Japan Credit Bureau\nMAESTRO|Multi-national Debit (MasterCard)\nMASTERCARD|MasterCard\nVISA|Visa\nUPI|Union Pay International\nGIFT_CARD|Gift Card (Generic)\nPLCC|Private Label Credit Card\n**Other local schemes as applicable**. Enter a pre-defined name to represent the scheme or type. \n**Note**: 1. For gift cards, card brand is mandatory and the value should be GIFT_CARD.\n2. This parameter is mandatory for dual branded cards."},"TokenPreferenceDto":{"type":"object","properties":{"token_scope":{"type":"string","title":"Token Scope","description":"The token scope under which this token was created.","format":"uuid"},"reuse_token_type":{"title":"Reuse Token Type","description":"The type of Reuse Token. This indicates if the reuse token is an internal Verifone type or an external Third-Party type.
\n**Note**: `reuse_token_details` is **mandatory** when `reuse_token_type` is set to `TAVE` or `CHASE`.\n","type":"string","enum":["CHASE","INTERNAL","TAVE"],"default":"INTERNAL"},"token_type":{"type":"string","title":"Token Type","description":"Token type","enum":["REUSE","ANALYTICS","REUSE_AND_ANALYTICS"]},"token_expiry_date":{"type":"string","description":"When this Token will expire.","format":"date"}},"required":["token_scope"]},"payWithPoint":{"title":"Pay With Points","type":"object","description":"Points usage and balance might be part of the transaction request. This object will hold flags and details that is related to points. Use-cases are:
  • Whether transaction should be paid using loyalty points/reward points or other type of point
  • Points redemption order request
  • Points balance request
    • ","additionalProperties":false,"properties":{"enabled":{"description":"Flag to indicate whether to use points or not.","type":"boolean","default":false},"points_type":{"type":"string","title":"Points Type","description":"Type or name of the points program.","enum":["AMEX"],"default":"AMEX"},"points_transaction_reference":{"type":"string","title":"Points Transaction Reference","description":"Unique transaction reference to the related card transaction."},"points_transaction_reference_type":{"type":"string","title":"Points Transaction Reference Type","description":"Type of the transaction reference.\n* `AUTH_CODE` The authorisation response code received from issuer/acquirer (as used in the ISO8583 specification (DE 38))"},"points_to_redeem":{"type":"string","title":"Points Amount","description":"An amount type represented in points for all fields like points balance, points redemption, etc. when a points program is applicable in a transaciton or a query.","maxLength":32,"pattern":"^(([0-9]+)|(([0-9]+)?[.][0-9]+))$"},"total_basket_amount":{"description":"The total basket amount decimal place e.g. $1.5 = 150.\n\nThe required number of decimal places for a currency code is according to ISO 4217. However the following table takes precedence over ISO 4217:\n\n| Code | Currency | Decimals | Fixed minor units |\n| ---- | ------------- | -------- | ----------------- |\n| ISK | Iceland Krona | 2 | 00 |","type":"integer"}},"required":["enabled","pointsType"]},"ReuseTokenCardBalancePaymentRequest":{"type":"object","properties":{"payment_provider_contract":{"type":"string","description":"The identifier of payment provider contract you want to process the transaction request with.","format":"uuid-flexible","title":"paymentProviderContractId"},"customer":{"type":"string","description":"The ID of a customer.","format":"uuid-flexible","title":"Customer ID"},"dynamic_descriptor":{"type":"string","description":"A short [descriptor](https://en.wikipedia.org/wiki/Billing_descriptor) to be shown on bank statement of the customer. Please refer to the integration guide for the format requirements.","maxLength":25,"title":"Dynamic Descriptor"},"invoice_number":{"type":"string","title":"Invoice Number","description":"Optional. The invoice number to track this payment.","maxLength":127},"merchant_reference":{"type":"string","description":"A reference specified by the merchant to identify the transaction.","maxLength":50,"title":"Merchant Reference"},"shopper_interaction":{"type":"string","description":"Determines the sales channel the shopper gives their card details through:\n\n * `ECOMMERCE` Online transactions where the cardholder is present.\n\n * `MAIL` order transactions where the shopper is in contact with the merchant via email.\n\n * `TELEPHONE` order transactions where the shopper is in contact with the merchant via telephone.","enum":["ECOMMERCE","MAIL","TELEPHONE","PHONE"],"default":"ECOMMERCE","title":"Ecommerce Shopper Interaction"},"currency_code":{"type":"string","title":"Currency Code","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD.\nValues correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). \n\n **Deprecated :** `BYR` (replaced by BYN), `FRF` (replaced by EUR), `LTL` (replaced by EUR), `LVL` (replaced by EUR), `MRO` (replaced by MRU), `STD` (replaced by STN), `USS` (no replacement), `VEF` (replaced by VES), `ZMK` (replaced by ZMV) and `BTC` (Bitcoin only supported as Crypto Amount).","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYN","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","FRF","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LVL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MRU","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","USS","UYI","UYU","UYW","UZS","VEF","VES","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMK","ZMW","ZWL","BTC"]},"card_brand":{"$ref":"#/components/schemas/CardBrand"},"reuse_token":{"type":"string","title":"Verifone or Third-Party Reuse Token","description":"The Verifone or Third-Party issued reuse token used to represent the previously stored cardholder data. Required here if not referenced by providing the stored credential signup reference `stored_credential.reference` in a subsequent charge request.","minLength":14,"maxLength":255},"reuse_token_type":{"type":"string","title":"Reuse Token Type","description":"The type of Reuse Token. This indicates if the reuse token is an internal Verifone type or an external Third-Party type.
    \n**Note**: `reuse_token_details` is **mandatory** when `reuse_token_type` is set to `TAVE` or `CHASE`.\n","enum":["INTERNAL","CHASE","TAVE"],"default":"INTERNAL"},"reuse_token_details":{"$ref":"#/components/schemas/TokenDetailsRequestBody"},"encrypted_svc_access_code":{"type":"string","title":"Client encrypted SVC Access Code","description":"The SVC Access Code encrypted using the Verifone provided public key. This can be obtained using either Verifone.JS solution or Verifone Checkout in capture mode.\n\nThe data to encrypt is a JSON with tag svcAccessCode.\n\nAdditionally a tag called captureTime must be presenting indicating the time the cvv was captured in UTC in format RFC 3339, section 5.6. eg. 2019-08-24T14:15:22Z.\n\nSample JSON to encrypt:\n \n {\n \"svcAccessCode\": \"484848\"\n \"captureTime\": \"2023-02-27T14:15:22Z\"\n }\n \n \n\n **Required for Stored Value Cards.**"},"public_key_alias":{"type":"string","title":"Public Key Alias","description":"The alias for the public key used to encrypt this card. \n card/cvv/svc access code."},"pay_with_points":{"$ref":"#/components/schemas/payWithPoint"}},"required":["payment_provider_contract","currency_code","reuse_token"]},"TokenDetailsRequestBody":{"title":"Reuse Token Details","type":"object","properties":{"expiry_month":{"maximum":12,"type":"integer","description":"A 2 digit value as shown on card. ISO8583 - DE 14.\\n\\nThis is included as an optional value to be used for some Third-Party reuse token types."},"expiry_year":{"maximum":9999,"type":"integer","description":"A 4 digit value as shown on card.\\n\\nThis is included as an optional value to be used for some Third-Party reuse token types."}},"additionalProperties":false,"description":"The details related to the token. For Third-Party Reuse tokens, these elements might be required as additional information together with the Reuse token itself.
    \n**Note**: `reuse_token_details` is **mandatory** when `reuse_token_type` is set to `TAVE` or `CHASE`.\n"},"BalanceEnquiryResponse":{"type":"object","properties":{"id":{"type":"string","title":"Transaction ID","format":"uuid-flexible","description":"The ID of the transaction."},"balance_amount":{"type":"integer","title":"balanceAmount","description":"Balance amount is the amount remaining on a card or account of cardholder without a decimal place e.g. $1.5 = 150. \n\n The required number of decimal places for a currency code is according to ISO 4217. However the following table takes precedence over ISO 4217: \n\nCode | Currency | Decimals | Fixed minor units\n------|-------------|-----------|-----------\nISK|Iceland krona|2|00\n\n For Account Verification transactions, provide 0 as value for this field."},"balance_points":{"description":"An Array containing result of querying balance for different kinds of points","type":"array","items":{"$ref":"#/components/schemas/BalancePoints"}},"created_at":{"type":"string","description":"The time at which the transaction was created.","format":"date-time"},"customer":{"type":"string","description":"The ID of a customer"},"invoice_number":{"type":"string","title":"Invoice Number","description":"Optional. The invoice number to track this payment.","maxLength":127},"merchant_reference":{"type":"string","title":"merchantReference","description":"A reference specified by the merchant to identify the transaction","maxLength":50},"processor":{"type":"string","description":"The name of the processor used for this transaction"},"processor_reference":{"type":"string","description":"Reference identifying the transaction, as provided by the processor."},"processor_details":{"type":"object","description":"Stores all details specific for the processor of the transaction."},"status":{"type":"string","title":"Ecommerce Transaction Status","description":"The outcome of the payment request.","enum":["INITIATED","AUTHORIZED","AUTHORIZATION_VOIDED","REFUNDED","FAILED","PENDING","DECLINED","CANCELLED","SETTLEMENT_CANCELLED","SETTLEMENT_REQUESTED","SETTLEMENT_SUBMITTED","SETTLEMENT_COMPLETED","SETTLEMENT_PARTIAL","SETTLEMENT_DECLINED","CUSTOMER_ACCEPTED","VOIDED","UNKNOWN"]},"status_reason":{"type":"string","description":"Message provided by the 3rd party service as additional information, when the transaction does not succeed."},"reason_code":{"type":"string","description":"A reason code assigned by the acquiring platform; '0000' in case of success","maxLength":4},"arn":{"type":"string","title":"Acquirer reference number","description":"Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions."},"authorization_code":{"type":"string","title":"authorizationCode","description":"Authorization code: \n\n * When the payment is authorized successfully, this field holds the authorisationCode code for the payment.\n\n* When the payment is not authorized, this field is not returned.","maxLength":6},"rrn":{"type":"string","title":"referenceId","maxLength":12,"description":"A client (user friendly) identifier for the transaction generated at the outset of a business event. The format will be dependent on the calling system.\n\n A reference supplied by the system retaining the original source information and used to assist in locating that transaction or a copy of the transaction. This value is critical in matching values that are sent to other Payment processors or Acquirers. This value would correspond to the ISO8583 specification as RRN in attribute DE 37, which limits the value to being an alphanumeric value 12 characters.\n \n For the GSC client android application the format will correspond to YYMMdd."},"shopper_interaction":{"type":"string","title":"Ecommerce Shopper Interaction","description":"Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth","enum":["ecommerce","pos","moto","mail_order","cont_auth","telephone_order","unknown"]},"stan":{"type":"number","description":"System Trace Audit Number."},"token_details":{"allOf":[{"$ref":"#/components/schemas/TokenDetails","description":"This object is returned as the response to a request for Create/Update Token."}]},"card_details":{"allOf":[{"$ref":"#/components/schemas/CardDetails"}]},"additional_data":{"$ref":"#/components/schemas/AdditionalData"}}},"BalancePoints":{"type":"object","title":"Points Details","properties":{"points_type":{"type":"string","description":"Type or name of the points program","title":"Points Type","enum":["AMEX"]},"balance_points":{"type":"string","description":"An amount type represented in points for all fields like points balance, points redemption, etc. when a points program is applicable in a transaciton or a query.","title":"Points Amount","maxLength":32,"pattern":"^(([0-9]+)|(([0-9]+)?[.][0-9]+))$"},"identifier":{"type":"string","description":"Identifier associated with the points balance. E.g points_id, account_id."},"points_transaction_reference":{"type":"string","description":"Unique transaction reference to the related card transaction.","title":"Points Transaction Reference"},"points_transaction_reference_type":{"type":"string","title":"Points Transaction Reference Type","description":"Type of the transaction reference.\n* `AUTH_CODE` The authorisation response code received from issuer/acquirer (as used in the ISO8583 specification (DE 38))"},"points_conversion_rate":{"type":"number","description":"The points conversion rate.","title":"Points Conversion Rate","format":"float"},"min_reward_amount":{"description":"Minimum reward amount to spend with points without a decimal place e.g. $1.5 = 150.\n\nThe required number of decimal places for a currency code is according to ISO 4217.","type":"integer"},"max_reward_amount":{"description":"Maximum reward amount to spend with points without a decimal place e.g. $1.5 = 150.\n\nThe required number of decimal places for a currency code is according to ISO 4217.","type":"integer"}},"required":["points_type"]},"TokenDetails":{"type":"object","properties":{"reuse_token":{"type":"string","description":"The Verifone issued reuse token used to represent the previously stored cardholder data.","minLength":14,"maxLength":255},"reuse_token_type":{"title":"Reuse Token Type","description":"The type of Reuse Token. This indicates if the reuse token is an internal Verifone type or an external Third-Party type.","type":"string","enum":["CHASE","INTERNAL","TAVE"]},"analytics_token":{"type":"string","description":"A token that cannot be reversed to Card Holder data. This is included in a Payment for auditing and tracking purposes."},"token_expiry_date":{"type":"string","format":"date","description":"When this Token will expire."},"token_scope":{"type":"string","format":"uuid","description":"The token scope under which this token was created."},"token_status":{"type":"string","enum":["DELETED","ACTIVE","SUSPENDED"],"description":"The status of the Token."},"created_at":{"type":"string","format":"date","description":"The date when this token was first created."},"updated_at":{"type":"string","format":"date","description":"The last date token was updated."},"variant":{"type":"string","description":"The variant of the card. eg. NEW_WORLD"},"type":{"type":"string","enum":["CREDIT","DEBIT"],"description":"The type of card application or account selection."},"issuer_name":{"type":"string","description":"The issuer of this card. eg. HSBC, BARCLAYS."},"issuer_country":{"$ref":"#/components/schemas/issuerCountryEnum"},"brand":{"type":"string","description":"The brand of this card. eg. VISA, MASTERCARD, AMEX."},"expiry_year":{"type":"integer","description":"A 4 digit value as shown on card.","maximum":9999},"expiry_month":{"type":"integer","description":"A 2 digit value as shown on card. ISO8583 - DE 14","maximum":12},"card_holder_name":{"type":"string","description":"The Card holder name as it appears on the card.","maxLength":30},"last_four":{"type":"string","description":"The last 4 digits of the card number.","maxLength":4},"bin":{"type":"string","description":"The Bank Identification Number (also called IIN - Issuer Identification Number) of this card.","minLength":4,"maxLength":11},"currency_code":{"type":"string","title":"Currency Code","description":"Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LVL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","USS","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XTS","XXX","YER","ZAR","ZMK","ZMW","BTC"]}}},"issuerCountryEnum":{"type":"string","description":"The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code.
    Note: The country code for Great Britain is GB and not UK as is used in that country's top-level domain names.
    .","enum":["ZZZ","ABW","AFG","AGO","AIA","ALA","ALB","AND","ARE","ARG","ARM","ASM","ATA","ATF","ATG","AUS","AUT","AZE","BDI","BEL","BEN","BES","BFA","BGD","BGR","BHR","BHS","BIH","BLM","BLR","BLZ","BMU","BOL","BRA","BRB","BSB","BRN","BTN","BVT","BWA","CAF","CAN","CCK","CHE","CHL","CHN","CIV","CMR","COD","COG","COK","COL","COM","CPV","CRI","CUB","CUW","CXR","CYM","CYP","CZE","DEU","DJI","DMA","DNK","DOM","DZA","ECU","EGY","ERI","ESH","ESP","EST","ETH","FIN","FJI","FLK","FRA","FRO","FSM","GAB","GBR","GEO","GGY","GHA","GIB","GIN","GLP","GMB","GNB","GNQ","GRC","GRD","GRL","GTM","GUF","GUM","GUY","HKG","HMD","HND","HRV","HTI","HUN","IDN","IMN","IND","IOT","IRL","IRN","IRQ","ISL","ISR","ITA","JAM","JEY","JOR","JPN","KAZ","KEN","KGZ","KHM","KIR","KNA","KOR","KWT","LAO","LBN","LBR","LBY","LCA","LIE","LKA","LSO","LTU","LUX","LVA","MAC","MAF","MAR","MCO","MDA","MDG","MDV","MEX","MHL","MKD","MLI","MLT","MMR","MNE","MNG","MNP","MOZ","MRT","MSR","MTQ","MUS","MWI","MYS","MYT","NAM","NCL","NER","NFK","NGA","NIC","NIU","NLD","NOR","NPL","NRU","NZL","OMN","PAK","PAN","PCN","PER","PHL","PLW","PNG","POL","PRI","PRK","PRT","PRY","PSE","PYF","QAT","REU","ROU","RUS","RWA","SAU","SDN","SEN","SGC","SGP","SHN","SJM","SLB","SLE","SLV","SMR","SOM","SPM","SRB","SSD","STP","SUR","SVK","SVN","SWE","SWZ","SXM","SYC","SYR","TCA","TCD","TGO","THA","TJK","TKL","TKM","TLS","TON","TTO","TUN","TUR","TUV","TWN","TZA","UGA","UKR","UMI","URY","USA","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT","WLF","WSM","YEM","ZAF","ZMB","ZWE"]},"CardDetails":{"type":"object","properties":{"masked_card_number":{"type":"string","title":"Masked Card Number","description":"The masked value for the card number"},"expiry_year":{"type":"integer","title":"Expiry Year","description":"A 4 digit value as shown on card."},"expiry_month":{"type":"integer","title":"Expiry Month","description":"A 2 digit value as shown on card. ISO8583 - DE 14"}}},"AdditionalData":{"type":"object","additionalProperties":false,"description":"Additional payment result data, which may be required to return in a particular payment response.","properties":{"acquirer_response_code":{"$ref":"#/components/schemas/acquirerResponseCode"},"acquirer_response_message":{"$ref":"#/components/schemas/acquirerResponseMessage"},"acquirer_authorizing_network_id":{"$ref":"#/components/schemas/acquirerAuthorizingNetworkID"},"acquirer_authorizing_network_id_descriptor":{"$ref":"#/components/schemas/acquirerAuthorizingNetworkIdDescriptor"},"initiator_trace_id":{"$ref":"#/components/schemas/initiatorTraceId"},"settlement_date":{"$ref":"#/components/schemas/settlementDate"},"issuer_receipt_text":{"type":"string","description":"Additional text to print on transaction receipt, which optionally may be provided by the Issuer."}}},"acquirerResponseCode":{"description":"Acquirer response returned during the authorisation.","type":"string","maxLength":4},"acquirerResponseMessage":{"description":"The response description generated by the acquirer corresponding to the acquirer response code.","type":"string"},"acquirerAuthorizingNetworkID":{"description":"The Network ID returned in the original authorization response.","type":"string"},"acquirerAuthorizingNetworkIdDescriptor":{"description":"The name or descriptor that corresponds with the `acquirer_authorizing_network_id` returned in the original authorization response.","type":"string"},"initiatorTraceId":{"description":"A number assigned by a transaction initiator(originator) to assist in identifying a transaction uniquely. The trace identifier remains unchanged for all messages within a two-message exchange, e.g. request/repeat and response. This property can be used to store the System trace audit number (STAN) as used in the ISO8583 specification (DE 11). Note the contents of this field are mandatory in many specifications - ISO8583, AS2805 (DE11) and are often related to the Retrieval Reference Number (RRN) as also specified in ISO8583. Unfortunately due to the usage in these earlier specifications, a STAN was limited to 6 digits which means that it cannot be utilised as a general purpose unique id. In addition, this entry is often printed on the receipt at a POI.\n This value will correspond to **ISO8583 DE11.**\n `Note: Use response.stan value for initiator_trace_id`","type":"string","maxLength":40,"deprecated":true},"settlementDate":{"description":"This will reflect either the desired Merchant settlement date or the actual settlement date depending where the transaction request is within the payment lifecycle. A transaction may be assigned an intended settlement date, but it is possible that this date will not occur for technical reasons hence there should be a subsequent event to indicate the actual date of settlement. Format is date only as per RFC 3339.","type":"string","format":"date"},"BadRequestV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[400],"default":400},"message":{"type":"string","enum":["At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."],"default":"At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the requests body, query for parameters appended to the requests URL, and params for templated parameters of the requests URL."}},"required":["message"]},"UnauthorizedV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[401],"default":401},"message":{"type":"string","enum":["Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."],"default":"Access is restricted to authenticated users only. The query can't be made without a valid JWT token (check the Authorization header of your request)."}},"required":["message"]},"ForbiddenV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[403],"default":403},"message":{"type":"string","enum":["Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."],"default":"Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator."}},"required":["message"]},"NotFoundV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[404],"default":404},"message":{"type":"string","enum":["The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."],"default":"The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights."}},"required":["message"]},"InternalErrorV2Docs":{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"object"}},"timestamp":{"type":"number","description":"Error timestamp"},"reversal_status":{"type":"string","description":"Indicates to the API client if a technical reversal has been completed by Verifone.","default":"NONE","enum":["NONE","REQUIRED","COMPLETED"]},"code":{"type":"number","enum":[500],"default":500},"message":{"type":"string","enum":["Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"],"default":"Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error"}},"required":["message"]}}},"paths":{"/api/v2/transactions/balance":{"post":{"operationId":"BalanceEnquiry","summary":"Query the balance on a card","description":"This retrieves the current balance on a gift/prepaid card.","parameters":[{"name":"x-vfi-api-idempotencykey","required":false,"in":"header","description":"Example: 63bbc548-d2de-4546-b106-880a5018461c \n\n A value you specify that uniquely identifies this transaction. This must be used to trigger a reversal if there is a timeout.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The card Balance Payment Request, using either, the encrypted cardholder data or the reuse token to represent card data.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EncryptedCardBalancePaymentRequest"},{"$ref":"#/components/schemas/ReuseTokenCardBalancePaymentRequest"}]}}}},"responses":{"201":{"description":"The Card Balance Enquiry Response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceEnquiryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestV2Docs"}}}},"401":{"description":"Unauthorised","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedV2Docs"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenV2Docs"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundV2Docs"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorV2Docs"}}}}},"tags":["Balance Enquiry"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verifone.com/api-reference/open-api-references/ecommerce/balance-enquiry.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.