# inquireTerminal

## Overview

The `inquireTerminal` command retrieves configuration details and status information for payment terminals within your merchant account. This command provides terminal settings, capabilities, and operational status data.

## Use cases

Use `inquireTerminal` when you need to:

* Check terminal configuration settings and capabilities
* Verify terminal status and availability for transactions
* Retrieve terminal-specific parameters for payment processing
* Validate terminal setup during integration testing
* Monitor terminal operational status for maintenance purposes

## Request structure

{% hint style="info" %}
For general API request structure and authentication, see [API Request & Response General Structure](/creditguard/introduction/request-and-response-general-structure.md).
{% endhint %}

The `inquireTerminal` command uses the following endpoint:

**POST** `https://your-hyp-environment-url/xpo/Relay`

### XML request structure

```xml
<ashrait>
    <request>
        <command>inquireTerminal</command>
        <user>[username]</user>
        <password>[password]</password>
        <terminalNumber>[terminal]</terminalNumber>
    </request>
</ashrait>
```

## Required parameters

<details>

<summary><strong>user</strong> - string</summary>

Your merchant username for API authentication.

</details>

<details>

<summary><strong>password</strong> - string</summary>

Your merchant password for API authentication.

</details>

<details>

<summary><strong>terminalNumber</strong> - string</summary>

The terminal number to inquire about. This must be a valid terminal associated with your merchant account.

</details>

## Response structure

### Success response

```xml
<ashrait>
    <response>
        <result>000</result>
        <message>Success</message>
        <terminalNumber>[terminal_number]</terminalNumber>
        <terminalStatus>[active/inactive]</terminalStatus>
        <terminalType>[terminal_type]</terminalType>
        <currencySupport>[supported_currencies]</currencySupport>
        <maxAmount>[maximum_transaction_amount]</maxAmount>
        <features>[supported_features]</features>
        <lastActivity>[last_transaction_date]</lastActivity>
    </response>
</ashrait>
```

### Error response

```xml
<ashrait>
    <response>
        <result>001</result>
        <message>Terminal not found or access denied</message>
    </response>
</ashrait>
```

## Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
#!/bin/bash

# Check terminal configuration and status
curl -X POST https://your-hyp-environment-url/xpo/Relay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "cgGateway" \
  --data-urlencode "txnId=12345" \
  --data-urlencode "amount=100.00" \
  --data-urlencode "currency=ILS" \
  --data-urlencode "cardId=12345" \
  --data-urlencode "int_in=<?xml version='1.0' encoding='UTF-8'?>
<ashrait>
    <request>
        <command>inquireTerminal</command>
        <user>your_username</user>
        <password>your_password</password>
        <terminalNumber>1234567</terminalNumber>
    </request>
</ashrait>"

```

{% endtab %}

{% tab title="Python" %}

```py
import requests
import xml.etree.ElementTree as ET

def inquire_terminal(username, password, terminal_number):
    """
    Retrieve terminal configuration and status information
    """
    # Build XML request
    ashrait = ET.Element("ashrait")
    request = ET.SubElement(ashrait, "request")
    
    ET.SubElement(request, "command").text = "inquireTerminal"
    ET.SubElement(request, "user").text = username
    ET.SubElement(request, "password").text = password
    ET.SubElement(request, "terminalNumber").text = terminal_number
    
    xml_string = ET.tostring(ashrait, encoding='unicode')
    
    # Send request
    response = requests.post(
        "https://your-hyp-environment-url/xpo/Relay",
        data={
            "int_in": xml_string
        },
        headers={
            "Content-Type": "application/x-www-form-urlencoded"
        }
    )
    
    if response.status_code == 200:
        # Parse response
        root = ET.fromstring(response.text)
        result = root.find(".//result").text
        
        if result == "000":
            terminal_status = root.find(".//terminalStatus").text
            terminal_type = root.find(".//terminalType").text
            max_amount = root.find(".//maxAmount").text
            print(f"Terminal {terminal_number} Status: {terminal_status}")
            print(f"Terminal Type: {terminal_type}")
            print(f"Maximum Amount: {max_amount}")
            return {
                "success": True,
                "terminal_number": terminal_number,
                "status": terminal_status,
                "type": terminal_type,
                "max_amount": max_amount
            }
        else:
            message = root.find(".//message").text
            print(f"Error: {message}")
            return {"success": False, "error": message}
    else:
        return {"success": False, "error": f"HTTP {response.status_code}"}

# Example usage
result = inquire_terminal(
    username="your_username",
    password="your_password",
    terminal_number="1234567"
)

```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.*;

public class TerminalInquiry {
    
    public static class TerminalInfo {
        public boolean success;
        public String terminalNumber;
        public String status;
        public String type;
        public String maxAmount;
        public String error;
        
        public TerminalInfo(boolean success, String terminalNumber, String status, 
                          String type, String maxAmount, String error) {
            this.success = success;
            this.terminalNumber = terminalNumber;
            this.status = status;
            this.type = type;
            this.maxAmount = maxAmount;
            this.error = error;
        }
    }
    
    public static TerminalInfo inquireTerminal(String username, String password, String terminalNumber) {
        try {
            // Build XML request
            StringBuilder xml = new StringBuilder();
            xml.append("<?xml version='1.0' encoding='UTF-8'?>");
            xml.append("<ashrait>");
            xml.append("<request>");
            xml.append("<command>inquireTerminal</command>");
            xml.append("<user>").append(username).append("</user>");
            xml.append("<password>").append(password).append("</password>");
            xml.append("<terminalNumber>").append(terminalNumber).append("</terminalNumber>");
            xml.append("</request>");
            xml.append("</ashrait>");
            
            // Send HTTP request
            URL url = new URL("https://your-hyp-environment-url/xpo/Relay");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            conn.setDoOutput(true);
            
            String postData = "int_in=" + URLEncoder.encode(xml.toString(), "UTF-8");
            
            try (OutputStream os = conn.getOutputStream()) {
                os.write(postData.getBytes("UTF-8"));
            }
            
            // Parse response
            if (conn.getResponseCode() == 200) {
                DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                DocumentBuilder builder = factory.newDocumentBuilder();
                Document doc = builder.parse(conn.getInputStream());
                
                String result = doc.getElementsByTagName("result").item(0).getTextContent();
                
                if ("000".equals(result)) {
                    String status = doc.getElementsByTagName("terminalStatus").item(0).getTextContent();
                    String type = doc.getElementsByTagName("terminalType").item(0).getTextContent();
                    String maxAmount = doc.getElementsByTagName("maxAmount").item(0).getTextContent();
                    System.out.println("Terminal " + terminalNumber + " Status: " + status);
                    System.out.println("Terminal Type: " + type);
                    System.out.println("Maximum Amount: " + maxAmount);
                    return new TerminalInfo(true, terminalNumber, status, type, maxAmount, null);
                } else {
                    String message = doc.getElementsByTagName("message").item(0).getTextContent();
                    System.out.println("Error: " + message);
                    return new TerminalInfo(false, terminalNumber, null, null, null, message);
                }
            } else {
                return new TerminalInfo(false, terminalNumber, null, null, null, "HTTP " + conn.getResponseCode());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
            return new TerminalInfo(false, terminalNumber, null, null, null, e.getMessage());
        }
    }
    
    public static void main(String[] args) {
        TerminalInfo info = inquireTerminal(
            "your_username",
            "your_password",
            "1234567"
        );
        
        if (info.success) {
            System.out.println("Success! Terminal status: " + info.status);
        } else {
            System.out.println("Failed: " + info.error);
        }
    }
}

```

{% endtab %}

{% tab title="Node.js" %}

```js
const https = require('https');
const querystring = require('querystring');
const { DOMParser } = require('xmldom');

function inquireTerminal(username, password, terminalNumber) {
    return new Promise((resolve, reject) => {
        // Build XML request
        const xml = `<?xml version='1.0' encoding='UTF-8'?>
<ashrait>
    <request>
        <command>inquireTerminal</command>
        <user>${username}</user>
        <password>${password}</password>
        <terminalNumber>${terminalNumber}</terminalNumber>
    </request>
</ashrait>`;

        // Prepare POST data
        const postData = querystring.stringify({
            int_in: xml
        });

        // HTTP request options
        const options = {
            hostname: 'cguat2.creditguard.co.il',
            path: '/xpo/Relay',
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

        // Send request
        const req = https.request(options, (res) => {
            let responseData = '';

            res.on('data', (chunk) => {
                responseData += chunk;
            });

            res.on('end', () => {
                try {
                    // Parse XML response
                    const parser = new DOMParser();
                    const doc = parser.parseFromString(responseData, 'text/xml');
                    
                    const result = doc.getElementsByTagName('result')[0]?.textContent;
                    
                    if (result === '000') {
                        const status = doc.getElementsByTagName('terminalStatus')[0]?.textContent;
                        const type = doc.getElementsByTagName('terminalType')[0]?.textContent;
                        const maxAmount = doc.getElementsByTagName('maxAmount')[0]?.textContent;
                        console.log(`Terminal ${terminalNumber} Status: ${status}`);
                        console.log(`Terminal Type: ${type}`);
                        console.log(`Maximum Amount: ${maxAmount}`);
                        resolve({
                            success: true,
                            terminalNumber: terminalNumber,
                            status: status,
                            type: type,
                            maxAmount: maxAmount
                        });
                    } else {
                        const message = doc.getElementsByTagName('message')[0]?.textContent;
                        console.log(`Error: ${message}`);
                        resolve({
                            success: false,
                            error: message
                        });
                    }
                } catch (error) {
                    reject(error);
                }
            });
        });

        req.on('error', (error) => {
            reject(error);
        });

        // Send POST data
        req.write(postData);
        req.end();
    });
}

// Example usage
(async () => {
    try {
        const result = await inquireTerminal(
            'your_username',
            'your_password',
            '1234567'
        );
        
        if (result.success) {
            console.log('Success! Terminal status:', result.status);
        } else {
            console.log('Failed:', result.error);
        }
    } catch (error) {
        console.error('Error:', error.message);
    }
})();
```

{% endtab %}
{% endtabs %}

## Error codes

| Code | Description             | Solution                                                          |
| ---- | ----------------------- | ----------------------------------------------------------------- |
| 000  | Success                 | Terminal information retrieved successfully                       |
| 001  | Terminal not found      | Verify the terminal number is correct and belongs to your account |
| 002  | Access denied           | Check that your account has permissions for this terminal         |
| 003  | Authentication failed   | Verify username and password                                      |
| 004  | Invalid terminal number | Ensure terminal number format is correct                          |

## Related commands

* [`transmitTerminal`](/creditguard/api-reference/transmitterminal.md) - Manual settlement transmission
* [`doDeal`](/creditguard/api-reference/dodeal.md) - Process payments through terminals

## Best practices

1. **Validate terminal before transactions** - Use this command to verify terminal availability before processing payments
2. **Check terminal capabilities** - Ensure the terminal supports required features like installments or specific currencies
3. **Monitor terminal status** - Regular terminal inquiries help identify configuration issues early
4. **Verify maximum amounts** - Check transaction limits to prevent declined payments
5. **Cache terminal information** - Store terminal details to reduce API calls during high-volume processing


---

# 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://developers.hyp.co.il/creditguard/api-reference/inquireterminal.md?ask=<question>
```

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.