Skip to main content

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.

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.
ParameterTypeRequiredDescription
iinstring (query)YesThe first 6 to 11 digits of the card number

​
Response Fields

FieldDescription
binThe matched BIN prefix (6–11 digits)
cardBrandCard brand (VISA, MASTERCARD, AMERICAN EXPRESS, JCB, etc.)
cardTypeCard type (CREDIT, DEBIT, DEBIT OR CREDIT, CHARGE CARD)
categoryCard category (CLASSIC, GOLD, PLATINUM, BUSINESS, etc.)
issuingOrganizationName of the issuing bank
countryCodeISO 3166-2 two-letter country code of the issuer
brandLogoUrlURL 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. 
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';
}

Brand Lookup

Only need the brand? Use the lighter Brand Lookup endpoint.

Multi-Gateway Failover

Combine BIN routing with gateway failover for maximum reliability.