> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BIN Intelligence (v1)

> Resolve the account range for a card BIN, full PAN, or network token and return the complete issuer, network, card, funding, product, capability, risk, and payout-eligibility profile in a single call.

Performs a single BIN Intelligence lookup and returns the full, normalized profile for the resolved account range. Unlike the tiered Card Lookup endpoint, BIN Intelligence has no feature flags: one call returns every attribute PayOS can resolve. Any attribute the card networks do not provide for the account range is returned as `null`.

The response is normalized, so the same shape is returned for every brand. Fields that apply only to a specific network (for example, several Visa-only risk flags, the Mastercard issuer number, or the Discover network-program flags) are populated only for that network and return `null` otherwise.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.payos.ai/api/bin/intelligence \
    --header 'X-API-Key: sk_live_your_api_key' \
    --header 'Content-Type: application/json' \
    --data '{
      "bin": "41111111"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1",
    "statusCode": 200,
    "errorCode": null,
    "data": {
      "status": "COMPLETED",
      "submitTimeUtc": "2026-06-18T21:47:57Z",
      "card": {
        "type": "001",
        "brandName": "VISA",
        "currency": "USD",
        "accountBillingCurrency": null,
        "minLength": null,
        "maxLength": "16",
        "credentialType": "PAN",
        "tokenizationSupported": null,
        "brands": [
          { "type": "001", "brandName": "VISA" }
        ]
      },
      "features": {
        "accountFundingSource": "DEBIT",
        "accountFundingSourceSubType": null,
        "cardProduct": "Visa Signature",
        "productCode": null,
        "productType": null,
        "productId": "Q4",
        "productIdSubtype": "BB",
        "cardPlatform": "CONSUMER",
        "comboCard": "0",
        "corporatePurchase": null,
        "healthCard": false,
        "fleetCard": false,
        "exemptBIN": false,
        "autoSubstantiation": false,
        "cashbackEligible": null,
        "cpsOptionEnabled": null,
        "messageType": "D",
        "threeDSSupport": true,
        "siEligible": true,
        "emiEligible": false,
        "atmEnabled": true,
        "posEnabled": true,
        "ecomEnabled": true,
        "flexCredential": false,
        "standInEligible": null,
        "alpEnabled": null,
        "dpwrEnabled": null,
        "rtpEnabled": null,
        "routingNetwork": null,
        "acceptanceLevel": "0",
        "sharedBIN": false,
        "posDomesticOnly": false,
        "gamblingAllowed": true,
        "onlineGamblingBlock": false,
        "commercialCardLevel2": false,
        "commercialCardLevel3": false,
        "regulationII": null,
        "accountLevelManagement": true
      },
      "network": {
        "id": "0001",
        "acceptanceBrand": null,
        "ica": null,
        "oneParticipation": null
      },
      "issuerInformation": {
        "name": "Example Bank National Association",
        "country": "USA",
        "countryName": "UNITED STATES",
        "binLength": "8",
        "accountPrefix": "41111111",
        "binRangeStart": null,
        "binRangeEnd": null,
        "phoneNumber": "+18005551234"
      },
      "payoutInformation": {
        "pushFunds": {
          "domesticParticipant": "true",
          "crossBorderParticipant": "true",
          "moneyTransferDomestic": "Y",
          "moneyTransferCrossBorder": "Y",
          "moneyTransferFastFundsDomestic": "Y",
          "moneyTransferFastFundsCrossBorder": "N",
          "nonMoneyTransferDomestic": "Y",
          "nonMoneyTransferCrossBorder": "N",
          "nonMoneyTransferFastFundsDomestic": "Y",
          "nonMoneyTransferFastFundsCrossBorder": "N",
          "onlineGamblingDomestic": "Y",
          "onlineGamblingCrossBorder": "N",
          "onlineGamblingFastFundsDomestic": "Y",
          "onlineGamblingFastFundsCrossBorder": "N"
        },
        "pullFunds": {
          "domesticParticipant": "true",
          "crossBorderParticipant": "false",
          "geoRestrictionIndicator": "Y"
        }
      }
    }
  }
  ```

  ```json 200 OK (Multiple matches) theme={null}
  {
    "success": true,
    "inquiryId": "9b2c1d44-1f0e-4a77-8c21-72d5b0c91a3e",
    "statusCode": 200,
    "errorCode": null,
    "data": {
      "status": "MULTIPLE",
      "submitTimeUtc": "2026-06-18T21:48:10Z",
      "card": {
        "brandName": "VISA",
        "credentialType": "PAN"
      }
    }
  }
  ```

  ```json 200 OK (No match) theme={null}
  {
    "success": true,
    "inquiryId": "c3a0f9e2-6b54-4d1e-9f88-2a6f1e0b7d44",
    "statusCode": 200,
    "errorCode": null,
    "data": {
      "status": "NO_MATCH",
      "submitTimeUtc": "2026-06-18T21:48:22Z"
    }
  }
  ```

  ```json 207 Multi-Status theme={null}
  {
    "success": false,
    "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1",
    "statusCode": 207,
    "errorCode": "PARTIAL_FAILURE",
    "error": "One or more failures occurred while processing the request. Please contact the PayOS team for assistance.",
    "data": {
      "status": "COMPLETED",
      "submitTimeUtc": "2026-06-18T21:47:57Z",
      "card": {
        "type": "001",
        "brandName": "VISA",
        "currency": "USD",
        "accountBillingCurrency": null,
        "minLength": null,
        "maxLength": "16",
        "credentialType": "PAN",
        "tokenizationSupported": null,
        "brands": [
          { "type": "001", "brandName": "VISA" }
        ]
      },
      "issuerInformation": {
        "name": "Example Bank National Association",
        "country": "USA",
        "countryName": "UNITED STATES",
        "binLength": "8",
        "accountPrefix": "41111111",
        "binRangeStart": null,
        "binRangeEnd": null,
        "phoneNumber": "+18005551234"
      }
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": "Either bin or accountNumber is required, but not both."
  }
  ```

  ```json 406 Not Acceptable theme={null}
  {
    "success": false,
    "error": "Character invalidation. Do you have any of these characters in your request: \\ ^ , \" ( ) | ; ~"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "ruleCode": 9001,
      "message": "Invalid API key"
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": {
      "code": "FORBIDDEN",
      "ruleCode": 9005,
      "message": "API key is not authorized for this resource"
    }
  }
  ```

  ```json 502 Bad Gateway theme={null}
  {
    "success": false,
    "error": "An upstream error occurred while processing the request.",
    "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1"
  }
  ```
</ResponseExample>

## Authentication

Requires API Key authentication via the `X-API-Key` header.

```text theme={null}
X-API-Key: sk_live_your_api_key
```

Sandbox requests use the test base URL and a test key:

```text theme={null}
https://sandbox.api.payos.ai/api/bin/intelligence
X-API-Key: sk_test_your_api_key
```

## Request Body

Provide exactly one credential: `bin` for a 6 to 8 digit prefix, or `accountNumber` for a full number. No other input is required, and there are no feature flags. The full profile is returned on every successful call.

<ParamField body="bin" type="string">
  A BIN or account prefix: 6 to 8 digits, digits only.

  A 6 to 8 digit prefix is enough for most lookups, but some prefixes are shared across issuers or products, in which case the result is `MULTIPLE` — resubmit with the full `accountNumber` to resolve a single range.

  Either `bin` or `accountNumber` is required, but not both.

  Example: `"41111111"`
</ParamField>

<ParamField body="accountNumber" type="string">
  A full account number: 12 to 19 digits, digits only, no spaces or dashes. Accepts a card number (PAN) or a network token number (for example, a mobile wallet credential) — you do not need to know which you hold. The response's `data.card.credentialType` reports how the network classified it (`PAN` or `TOKEN`).

  Either `bin` or `accountNumber` is required, but not both.

  Example: `"4111111111111111"`
</ParamField>

## Response

### 200 OK

Successful lookup. Inspect `data.status` to confirm the match before relying on the rest of the profile: a `MULTIPLE` or `NO_MATCH` result is still returned with HTTP 200.

<ResponseField name="success" type="boolean">
  `true` when the lookup was processed.
</ResponseField>

<ResponseField name="inquiryId" type="string">
  Unique identifier for the lookup. Store it with your records and quote it to PayOS support for troubleshooting.
</ResponseField>

<ResponseField name="statusCode" type="integer">
  HTTP status code for the response.
</ResponseField>

<ResponseField name="errorCode" type="string | null">
  Machine-readable error code. `null` on success (HTTP 200). On a 207 it is the string `PARTIAL_FAILURE`. On 400 / 401 / 406 the error is conveyed in `error` and `errorCode` may be absent.
</ResponseField>

<ResponseField name="data" type="object">
  The BIN Intelligence profile. Always a single object (one card profile), never an array of candidate ranges. On a `MULTIPLE` result the card profile is not populated; resubmit with the full `accountNumber` to resolve to one range.

  <Expandable title="data">
    <ResponseField name="status" type="string">
      The match result for the lookup. One of `COMPLETED` (a single definitive match), `MULTIPLE` (more than one account range matched; resubmit with the full `accountNumber`), or `NO_MATCH` (no account range matched). Upstream status values are normalized to these documented enum values. Always evaluate this before consuming other fields.
    </ResponseField>

    <ResponseField name="submitTimeUtc" type="string">
      Time the lookup was processed, in UTC (`YYYY-MM-DDThh:mm:ssZ`).
    </ResponseField>

    <ResponseField name="card" type="object">
      Card and credential attributes.

      <Expandable title="card">
        <ResponseField name="type" type="string">
          Three-digit network type code, the system-readable form of the brand: `001` Visa, `002` Mastercard, `003` American Express, `004` Discover (and other network codes for co-badged brands). Networks: all.
        </ResponseField>

        <ResponseField name="brandName" type="string">
          Card brand name (for example, `VISA`, `MASTERCARD`, `AMERICAN EXPRESS`, `DISCOVER`). Networks: all.
        </ResponseField>

        <ResponseField name="currency" type="string | null">
          The 3-letter ISO 4217 currency code for the card currency. Networks: all.
        </ResponseField>

        <ResponseField name="accountBillingCurrency" type="string | null">
          The account billing currency as a 3-letter ISO 4217 code. Networks: all; `null` when unavailable.
        </ResponseField>

        <ResponseField name="minLength" type="integer | null">
          Minimum PAN length for the account range. Networks: American Express only; `null` otherwise.
        </ResponseField>

        <ResponseField name="maxLength" type="string">
          Maximum PAN length for the account range.
        </ResponseField>

        <ResponseField name="credentialType" type="string">
          `PAN` or `TOKEN`.
        </ResponseField>

        <ResponseField name="tokenizationSupported" type="boolean | null">
          Whether the issuing program supports network tokenization. American Express and Discover only; `null` for Mastercard and other networks.
        </ResponseField>

        <ResponseField name="brands" type="array">
          Every network the credential can run on, including co-badged or secondary networks.

          <Expandable title="brands[]">
            <ResponseField name="type" type="string">
              Three-digit network type code for the brand entry (`001` Visa, `002` Mastercard, `003` American Express, `004` Discover, and so on). Networks: all.
            </ResponseField>

            <ResponseField name="brandName" type="string">
              Brand name for the brand entry. Networks: all.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="features" type="object">
      Funding, product, program, capability, and risk attributes.

      <Expandable title="features">
        <ResponseField name="accountFundingSource" type="string | null">
          How the card is funded: `CREDIT`, `DEBIT`, `PREPAID`, `CHARGE`, or `DEFERRED DEBIT`. Networks: all (`null` where the network does not supply it).
        </ResponseField>

        <ResponseField name="accountFundingSourceSubType" type="string | null">
          For prepaid cards: `Reloadable` or `Non-reloadable`.
        </ResponseField>

        <ResponseField name="cardProduct" type="string | null">
          Issuer product or marketing tier name (for example, `Visa Signature`).
        </ResponseField>

        <ResponseField name="productCode" type="string | null">
          Brand product code. Mastercard and American Express only; `null` for Visa, Discover, and other networks. Source: Mastercard and American Express BIN data.
        </ResponseField>

        <ResponseField name="productType" type="string | null">
          Network product category. Networks: American Express only; `null` for Discover and all other networks.
        </ResponseField>

        <ResponseField name="productId" type="string | null">
          Visa-assigned product identifier. Visa only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="productIdSubtype" type="string | null">
          Visa-assigned product subtype identifier. Visa only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="cardPlatform" type="string | null">
          Card program category: `CONSUMER`, `BUSINESS`, `CORPORATE`, `COMMERCIAL`, or `GOVERNMENT`.
        </ResponseField>

        <ResponseField name="comboCard" type="string | null">
          Combo-card indicator: `0` (not a combo card), `1` (credit and prepaid), `2` (credit and debit), `3` (prepaid credit and prepaid debit).
        </ResponseField>

        <ResponseField name="corporatePurchase" type="boolean | null">
          Whether the card supports corporate purchasing. American Express only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="healthCard" type="boolean | null">
          Whether the BIN is a healthcare (HSA/FSA) card. Visa only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="fleetCard" type="boolean | null">
          Whether the BIN is designated for fuel/fleet usage.
        </ResponseField>

        <ResponseField name="exemptBIN" type="boolean | null">
          Whether the card qualifies for government-exempt interchange treatment.
        </ResponseField>

        <ResponseField name="autoSubstantiation" type="boolean | null">
          Whether auto-substantiation is enabled on the BIN.
        </ResponseField>

        <ResponseField name="cashbackEligible" type="boolean | null">
          Whether the card is cashback eligible. Returned for American Express cards only; `null` for Visa, Mastercard, Discover, and others.
        </ResponseField>

        <ResponseField name="cpsOptionEnabled" type="boolean | null">
          Whether the American Express CPS option is enabled. American Express only; `null` for all other networks. Source: American Express BIN range data.
        </ResponseField>

        <ResponseField name="messageType" type="string | null">
          Processing model: `S` (single message) or `D` (dual message).
        </ResponseField>

        <ResponseField name="threeDSSupport" type="boolean | null">
          Whether the card supports 3-D Secure authentication.
        </ResponseField>

        <ResponseField name="siEligible" type="boolean | null">
          Whether the card is eligible for standing instructions (recurring payments).
        </ResponseField>

        <ResponseField name="emiEligible" type="boolean | null">
          Whether the card is eligible for installment payments (EMI).
        </ResponseField>

        <ResponseField name="atmEnabled" type="boolean | null">
          Whether the card is enabled for ATM use.
        </ResponseField>

        <ResponseField name="posEnabled" type="boolean | null">
          Whether the card is enabled for in-person (POS) use.
        </ResponseField>

        <ResponseField name="ecomEnabled" type="boolean | null">
          Whether the card is enabled for ecommerce use.
        </ResponseField>

        <ResponseField name="flexCredential" type="boolean | null">
          Whether the card is a flexible (multi-account) credential.
        </ResponseField>

        <ResponseField name="standInEligible" type="boolean | null">
          Whether the card is eligible for network stand-in processing. Returned as a boolean. Networks: Discover only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="alpEnabled" type="boolean | null">
          Whether the Discover ALP program is enabled. Returned as a boolean. Networks: Discover only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="dpwrEnabled" type="boolean | null">
          Whether the Discover DPWR program is enabled. Returned as a boolean. Networks: Discover only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="rtpEnabled" type="boolean | null">
          Whether the Discover RTP program is enabled. Discover only; `null` for all other networks. Source: Discover BIN data.
        </ResponseField>

        <ResponseField name="routingNetwork" type="string | null">
          Routing capability (`Credit` or `Debit`) for the account range. Available for Discover, Diners Club, JCB, and UnionPay; `null` for Visa, Mastercard, and American Express.
        </ResponseField>

        <ResponseField name="acceptanceLevel" type="string | null">
          Acceptance level of the PAN: `0` Normal, `1` Monitor, `2` Refuse, `3` Not Allowed, `4` Private, `5` Test.
        </ResponseField>

        <ResponseField name="sharedBIN" type="boolean | null">
          Whether the BIN is shared by multiple issuers.
        </ResponseField>

        <ResponseField name="posDomesticOnly" type="boolean | null">
          Whether the BIN is valid only for domestic POS use.
        </ResponseField>

        <ResponseField name="gamblingAllowed" type="boolean | null">
          Whether gambling transactions are allowed on the BIN.
        </ResponseField>

        <ResponseField name="onlineGamblingBlock" type="boolean | null">
          Whether online gambling is blocked on the BIN.
        </ResponseField>

        <ResponseField name="commercialCardLevel2" type="boolean | null">
          Whether the card qualifies for Level 2 interchange. Visa and Mastercard; `null` for all other networks.
        </ResponseField>

        <ResponseField name="commercialCardLevel3" type="boolean | null">
          Whether the card qualifies for Level 3 interchange. Visa and Mastercard; `null` for all other networks.
        </ResponseField>

        <ResponseField name="regulationII" type="boolean | null">
          Whether the card is subject to U.S. Regulation II regulated-debit treatment. Discover cards only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="accountLevelManagement" type="boolean | null">
          Whether the BIN participates in Account Level Management. Visa only; `null` for all other networks.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="network" type="object">
      Network ownership and participation identifiers.

      <Expandable title="network">
        <ResponseField name="id" type="string | null">
          Network or sharing-group code.
        </ResponseField>

        <ResponseField name="acceptanceBrand" type="string | null">
          Brand used for acceptance and routing decisions. Mastercard cards only; `null` for Visa, American Express, Discover, and others.
        </ResponseField>

        <ResponseField name="ica" type="string | null">
          Mastercard issuer identification number (ICA), with any leading zeros removed. Networks: Mastercard only; `null` for all other networks.
        </ResponseField>

        <ResponseField name="oneParticipation" type="boolean | null">
          Mastercard One participation indicator. Mastercard only; `null` for all other networks. Source: Mastercard enrichment.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="issuerInformation" type="object">
      Issuer and account-range details.

      <Expandable title="issuerInformation">
        <ResponseField name="name" type="string | null">
          Issuing bank or organization name.
        </ResponseField>

        <ResponseField name="country" type="string | null">
          Issuer country as a 3-letter ISO 3166-1 alpha-3 code (for example, `USA`, `GBR`). In rare cases where the code cannot be resolved to alpha-3, the 2-letter alpha-2 value is returned instead. Networks: all.
        </ResponseField>

        <ResponseField name="countryName" type="string | null">
          Full issuer country name. Available for American Express cards; may be `null` for other brands.
        </ResponseField>

        <ResponseField name="binLength" type="string | null">
          Number of significant digits in the identified BIN, as a string: `6` or `8`. This is the length of the matched issuer prefix, not the PAN. Networks: all.
        </ResponseField>

        <ResponseField name="accountPrefix" type="string | null">
          The resolved account-range prefix (6 to 8 digits).
        </ResponseField>

        <ResponseField name="binRangeStart" type="string | null">
          Lowest account number in the identified range.
        </ResponseField>

        <ResponseField name="binRangeEnd" type="string | null">
          Highest account number in the identified range.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string | null">
          Issuer customer-service phone number.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payoutInformation" type="object">
      Payout eligibility. Eligibility can differ between account ranges under one issuing BIN, so it is resolved at the account-range level.

      <Expandable title="payoutInformation">
        <ResponseField name="pushFunds" type="object">
          Eligibility to send funds to the card (OCT).

          <Expandable title="pushFunds">
            <ResponseField name="domesticParticipant" type="string">
              Domestic push funds allowed (`true` / `false`).
            </ResponseField>

            <ResponseField name="crossBorderParticipant" type="string">
              Cross-border push funds allowed (`true` / `false`).
            </ResponseField>

            <ResponseField name="moneyTransferDomestic" type="string">
              Domestic money-transfer OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="moneyTransferCrossBorder" type="string">
              Cross-border money-transfer OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="moneyTransferFastFundsDomestic" type="string">
              Domestic money-transfer Fast Funds allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="moneyTransferFastFundsCrossBorder" type="string">
              Cross-border money-transfer Fast Funds allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="nonMoneyTransferDomestic" type="string">
              Domestic non-money-transfer OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="nonMoneyTransferCrossBorder" type="string">
              Cross-border non-money-transfer OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="nonMoneyTransferFastFundsDomestic" type="string">
              Domestic non-money-transfer Fast Funds allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="nonMoneyTransferFastFundsCrossBorder" type="string">
              Cross-border non-money-transfer Fast Funds allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="onlineGamblingDomestic" type="string">
              Domestic online-gambling OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="onlineGamblingCrossBorder" type="string">
              Cross-border online-gambling OCTs allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="onlineGamblingFastFundsDomestic" type="string">
              Domestic online-gambling Fast Funds allowed (`Y` / `N`).
            </ResponseField>

            <ResponseField name="onlineGamblingFastFundsCrossBorder" type="string">
              Cross-border online-gambling Fast Funds allowed (`Y` / `N`).
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="pullFunds" type="object">
          Eligibility to pull funds from the card (AFT).

          <Expandable title="pullFunds">
            <ResponseField name="domesticParticipant" type="string">
              Domestic pull funds allowed (`true` / `false`).
            </ResponseField>

            <ResponseField name="crossBorderParticipant" type="string">
              Cross-border pull funds allowed (`true` / `false`).
            </ResponseField>

            <ResponseField name="geoRestrictionIndicator" type="string">
              Whether the recipient issuer can accept pull-funds (AFT) transactions from the originator country: `Y` (geographic restrictions apply) or `N` (no restriction). Networks: all that participate in pull funds.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Lookup Status

The match result is returned in `data.status` and is independent of the HTTP status code. All three values return HTTP 200.

| `data.status` | Meaning                                                       | Recommended action                                          |
| ------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| `COMPLETED`   | A single account range matched. The profile is authoritative. | Use the returned profile.                                   |
| `MULTIPLE`    | More than one account range matched the supplied digits.      | Resubmit with an 8-digit `bin` or the full `accountNumber`. |
| `NO_MATCH`    | No account range matched.                                     | Proceed without a profile or review the credential.         |

<Note>
  Every lookup returns a **single response** with a single `data` object — one card profile, never an array of candidate ranges. When the supplied digits match more than one account range, `data.status` is `MULTIPLE` and no card profile is populated; resubmit the lookup with more digits (an 8-digit `bin`, or the full `accountNumber`) to resolve to a single range. The API does not fan out or return a list of candidate matches.
</Note>

### 207 Multi-Status

Partial processing failure: one or more upstream operations failed during the lookup. `success` is `false` and `errorCode` is `PARTIAL_FAILURE`. Any data that was resolved is returned in `data`, using the same profile shape as a 200 `COMPLETED` response (the example above is abbreviated).

If you receive a 207, contact PayOS support with the `inquiryId` and the full response.

### 400 Bad Request

Validation error. Returned when the request is malformed, for example when neither `bin` nor `accountNumber` is supplied, when both are supplied, when either contains non-digit characters, when `bin` is not 6 to 8 digits, when `accountNumber` is not 12 to 19 digits, or when the card networks reject the supplied credential as unprocessable.

### 406 Not Acceptable

Character validation error. Returned when input contains forbidden characters or matches a security pattern (see Input Validation below).

### 401 Unauthorized

Authentication error. Returned when the `X-API-Key` header is missing or invalid. Authentication and authorization errors use a different envelope from lookup errors: `{ "error": { "code", "ruleCode", "message" } }`.

### 403 Forbidden

Authorization error. Returned when the API key is valid but not authorized for BIN Intelligence. Uses the same `{ "error": { "code", "ruleCode", "message" } }` envelope as 401. Contact PayOS to enable BIN Intelligence for your key.

### 429 Too Many Requests

Rate limit exceeded. `errorCode` is `RATE_LIMIT_EXCEEDED`. Retry after the time indicated by the `RateLimit-Reset` response header.

### 502 Bad Gateway

Upstream error. The lookup could not be completed because an upstream dependency failed or is unavailable. The response includes an `inquiryId` for the attempted lookup. Retry later; if the error persists, contact PayOS support with the `inquiryId`.

## Sandbox Testing

Sandbox (test API keys, `sk_test_…`) returns **deterministic test profiles** for the credentials below — no real card data is required, and the request and response shapes are identical to production. Nothing extra is needed in the request: the same call against the sandbox base URL with a test key just works.

| Test range                       | As `bin` | As `accountNumber` | Result                                                 |
| -------------------------------- | -------- | ------------------ | ------------------------------------------------------ |
| Visa consumer debit              | `411111` | `4111111111111111` | `200` — `COMPLETED` (matches the 200 OK example above) |
| Mastercard business credit       | `555555` | `5555555555554444` | `200` — `COMPLETED`                                    |
| American Express consumer charge | `378282` | `378282246310005`  | `200` — `COMPLETED`                                    |
| Discover consumer credit         | `601111` | `6011111111111117` | `200` — `COMPLETED`                                    |
| Network token (Visa)             | `489537` | `4895370012003478` | `200` — `COMPLETED` with `credentialType: "TOKEN"`     |
| Shared prefix                    | `400000` | `4000001234567890` | `200` — `MULTIPLE` (resubmit the full `accountNumber`) |
| Unknown range                    | `999999` | `9999990000000000` | `200` — `NO_MATCH`                                     |
| Unprocessable trigger            | `999990` | `9999900000000000` | `400` — triggers the unprocessable-credential error    |
| Upstream-error trigger           | `999995` | `9999950000000000` | `502` — triggers the upstream-error response           |

Each test range works either way — send the 6-digit prefix as `bin` or the example full number as `accountNumber`. Any other sandbox input returns `NO_MATCH`.

## Error Codes

| HTTP | `errorCode`                   | Meaning                                                                                                                                            | What to do                                                        |
| ---- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| 200  | `null`                        | Success. Check `data.status` for the match result.                                                                                                 | Use the profile.                                                  |
| 207  | `PARTIAL_FAILURE`             | One or more upstream operations failed.                                                                                                            | Contact support with the `inquiryId`.                             |
| 400  | varies                        | Malformed request (missing credential, both fields supplied, or invalid `bin` / `accountNumber`), or the credential was rejected as unprocessable. | Fix the request and retry.                                        |
| 401  | `UNAUTHORIZED` (`error.code`) | Missing or invalid API key. Different envelope: `{ "error": { "code", "ruleCode", "message" } }`.                                                  | Check the `X-API-Key` header.                                     |
| 403  | `FORBIDDEN` (`error.code`)    | API key not authorized for BIN Intelligence. Same envelope as 401.                                                                                 | Contact PayOS to enable BIN Intelligence for your key.            |
| 406  | none                          | Forbidden characters or a security pattern in the input.                                                                                           | Review the input and retry.                                       |
| 429  | `RATE_LIMIT_EXCEEDED`         | Rate limit exceeded.                                                                                                                               | Retry after the `RateLimit-Reset` header.                         |
| 502  | none                          | Upstream error — the lookup could not be completed.                                                                                                | Retry later; contact support with the `inquiryId` if it persists. |

## Example Usage

<CodeGroup>
  ```bash BIN prefix theme={null}
  curl -X POST https://sandbox.api.payos.ai/api/bin/intelligence \
    -H "X-API-Key: sk_test_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "bin": "41111111"
    }'
  ```

  ```bash Full card number theme={null}
  curl -X POST https://sandbox.api.payos.ai/api/bin/intelligence \
    -H "X-API-Key: sk_test_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "accountNumber": "4111111111111111"
    }'
  ```

  ```bash Network token number theme={null}
  curl -X POST https://sandbox.api.payos.ai/api/bin/intelligence \
    -H "X-API-Key: sk_test_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "accountNumber": "4895370012003478"
    }'
  ```
</CodeGroup>

## Input Validation

The lookup accepts only the credential. `bin` and `accountNumber` must be digits only, with no spaces or dashes. The following characters are rejected, and the request returns 406 Not Acceptable:

```text theme={null}
\ ^ , " ( ) | ; ~ ` [ ]
```

Control characters are also rejected. Requests return 406 when input matches a security pattern, such as consecutive dots (`..`) or SQL keywords and comment markers (for example `SELECT`, `DROP`, `UNION`, `--`, `/*`). For security, the error message does not identify which field caused the failure.

## Notes

* BIN Intelligence returns the full profile on every successful call. There are no feature flags, and there is no separate request to enable additional fields.
* Always check `data.status` before consuming the profile. `MULTIPLE` and `NO_MATCH` return HTTP 200.
* Fields that are network-specific (for example, Visa-only risk flags, the Mastercard issuer number, or Discover program flags) are populated only for that network and return `null` otherwise.
* Payout eligibility (push and pull) can differ between account ranges under one issuing BIN, so it is resolved at the account-range level rather than the BIN level.
* Every lookup is tracked with a unique `inquiryId` for support purposes. Full account numbers are masked in stored inquiry records.
* For plain-language field definitions, usage guidance, and the network code lists (card type, product, ACNL, ARDEF), see the BIN Intelligence guide.