The Card Information endpoints provide lookup tools for Card Present flows in Mexico 🇲🇽: retrieve card type and MSI availability from a BIN, fetch installment options for a specific card, and query transactions recorded on a POS terminal.
Endpoints at a glance#
| Endpoint | Purpose |
|---|
POST /pos/v1/bin | BIN lookup — returns card type and MSI availability |
GET /deferred/v2/bin/{bin} | MSI options v2 — installment types and months for a BIN |
GET /card/v1/deferred/{bin} | MSI options v1 — available installment months for a BIN |
POST /pos/v1/transaction | Transaction list — query transactions on a POS terminal |
BIN lookup#
Call POST /pos/v1/bin with the card BIN (first 6–8 digits) to determine whether the card supports MSI before proceeding.{
"bin": "43810200",
"pos_details": {
"terminal_id": "PB04209860189",
"brand": "SUNMI",
"model": "P2-EU",
"version": "Kushki SunmiV1.1.28"
}
}
{
"card_type": "credit",
"country": "MEX",
"deferred": true
}
| Response field | Description |
|---|
card_type | "credit", "debit", or "prepaid". |
country | ISO 3166-1 alpha-3 of the card-issuing country. |
deferred | true if the card supports MSI installment payments. |
MSI options#
Use these endpoints to retrieve valid MSI configurations for a BIN before creating a deferred charge. Always query MSI options first — available months depend on the specific card BIN.MSI is only available for credit cards.
v2 — GET /deferred/v2/bin/{bin}#
Returns card metadata together with installment options.GET /deferred/v2/bin/43810200
Public-Merchant-Id: <your-public-key>
| Field | Description |
|---|
bank | Issuing bank name. |
brand | Card network (e.g., "visa", "mastercard"). |
cardType | "credit", "debit", or "prepaid". |
country | Card-issuing country. |
v1 — GET /card/v1/deferred/{bin}#
Returns the available MSI months for a BIN.GET /card/v1/deferred/43810200
Public-Merchant-Id: <your-public-key>
[
{
"months": ["3", "6", "9", "12", "18"],
"monthsOfGrace": ["00"],
"type": "03"
}
]
type value | Meaning |
|---|
"03" | MSI (Meses Sin Intereses). Use credit_type: "03" and graceMonths: "00" in the charge request. |
Use the type and months values from this response to construct the deferred object in the charge request.
Transaction list#
POST /pos/v1/transaction with transaction_type: "balanceInquiry" returns a list of transactions recorded on a POS terminal.Returns a maximum of 10,000 transactions.
{
"transaction_type": "balanceInquiry",
"transaction_mode": "Authorization",
"country": "MEX",
"amount": {
"currency": "MXN",
"subtotal_iva": 0,
"subtotal_iva0": 0,
"iva": 0
},
"pos_details": {
"brand": "SUNMI",
"model": "P2-EU",
"version": "Kushki SunmiV1.1.28",
"has_print": true,
"terminal_id": "PB04209860189"
}
}
| Field | Description |
|---|
transaction_reference | Merchant-side transaction reference. |
transaction_status | APPROVED, DECLINED, VOIDED, or REFUNDED. |
transaction_type | Type of the original transaction. |
payment_brand | Card network used (e.g., "VISA", "MASTERCARD"). |
reading_type | ICC, MCR, or NFC. |
amount | Amount object with transaction totals. |
deferred | MSI installment details, if applicable. |
merchant_id | Merchant identifier. |
pos_details | Terminal details. |
Authentication#
| Endpoint | Header |
|---|
POST /pos/v1/bin | Private-Credential-Id: <your-private-credential> |
POST /pos/v1/transaction | Private-Credential-Id: <your-private-credential> |
GET /deferred/v2/bin/{bin} | Public-Merchant-Id: <your-public-key> |
GET /card/v1/deferred/{bin} | Public-Merchant-Id: <your-public-key> |
Environments#
https://api.kushkipagos.com/
Available Endpoints#
BIN Lookup
Query a card BIN to retrieve card type and MSI availability.
MSI Options v2
Retrieve BIN metadata and available MSI configurations (v2).
MSI Options v1
Retrieve available MSI months for a BIN (v1).
Transaction List
Query transactions recorded on a POS terminal with optional filters.
Got a suggestion on this documentation? Contact us.
