> ## Documentation Index > Fetch the complete documentation index at: https://docs.staging.paycodefintech.net/llms.txt > Use this file to discover all available pages before exploring further. # POS Balance Enquiry > Performs a balance enquiry for a card or account through POS terminal. This endpoint allows merchants to check the available balance of a customer's card or account before processing a transaction. ## OpenAPI ````yaml post /terminals/balance-enquiry openapi: 3.0.3 info: title: Paycode - API Documentation description: > ## Get started Paycode provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. Currently, our sandbox environment is live while our production environment is under development and will be available soon. You can sign up on our Dashboard to get API keys to access Paycode API. ### Environment Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------| | Sandbox | | | Production | | ## Authentication When you sign up on our [dashboard](https://app.staging.paycodefintech.net) and create a merchant account, you are given a secret key (also referred as api-key) and a publishable key. You may authenticate all API requests with Paycode server by providing the appropriate key in the request Authorization header. | Key | Description | |-----------------|-----------------------------------------------------------------------------------------------| | api-key | Private key. Used to authenticate all API requests from your merchant server | | publishable key | Unique identifier for your account. Used to authenticate API requests from your app's client | Never share your secret api keys. Keep them guarded and secure. contact: name: Paycode Support url: https://paycodefintech.net email: Paycode@juspay.in license: name: Apache-2.0 version: 0.1.0 servers: - url: https://api.staging.paycodefintech.net description: Sandbox Environment security: [] tags: - name: Merchant Account description: Create and manage merchant accounts - name: Profile description: Create and manage profiles - name: Merchant Connector Account description: Create and manage merchant connector accounts - name: Payments description: Create and manage one-time payments, recurring payments and mandates - name: Refunds description: Create and manage refunds for successful payments - name: Mandates description: Manage mandates - name: Customers description: Create and manage customers - name: Payment Methods description: Create and manage payment methods of customers - name: Disputes description: Manage disputes - name: API Key description: Create and manage API Keys - name: Payouts description: Create and manage payouts - name: payment link description: Create payment link - name: Routing description: Create and manage routing configurations - name: Event description: Manage events - name: POS description: Point of Sale operations including balance enquiry paths: /terminals/balance-enquiry: post: tags: - POS summary: POS Balance Enquiry description: >- Performs a balance enquiry for a card or account through POS terminal. This endpoint allows merchants to check the available balance of a customer's card or account before processing a transaction. operationId: pos_balance_enquiry requestBody: content: application/json: schema: $ref: '#/components/schemas/PosBalanceEnquiryRequest' examples: Basic Balance Enquiry: value: acquirer: country: '180' id: ACQ001 card: entry_mode: '051' expiry_date: '2509' pan: '6050923334801130' sequence_number: '001' track2: 6050923334801130D25076211019450400000 cardholder: authentication: protected_pin_data: 8DA22546B6C93C95 emv_data: '82': 3c00 '95': '8000040000' 5F2A: '0976' 5F34: '00' 9A: '250720' 9C: '01' 9F02: '000000000000' 9F03: '000000000000' 9F10: >- 0fa501a23100000000000000000000000f000000000000000000000000000000 9F1A: '0180' 9F26: aac7b7d3eda149af 9F27: '80' 9F33: '604020' 9F36: 005a 9F37: 7aa214a6 merchant: category_code: '5411' id: MERCHAoNT001 name_and_location: Test Merchant, Test City network_token: f5Ce3SuoWgSVq1A5WWbg poi: id: '58100155' terminal_id: term_5QoXWYH7lR8Og5lu2Bv5 transaction_amounts: cardholder_billing_amount: '0' cardholder_billing_currency: '976' currency: '976' exchange_rate: '1.000000' total_amount: '0' transaction_id: reference: bacd required: true responses: '200': description: Balance enquiry successful content: application/json: schema: $ref: '#/components/schemas/PosBalanceEnquiryResponse' examples: Success Response: value: additional_amounts: - amount: '10500' currency: USD qualifier: LEDGER_BALANCE - amount: '500' currency: USD qualifier: HOLD_AMOUNT available_balance: 10000 currency: USD message: Balance enquiry completed successfully raw_response: null response_code: '00' status: success timestamp: '2024-01-15T10:30:05Z' transaction_id: txn_123456 '400': description: Bad Request - Invalid request parameters '401': description: Unauthorized - Invalid API key '403': description: Forbidden - Insufficient permissions '422': description: Unprocessable Entity - Validation errors '500': description: Internal Server Error security: - api_key: [] components: schemas: PosBalanceEnquiryRequest: type: object description: Request payload for POS balance enquiry required: - terminal_id - network_token - card - merchant - acquirer - poi - cardholder - transaction_amounts - transaction_id properties: terminal_id: type: string description: Terminal ID (required) network_token: type: string description: network-token card: $ref: '#/components/schemas/PosCard' merchant: $ref: '#/components/schemas/PosMerchant' acquirer: $ref: '#/components/schemas/PosAcquirer' poi: $ref: '#/components/schemas/PosPointOfInteraction' cardholder: $ref: '#/components/schemas/PosCardholder' transaction_amounts: $ref: '#/components/schemas/PosTransactionAmounts' transaction_id: $ref: '#/components/schemas/PosTransactionId' emv_data: type: object description: EMV data if available additionalProperties: type: string initiating_party: $ref: '#/components/schemas/PosInitiatingParty' additionalProperties: false PosBalanceEnquiryResponse: type: object description: Response payload for POS balance enquiry required: - transaction_id - is_successful - currency - message properties: transaction_id: type: string description: Transaction ID is_successful: type: boolean description: Status of the enquiry available_balance: type: string description: Available balance (in smallest currency unit, e.g., cents) nullable: true currency: type: string description: Currency code additional_amounts: type: array items: 582a54ac-f773-43ba-85a9-c125c92420be description: Additional amounts (e.g., ledger balance, hold amount) nullable: true timestamp: type: string format: date-time description: Response timestamp nullable: true response_code: type: string description: Response code from the payment system nullable: true message: type: string description: Response message raw_response: type: string description: Raw response from the payment system if available nullable: true PosCard: type: object description: Card Information for POS transactions properties: pan: type: string description: Primary Account Number (PAN) - either PAN or Track2 must be provided nullable: true expiry_date: type: string description: Card expiry date (YYMM format) nullable: true sequence_number: type: string description: Card sequence number nullable: true entry_mode: type: string description: Entry mode (e.g., "CHIP", "SWIPE", "CONTACTLESS") nullable: true track1: type: string description: Track 1 data if available nullable: true track2: type: string description: Track 2 data if available - either PAN or Track2 must be provided nullable: true PosMerchant: type: object description: Merchant Information for POS transactions required: - id properties: id: type: string description: Merchant ID (required) category_code: type: string description: Merchant Category Code (MCC) nullable: true name_and_location: type: string description: Merchant name and location nullable: true PosAcquirer: type: object description: Acquirer Information for POS transactions required: - id properties: id: type: string description: Acquirer ID (required) country: type: string description: Acquirer country code nullable: true PosPointOfInteraction: type: object description: Point of Interaction (Terminal) Information required: - id properties: id: type: string description: Terminal ID (required) terminal_type: type: string description: Terminal type nullable: true PosCardholder: type: object description: Cardholder Information properties: authentication: allOf: - $ref: '#/components/schemas/PosCardholderAuthentication' nullable: true PosTransactionAmounts: type: object description: Transaction Amounts Information required: - currency properties: total_amount: type: string description: Transaction amount (for balance enquiry, this might be 0) nullable: true currency: type: string description: Currency code (required) exchange_rate: type: string description: Exchange rate nullable: true cardholder_billing_amount: type: string description: Cardholder billing amount nullable: true cardholder_billing_currency: type: string description: Cardholder billing currency nullable: true PosTransactionId: type: object description: Transaction Identification required: - reference properties: sys_trace_audit_number: type: string description: System trace audit number (STAN) nullable: true transmission_date_time: type: string format: date-time description: Transmission date and time nullable: true reference: type: string description: Unique transaction reference (required) PosInitiatingParty: type: object description: Initiating Party Information properties: terminal_id: type: string description: Terminal identification nullable: true additional_info: type: string description: Additional party information nullable: true PosCardholderAuthentication: type: object description: Cardholder Authentication Data properties: protected_pin_data: type: string description: Protected PIN data nullable: true new_pin_data: type: string description: New PIN data if applicable nullable: true securitySchemes: api_key: type: apiKey in: header name: api-key description: >- Use the API key created under your merchant account from the Paycode dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application. ````