Developer documentation

Look up card information by BIN

Last updated:

The getBinInfo method returns the brand, type, country, and issuing bank of a card from its BIN — the first 6 to 8 digits of the PAN. Use it to prevalidate destinations before submitting a card payout, to display issuer details to operators reviewing manual disbursements, or to gate features by country and card type.

When to use it

  • Before createPayout with paymentType=card — reject ineligible destinations (prepaid, sanctioned-country issuers, virtual cards) before they consume a payout limit.
  • Operator UIs — show the issuing bank and country alongside a masked PAN so operators can spot mismatches against the beneficiary record.
  • Feature gating — restrict cross-border card payouts to specific issuer countries per your AML risk appetite.

BIN lookup is informational only. A successful lookup does not guarantee the card is open, has sufficient funds, or will accept a payout — the destination rail still validates at submission.

Endpoint

Send the request to https://api.unitpay.net/api. POST over TLS is required.

Required parameters

ParameterTypeDescription
methodstringAlways getBinInfo.
params[bin]stringFirst 6, 7, or 8 digits of the PAN. Pass digits only — no spaces, dashes, or grouping. UnitPay never requires the full PAN for BIN lookup.
params[secretKey]stringProject secret key. Send only via TLS in the POST body.

Example request

POST https://api.unitpay.net/api
Content-Type: application/x-www-form-urlencoded

method=getBinInfo
&params[bin]=455673
&params[secretKey]=<your-project-secret-key>

Successful response

{
  "result": {
    "bin": "455673",
    "brand": "visa",
    "type": "credit",
    "category": "consumer",
    "country": "ID",
    "countryName": "Indonesia",
    "currency": "IDR",
    "bankName": "Bank Central Asia",
    "bankBicCode": "CENAIDJA",
    "supports": {
      "payout": true,
      "threeDSecure": true
    }
  }
}
FieldDescription
brandOne of visa, mastercard, jcb, amex, unionpay, or discover.
typeOne of credit, debit, prepaid, or charge.
categoryOne of consumer, business, corporate, or commercial. Useful when commercial-card surcharges apply.
countryISO 3166-1 alpha-2 issuer country. Pair with currency for cross-border decisions.
bankNameIssuing bank's display name. May be empty for niche issuers; bankBicCode is the stable identifier.
supports.payouttrue if the issuer typically accepts inbound card payouts on this BIN range. A false here means createPayout with this card will likely fail with code -32104.
supports.threeDSecureWhether the issuer participates in 3-D Secure 2.0 for inbound charges. Informational; payouts do not trigger 3-DS.

Error response

{
  "error": {
    "message": "BIN not found.",
    "code": -32200
  }
}
codeMeaning
-32000Invalid secret key.
-32200BIN not found in any data source. Treat the destination as unknown — do not assume any default issuer attributes.
-32201BIN format invalid (fewer than 6 digits, more than 8 digits, or non-digit characters).
-32202Rate limit exceeded for this project. Cache the response client-side; see below.

Caching and freshness

  • BIN data changes slowly; caching responses by bin key for up to 30 days is appropriate for most use cases.
  • BIN ranges are occasionally reassigned between issuers and acquirers. Bust your cache after a confirmed wrong-issuer event — do not assume cached entries are immutable.
  • Per-project rate limit is 100 requests/min. The limit is generous for prevalidation traffic but does not allow bulk-scanning of BIN ranges.

Privacy and PCI considerations

BINs (the first 6–8 digits) are not personally identifying and fall outside PCI DSS cardholder data — you can log and cache them without invoking PCI scope. Never send the full PAN to getBinInfo; UnitPay rejects requests with more than 8 digits with error -32201, but the safer practice is to truncate at the call site so a full PAN never crosses your application boundary.

Test mode

Test-mode keys query the same BIN database as production. There is no separate sandbox dataset; lookups are deterministic and idempotent.

Next steps