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

# Metadata Lookup

> Get full card metadata including brand, type, category, issuer, and country from the BIN.

The Metadata Lookup endpoint returns the full metadata for a card based on its BIN/IIN. This includes the card brand, type (credit/debit), category, issuing organization, country of issue, and a brand logo URL.

**Endpoint:** `GET /Tools/iin`

## When to Use This

Use Metadata Lookup when you need detailed card information to make decisions before processing a payment. The most common use case is **BIN-based routing**, directing transactions to different payment gateways based on the card's issuer country, brand, or type.

For example, a travel company operating across regions might route cards issued in Morocco through a local PSP (e.g., Payzone) for better approval rates, while routing all other cards through a global PSP (e.g., Stripe).

## How It Works

Pass the first 6 to 11 digits of the card number as the `iin` query parameter. The endpoint returns the full metadata record for that BIN range.

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

### Response Fields

| Field                 | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `bin`                 | The matched BIN prefix (6–11 digits)                       |
| `cardBrand`           | Card brand (VISA, MASTERCARD, AMERICAN EXPRESS, JCB, etc.) |
| `cardType`            | Card type (CREDIT, DEBIT, DEBIT OR CREDIT, CHARGE CARD)    |
| `category`            | Card category (CLASSIC, GOLD, PLATINUM, BUSINESS, etc.)    |
| `issuingOrganization` | Name of the issuing bank                                   |
| `countryCode`         | ISO 3166-2 two-letter country code of the issuer           |
| `brandLogoUrl`        | URL to the brand logo image                                |

## Example: BIN-Based Payment Routing

Route payments to different PSPs based on the card's issuer country to optimize approval rates and processing costs.

<CodeGroup>
  ```javascript Node.js theme={null}
  async function selectGateway(cardNumber, apiKey) {
    const iin = cardNumber.replace(/\D/g, '').substring(0, 8);

    const response = await fetch(
      `https://api.orchestrasolutions.com/Tools/iin?iin=${iin}`,
      { headers: { 'X-Api-Key': apiKey } }
    );
    const { countryCode, cardBrand } = await response.json();

    // Route Moroccan cards to a local PSP for better approval rates
    if (countryCode === 'MA') {
      return 'payzone-morocco';
    }

    // Route Amex through a gateway with better Amex rates
    if (cardBrand === 'AMERICAN EXPRESS') {
      return 'amex-preferred-gateway';
    }

    return 'stripe-default';
  }
  ```

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

  def select_gateway(card_number, api_key):
      """Choose the best PSP based on card metadata."""
      iin = card_number.replace(' ', '')[:8]

      response = requests.get(
          'https://api.orchestrasolutions.com/Tools/iin',
          params={'iin': iin},
          headers={'X-Api-Key': api_key}
      )
      response.raise_for_status()
      meta = response.json()

      if meta['countryCode'] == 'MA':
          return 'payzone-morocco'

      if meta['cardBrand'] == 'AMERICAN EXPRESS':
          return 'amex-preferred-gateway'

      return 'stripe-default'
  ```

  ```bash cURL theme={null}
  curl "https://api.orchestrasolutions.com/Tools/iin?iin=411111" \
    -H "X-Api-Key: YOUR_API_KEY"

  # Response:
  # {
  #   "bin": "411111",
  #   "cardBrand": "VISA",
  #   "cardType": "CREDIT",
  #   "category": "CLASSIC",
  #   "issuingOrganization": "JPMORGAN CHASE BANK, N.A.",
  #   "countryCode": "US",
  #   "brandLogoUrl": "https://..."
  # }
  ```
</CodeGroup>

## Related

<CardGroup cols={2}>
  <Card title="Brand Lookup" icon="credit-card" href="/guides/rest-api/utilities/card-tools/brand-lookup">
    Only need the brand? Use the lighter Brand Lookup endpoint.
  </Card>

  <Card title="Multi-Gateway Failover" icon="arrows-split-up-and-left" href="/guides/rest-api/multi-gateway-failover">
    Combine BIN routing with gateway failover for maximum reliability.
  </Card>
</CardGroup>