Resolve the issuing bank of a BIN

GET https://api.veriko.mx/v1/public/bin-lookup/{bin}

Audience: public

Resolves the issuing SPEI bank of a card from its BIN, against the local bin_directory catalog. It is a pure read (one indexed database query, with no external network call): a BIN that is not in the catalog returns 404 and never triggers a lookup against external services.

Accepts 6 to 16 digits. Only the leading 6-8 are used (longest-prefix-wins: 8, then 7, then 6, most specific match wins). The BIN returned in the response (data.id / data.attributes.bin) is the 6-8 digit prefix that matched — never the full number you sent.

Privacy: for convenience the endpoint accepts a full card number, but it only needs the BIN. Send just the leading 6-8 digits whenever you can: a full card number (PAN) in the URL may be captured by intermediate logs (CDN, proxy) outside the API's control. The service never logs the received value and the response returns only the 6-8 digit BIN.

Anonymous-allowed (same rate-limited public catalog read as GET /v1/public/banks). The returned banxico_code is the 5-digit code used as bank_code when creating beneficiaries or as receptor when validating; it is null when the issuer is not SPEI-routable (e.g. Amex).

Parameters
Parameter	In	Type	Required	Description
`bin` *	path	`string`	required	BIN or card number (6 to 16 digits). Only the leading 6-8 are used; send just the BIN when possible.

Request

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/public/bin-lookup/{bin}' \
  -H 'Authorization: Bearer mxcep_••••'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `BinLookupResponse` — BIN resolved: issuing bank and card metadata.
Field	Type	Description
`type` *	`string`	JSON:API resource type.
`id` *	`string`	The 6-8 digit BIN that matched in the catalog.
`attributes` *	`object`	Issuing bank and card metadata associated with the BIN.
`bin` *	`string`	The matched BIN (same value as `id`; 6-8 digits).
`bank_name` *	`string`	Canonical Banxico name of the issuing bank.
`banxico_code` *	`string` nullable	5-digit Banxico SPEI code of the issuing bank, or `null` when the issuer is not SPEI-routable (e.g. Amex, vouchers).
`card_brand`	`string` nullable	Card network (VISA, MASTERCARD, …), or `null` if unknown.
`card_type`	`string` nullable	Card type (CREDIT, DEBIT, PREPAID, …), or `null` if unknown.
`card_level`	`string` nullable	Card level/tier (GOLD, PLATINUM, …), or `null` if unknown.
`country_iso` *	`string`	Issuing country as ISO-3166 alpha-2.

**Response status codes** `GET /v1/public/bin-lookup/{bin}`
Status	Class	Description	Body
200	`2xx`	BIN resolved: issuing bank and card metadata.	`BinLookupResponse`
404	`4xx`	The resource does not exist or is not visible to the caller	`Error`
422	`4xx`	Request validation failed.	`ErrorResponse`
429	`4xx`	Rate limit exceeded	`ErrorResponse`

**Errors from `GET /v1/public/bin-lookup/{bin}`**
Status	Code	Detail
422	`validation_error`	The fecha field is required. Envelope source.pointer `/data/attributes/fecha` meta.request_id `e6f7a8b9c0d1`
429	`rate_limit_exceeded`	Rate limit exceeded. Try again in 45 seconds. Envelope meta.request_id `f7a8b9c0d1e2` Response headers `Retry-After` : integer — Seconds to wait before retrying. Matches the endpoint's rate-limit window (typically 60s for list endpoints, 1-5s for in-flight idempotent operations). `X-RateLimit-Limit` : integer — Configured request cap for this bucket (emitted only on 429). `X-RateLimit-Remaining` : integer — Requests remaining in the current window — always 0 at the moment of the 429 (emitted only on 429). `X-RateLimit-Reset` : integer — Absolute Unix epoch (seconds) when the window resets. Emitted only on 429, alongside Retry-After. Per-endpoint overrides exist (e.g. `rate_limited_login`).