BIN Intelligence (v1)

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"
  }'

{
  "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"
      }
    }
  }
}

{
  "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"
    }
  }
}

{
  "success": true,
  "inquiryId": "c3a0f9e2-6b54-4d1e-9f88-2a6f1e0b7d44",
  "statusCode": 200,
  "errorCode": null,
  "data": {
    "status": "NO_MATCH",
    "submitTimeUtc": "2026-06-18T21:48:22Z"
  }
}

{
  "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"
    }
  }
}

{
  "success": false,
  "error": "Either bin or accountNumber is required, but not both."
}

{
  "success": false,
  "error": "Character invalidation. Do you have any of these characters in your request: \\ ^ , \" ( ) | ; ~"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "ruleCode": 9001,
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "ruleCode": 9005,
    "message": "API key is not authorized for this resource"
  }
}

{
  "success": false,
  "error": "An upstream error occurred while processing the request.",
  "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1"
}

POST

api

bin

intelligence

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"
  }'

{
  "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"
      }
    }
  }
}

{
  "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"
    }
  }
}

{
  "success": true,
  "inquiryId": "c3a0f9e2-6b54-4d1e-9f88-2a6f1e0b7d44",
  "statusCode": 200,
  "errorCode": null,
  "data": {
    "status": "NO_MATCH",
    "submitTimeUtc": "2026-06-18T21:48:22Z"
  }
}

{
  "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"
    }
  }
}

{
  "success": false,
  "error": "Either bin or accountNumber is required, but not both."
}

{
  "success": false,
  "error": "Character invalidation. Do you have any of these characters in your request: \\ ^ , \" ( ) | ; ~"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "ruleCode": 9001,
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "ruleCode": 9005,
    "message": "API key is not authorized for this resource"
  }
}

{
  "success": false,
  "error": "An upstream error occurred while processing the request.",
  "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1"
}

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.

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"
  }'

{
  "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"
      }
    }
  }
}

{
  "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"
    }
  }
}

{
  "success": true,
  "inquiryId": "c3a0f9e2-6b54-4d1e-9f88-2a6f1e0b7d44",
  "statusCode": 200,
  "errorCode": null,
  "data": {
    "status": "NO_MATCH",
    "submitTimeUtc": "2026-06-18T21:48:22Z"
  }
}

{
  "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"
    }
  }
}

{
  "success": false,
  "error": "Either bin or accountNumber is required, but not both."
}

{
  "success": false,
  "error": "Character invalidation. Do you have any of these characters in your request: \\ ^ , \" ( ) | ; ~"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "ruleCode": 9001,
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "ruleCode": 9005,
    "message": "API key is not authorized for this resource"
  }
}

{
  "success": false,
  "error": "An upstream error occurred while processing the request.",
  "inquiryId": "20e791ff-6937-45fc-a28a-f358b7e6a4b1"
}

Authentication

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

X-API-Key: sk_live_your_api_key

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

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.

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"

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"

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.

boolean

true when the lookup was processed.

string

Unique identifier for the lookup. Store it with your records and quote it to PayOS support for troubleshooting.

integer

HTTP status code for the response.

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.

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.

Show data

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.

string

Time the lookup was processed, in UTC (YYYY-MM-DDThh:mm:ssZ).

object

Card and credential attributes.

Show card

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.

string

Card brand name (for example, VISA, MASTERCARD, AMERICAN EXPRESS, DISCOVER). Networks: all.

string | null

The 3-letter ISO 4217 currency code for the card currency. Networks: all.

string | null

The account billing currency as a 3-letter ISO 4217 code. Networks: all; null when unavailable.

integer | null

Minimum PAN length for the account range. Networks: American Express only; null otherwise.

string

Maximum PAN length for the account range.

string

PAN or TOKEN.

boolean | null

Whether the issuing program supports network tokenization. American Express and Discover only; null for Mastercard and other networks.

array

Every network the credential can run on, including co-badged or secondary networks.

Show brands[]

string

Three-digit network type code for the brand entry (001 Visa, 002 Mastercard, 003 American Express, 004 Discover, and so on). Networks: all.

string

Brand name for the brand entry. Networks: all.

object

Funding, product, program, capability, and risk attributes.

Show features

string | null

How the card is funded: CREDIT, DEBIT, PREPAID, CHARGE, or DEFERRED DEBIT. Networks: all (null where the network does not supply it).

string | null

For prepaid cards: Reloadable or Non-reloadable.

string | null

Issuer product or marketing tier name (for example, Visa Signature).

string | null

Brand product code. Mastercard and American Express only; null for Visa, Discover, and other networks. Source: Mastercard and American Express BIN data.

string | null

Network product category. Networks: American Express only; null for Discover and all other networks.

string | null

Visa-assigned product identifier. Visa only; null for all other networks.

string | null

Visa-assigned product subtype identifier. Visa only; null for all other networks.

string | null

Card program category: CONSUMER, BUSINESS, CORPORATE, COMMERCIAL, or GOVERNMENT.

string | null

Combo-card indicator: 0 (not a combo card), 1 (credit and prepaid), 2 (credit and debit), 3 (prepaid credit and prepaid debit).

boolean | null

Whether the card supports corporate purchasing. American Express only; null for all other networks.

boolean | null

Whether the BIN is a healthcare (HSA/FSA) card. Visa only; null for all other networks.

boolean | null

Whether the BIN is designated for fuel/fleet usage.

boolean | null

Whether the card qualifies for government-exempt interchange treatment.

boolean | null

Whether auto-substantiation is enabled on the BIN.

boolean | null

Whether the card is cashback eligible. Returned for American Express cards only; null for Visa, Mastercard, Discover, and others.

boolean | null

Whether the American Express CPS option is enabled. American Express only; null for all other networks. Source: American Express BIN range data.

string | null

Processing model: S (single message) or D (dual message).

boolean | null

Whether the card supports 3-D Secure authentication.

boolean | null

Whether the card is eligible for standing instructions (recurring payments).

boolean | null

Whether the card is eligible for installment payments (EMI).

boolean | null

Whether the card is enabled for ATM use.

boolean | null

Whether the card is enabled for in-person (POS) use.

boolean | null

Whether the card is enabled for ecommerce use.

boolean | null

Whether the card is a flexible (multi-account) credential.

boolean | null

Whether the card is eligible for network stand-in processing. Returned as a boolean. Networks: Discover only; null for all other networks.

boolean | null

Whether the Discover ALP program is enabled. Returned as a boolean. Networks: Discover only; null for all other networks.

boolean | null

Whether the Discover DPWR program is enabled. Returned as a boolean. Networks: Discover only; null for all other networks.

boolean | null

Whether the Discover RTP program is enabled. Discover only; null for all other networks. Source: Discover BIN data.

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.

string | null

Acceptance level of the PAN: 0 Normal, 1 Monitor, 2 Refuse, 3 Not Allowed, 4 Private, 5 Test.

boolean | null

Whether the BIN is shared by multiple issuers.

boolean | null

Whether the BIN is valid only for domestic POS use.

boolean | null

Whether gambling transactions are allowed on the BIN.

boolean | null

Whether online gambling is blocked on the BIN.

boolean | null

Whether the card qualifies for Level 2 interchange. Visa and Mastercard; null for all other networks.

boolean | null

Whether the card qualifies for Level 3 interchange. Visa and Mastercard; null for all other networks.

boolean | null

Whether the card is subject to U.S. Regulation II regulated-debit treatment. Discover cards only; null for all other networks.

boolean | null

Whether the BIN participates in Account Level Management. Visa only; null for all other networks.

object

Network ownership and participation identifiers.

Show network

string | null

Network or sharing-group code.

string | null

Brand used for acceptance and routing decisions. Mastercard cards only; null for Visa, American Express, Discover, and others.

string | null

Mastercard issuer identification number (ICA), with any leading zeros removed. Networks: Mastercard only; null for all other networks.

boolean | null

Mastercard One participation indicator. Mastercard only; null for all other networks. Source: Mastercard enrichment.

object

Issuer and account-range details.

Show issuerInformation

string | null

Issuing bank or organization name.

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.

string | null

Full issuer country name. Available for American Express cards; may be null for other brands.

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.

string | null

The resolved account-range prefix (6 to 8 digits).

string | null

Lowest account number in the identified range.

string | null

Highest account number in the identified range.

string | null

Issuer customer-service phone number.

object

Payout eligibility. Eligibility can differ between account ranges under one issuing BIN, so it is resolved at the account-range level.

Show payoutInformation

object

Eligibility to send funds to the card (OCT).

Show pushFunds

string

Domestic push funds allowed (true / false).

string

Cross-border push funds allowed (true / false).

string

Domestic money-transfer OCTs allowed (Y / N).

string

Cross-border money-transfer OCTs allowed (Y / N).

string

Domestic money-transfer Fast Funds allowed (Y / N).

string

Cross-border money-transfer Fast Funds allowed (Y / N).

string

Domestic non-money-transfer OCTs allowed (Y / N).

string

Cross-border non-money-transfer OCTs allowed (Y / N).

string

Domestic non-money-transfer Fast Funds allowed (Y / N).

string

Cross-border non-money-transfer Fast Funds allowed (Y / N).

string

Domestic online-gambling OCTs allowed (Y / N).

string

Cross-border online-gambling OCTs allowed (Y / N).

string

Domestic online-gambling Fast Funds allowed (Y / N).

string

Cross-border online-gambling Fast Funds allowed (Y / N).

object

Eligibility to pull funds from the card (AFT).

Show pullFunds

string

Domestic pull funds allowed (true / false).

string

Cross-border pull funds allowed (true / false).

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.

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.

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.

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

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"
  }'

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"
  }'

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"
  }'

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:

\ ^ , " ( ) | ; ~ ` [ ]

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.

⌘I

​Authentication

​Request Body

​Response

​200 OK

​Lookup Status

​207 Multi-Status

​400 Bad Request

​406 Not Acceptable

​401 Unauthorized

​403 Forbidden

​429 Too Many Requests

​502 Bad Gateway

​Sandbox Testing

​Error Codes

​Example Usage

​Input Validation

​Notes

Authentication

Request Body

Response

200 OK

Lookup Status

207 Multi-Status

400 Bad Request

406 Not Acceptable

401 Unauthorized

403 Forbidden

429 Too Many Requests

502 Bad Gateway

Sandbox Testing

Error Codes

Example Usage

Input Validation

Notes