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 Card Validation endpoint performs a risk assessment by comparing the card’s BIN metadata (issuer country) against the payer’s billing address and IP geolocation. It returns a risk level along with the full card metadata and the detected countries from each data source. Endpoint: POST /Tools/validate

​
When to Use This

Use Card Validation as a pre-transaction fraud screening step. By comparing where the card was issued, where the payer claims to be (billing address), and where they actually are (IP geolocation), you can flag suspicious transactions before they reach the PSP. For example, a card issued in Germany being used from an IP address in Nigeria with a billing address in the US would produce a high risk score — an indication that the transaction warrants additional scrutiny or rejection.

​
How It Works

Pass the card’s BIN/IIN as a query parameter and the payer’s billing details in the request body. Query parameter:
ParameterTypeRequiredDescription
iinstringYesThe first 6 to 11 digits of the card number
Request body:
FieldTypeRequiredDescription
clientIPAddressstringYesThe payer’s IP address
countryCodestringYesISO 3166-2 two-letter country code from billing address
citystringNoBilling city
stateProvincestringNoBilling state or province

​
Risk Levels

LevelMeaning
VeryLowCard issuer country, IP country, and billing country all match
LowMinor discrepancy between data points
HighSignificant mismatch between card origin and payer location
VeryHighMultiple mismatches or anonymous proxy detected

​
Example: Pre-Transaction Fraud Check

Screen transactions before processing and flag high-risk payments for manual review. 
async function assessRisk(cardBin, payerInfo, apiKey) {
  const response = await fetch(
    `https://api.orchestrasolutions.com/Tools/validate?iin=${cardBin}`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        clientIPAddress: payerInfo.ip,
        countryCode: payerInfo.country,
        city: payerInfo.city,
        stateProvince: payerInfo.state
      })
    }
  );
  const result = await response.json();

  if (result.riskLevel === 'VeryHigh' || result.riskLevel === 'High') {
    console.warn(`High risk: ${result.description}`);
    console.warn(`Card from ${result.issuerCountry}, IP from ${result.countryByIP}, billing from ${result.countryFromBillingAddress}`);

    if (result.anonymousProxyUsed) {
      console.warn('Anonymous proxy detected');
    }
    return { approved: false, reason: result.description };
  }

  return { approved: true, riskLevel: result.riskLevel };
}

const risk = await assessRisk('411111', {
  ip: '203.0.113.42',
  country: 'US',
  city: 'New York',
  state: 'NY'
}, 'YOUR_API_KEY');

Metadata Lookup

Get card metadata without the risk assessment

API Reference

Full endpoint specification and response schema