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

# Card Validation

> Assess transaction risk by comparing card origin against the payer's IP and billing address.

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:**

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

**Request body:**

| Field             | Type   | Required | Description                                             |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| `clientIPAddress` | string | Yes      | The payer's IP address                                  |
| `countryCode`     | string | Yes      | ISO 3166-2 two-letter country code from billing address |
| `city`            | string | No       | Billing city                                            |
| `stateProvince`   | string | No       | Billing state or province                               |

### Risk Levels

| Level      | Meaning                                                        |
| ---------- | -------------------------------------------------------------- |
| `VeryLow`  | Card issuer country, IP country, and billing country all match |
| `Low`      | Minor discrepancy between data points                          |
| `High`     | Significant mismatch between card origin and payer location    |
| `VeryHigh` | Multiple mismatches or anonymous proxy detected                |

## Example: Pre-Transaction Fraud Check

Screen transactions before processing and flag high-risk payments for manual review.

<CodeGroup>
  ```javascript Node.js theme={null}
  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');
  ```

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

  def assess_risk(card_bin, payer_ip, payer_country, api_key, city=None, state=None):
      """Assess transaction risk based on card origin vs payer location."""
      response = requests.post(
          'https://api.orchestrasolutions.com/Tools/validate',
          params={'iin': card_bin},
          headers={
              'X-Api-Key': api_key,
              'Content-Type': 'application/json'
          },
          json={
              'clientIPAddress': payer_ip,
              'countryCode': payer_country,
              'city': city,
              'stateProvince': state
          }
      )
      response.raise_for_status()
      result = response.json()

      if result['riskLevel'] in ('High', 'VeryHigh'):
          print(f"WARNING: {result['description']}")
          print(f"  Card issuer: {result['issuerCountry']}")
          print(f"  IP location: {result['countryByIP']}")
          print(f"  Billing:     {result['countryFromBillingAddress']}")
          print(f"  Proxy:       {result['anonymousProxyUsed']}")
          return False

      return True

  is_safe = assess_risk('411111', '203.0.113.42', 'US', 'YOUR_API_KEY',
                         city='New York', state='NY')
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.orchestrasolutions.com/Tools/validate?iin=411111" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "clientIPAddress": "203.0.113.42",
      "countryCode": "US",
      "city": "New York",
      "stateProvince": "NY"
    }'
  ```
</CodeGroup>

## Related

<CardGroup cols={2}>
  <Card title="Metadata Lookup" icon="magnifying-glass" href="/guides/rest-api/utilities/card-tools/metadata-lookup">
    Get card metadata without the risk assessment
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tools/card-validation">
    Full endpoint specification and response schema
  </Card>
</CardGroup>