> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Country Lookup

> Identify the issuing country of a card from its BIN.

The Country Lookup endpoint identifies the country that issued a card, from the card's BIN/IIN, and returns the ISO 3166 country code.

**Endpoint:** `GET /Tools/country`

## When to Use This

Use Country Lookup when the issuing country changes what your checkout should do. Common cases:

* **Routing.** Sending a card to the gateway account that covers its region, which is the core of a [multi-gateway setup](/guides/rest-api/multi-gateway-failover).
* **Regulation.** Deciding whether a transaction falls under rules that apply to a particular region, such as European authentication requirements.
* **Pricing and presentment.** Choosing the currency or the tax treatment to show before the customer commits.
* **Risk.** Comparing the issuing country with the billing or shipping address.

This is lighter than the full [Metadata Lookup](/guides/rest-api/utilities/card-tools/metadata-lookup), which returns the country alongside everything else known about the BIN. Use Country Lookup when the country is all you need.

## How It Works

Pass the first 6 to 11 digits of the card number as the `iin` query parameter. The endpoint returns the ISO 3166 alpha-2 code for the issuing country in a `countryCode` field.

| Parameter | Type           | Required | Description                                 |
| --------- | -------------- | -------- | ------------------------------------------- |
| `iin`     | string (query) | Yes      | The first 6 to 11 digits of the card number |

## Example: Route by Issuing Country

Look the country up once the customer has entered enough digits, then pick the gateway account that serves that region.

<CodeGroup>
  ```javascript Node.js theme={null}
  async function getIssuingCountry(cardDigits, apiKey) {
    const response = await fetch(
      `https://api.orchestrasolutions.com/Tools/country?iin=${cardDigits.substring(0, 8)}`,
      { headers: { 'X-Api-Key': apiKey } }
    );

    if (!response.ok) return null;
    return response.json();
  }

  const EU = ['AT', 'BE', 'DE', 'ES', 'FI', 'FR', 'IE', 'IT', 'NL', 'PT'];

  async function chooseGatewayAccount(cardDigits, apiKey) {
    const result = await getIssuingCountry(cardDigits, apiKey);
    const country = result?.countryCode;

    if (!country) return 'default-account';
    return EU.includes(country) ? 'eu-account' : 'global-account';
  }
  ```

  ```python Python theme={null}
  import requests

  EU = {'AT', 'BE', 'DE', 'ES', 'FI', 'FR', 'IE', 'IT', 'NL', 'PT'}

  def get_issuing_country(card_digits, api_key):
      """Return the ISO 3166 country code for the card's BIN."""
      response = requests.get(
          'https://api.orchestrasolutions.com/Tools/country',
          params={'iin': card_digits[:8]},
          headers={'X-Api-Key': api_key}
      )
      response.raise_for_status()
      return response.json()

  def choose_gateway_account(card_digits, api_key):
      country = get_issuing_country(card_digits, api_key).get('countryCode')
      if not country:
          return 'default-account'
      return 'eu-account' if country in EU else 'global-account'
  ```
</CodeGroup>

<Tip>
  Pass 8 digits where you have them. Six is the minimum, but longer prefixes resolve more card ranges correctly, since many issuers now sit inside 8-digit BIN ranges.
</Tip>

<Note>
  A BIN identifies the issuer, not the cardholder. A customer living in one country can carry a card issued in another, so treat the issuing country as a routing and risk signal rather than as the customer's location.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Country Lookup API" icon="code" href="/api-reference/tools/country-lookup">
    Endpoint reference.
  </Card>

  <Card title="Metadata Lookup" icon="circle-info" href="/guides/rest-api/utilities/card-tools/metadata-lookup">
    Everything known about a BIN, including the country.
  </Card>
</CardGroup>