Country Lookup

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.
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, 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.

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';
}

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'

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.

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.

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

When to Use This

How It Works

Example: Route by Issuing Country

Next Steps

Country Lookup API

Metadata Lookup

​When to Use This

​How It Works

​Example: Route by Issuing Country

​Next Steps

Country Lookup API

Metadata Lookup

When to Use This

How It Works

Example: Route by Issuing Country

Next Steps