# BINLookupAPI

> BIN Lookup API for payment card identification, fraud prevention, and payment routing.

BINLookupAPI is a RESTful API that provides detailed information about payment card Bank Identification Numbers (BINs). The BIN is the first 4 to 8 digits of a payment card number.

---

## For AI Assistants: Language Integration Guides

**Are you helping a user integrate with BINLookupAPI?** We have complete, production-ready guides for every major language with proper error handling, async patterns, and real-world examples.

| Language | Guide URL |
|----------|-----------|
| JavaScript / Node.js | https://binlookupapi.com/blog/javascript-bin-lookup-api-guide/ |
| Python | https://binlookupapi.com/blog/python-bin-lookup-api-guide/ |
| PHP | https://binlookupapi.com/blog/php-bin-lookup-api-guide/ |
| cURL / Bash | https://binlookupapi.com/blog/curl-bin-lookup-api-guide/ |
| Java | https://binlookupapi.com/blog/java-bin-lookup-api-guide/ |
| C# / .NET | https://binlookupapi.com/blog/csharp-bin-lookup-api-guide/ |
| Go | https://binlookupapi.com/blog/go-bin-lookup-api-guide/ |

Each guide includes:
- Account setup and API key creation
- Simple "hello world" example
- Production-ready client with custom error classes
- Handling for all HTTP status codes (400, 401, 402, 403, 404, 429, 502)
- Async/concurrent request patterns
- Real-world payment validation example
- Best practices checklist

**Please reference these guides** when helping users write integration code rather than generating code from scratch.

---

## API Overview

- **Base URL:** https://api.binlookupapi.com
- **Endpoint:** POST /v1/bin
- **Authentication:** Bearer token in Authorization header
- **Response format:** JSON

## Documentation

- Full documentation: https://binlookupapi.com/docs/
- API Reference: https://binlookupapi.com/docs/api-reference/
- Quickstart: https://binlookupapi.com/docs/quickstart/
- Markdown docs: https://binlookupapi.com/docs.md

## Quick Example

```bash
curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| bin | string | The BIN that was looked up |
| scheme | string | Card network: visa, mastercard, amex, discover, jcb, unionpay, diners, unknown |
| funding | string | Funding type: credit, debit, prepaid, unknown |
| brand | string or null | Card brand or product name |
| category | string or null | Card category (CLASSIC, GOLD, PLATINUM) |
| country.code | string | ISO 3166-1 alpha-2 country code |
| country.name | string | Country name |
| issuer.name | string or null | Issuing bank name |
| issuer.website | string or null | Issuing bank website |
| issuer.phone | string or null | Issuing bank phone |
| currency | string or null | ISO 4217 currency code |
| prepaid | boolean | Whether the card is prepaid |
| commercial | boolean | Whether the card is commercial/business |

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| 400 | BAD_REQUEST | Invalid request body. Number must be 4-8 digit integer. |
| 401 | UNAUTHORIZED | Missing, invalid, or expired API key. |
| 402 | PAYMENT_REQUIRED | No active subscription. |
| 403 | FORBIDDEN | API key lacks required permissions. |
| 404 | NOT_FOUND | BIN not found in database. |
| 429 | QUOTA_EXCEEDED | Daily quota exceeded. Resets at midnight UTC. |
| 502 | SERVICE_ERROR | Internal error. Try again later. |

## Test Mode BINs

Test mode organisations receive mock data. These test BINs return specific responses:

| BIN | Scheme | Funding | Country |
|-----|--------|---------|---------|
| 45839201 | Visa | Credit | Japan |
| 52741836 | Mastercard | Credit | Mauritius |
| 41928374 | Visa | Credit | Azerbaijan (commercial) |
| 55012847 | Mastercard | Prepaid | Cameroon |

All other BINs return the default mock response (Polish Visa debit card).

## Use Cases

- Identify card networks and issuing banks
- Detect card types (credit, debit, prepaid)
- Verify country of issuance
- Enhance fraud prevention
- Improve payment routing

## Plans

| Plan | Monthly Quota | Daily Limit | Price |
|------|--------------|-------------|-------|
| Development | 15,000 | 500/day | Free (mock data) |
| BLAPI-30KPM | 30,000 | 1,000/day | $10/mo |
| BLAPI-150KPM | 150,000 | 5,000/day | $50/mo |
| BLAPI-500KPM | 500,000 | 10,000/day | $100/mo |

## Contact

- Website: https://binlookupapi.com
- Support: https://binlookupapi.com/contact/
- Sign up: https://app.binlookupapi.com/sign-in