Card information - Kushki Developer Portal

Los endpoints de Card Information te dan herramientas de consulta para los flujos presenciales: obtener el tipo de tarjeta y la disponibilidad de diferido a partir de un BIN, consultar las opciones de diferido de una tarjeta específica y listar las transacciones registradas en una terminal POS.

Resumen de endpoints

Endpoint	Propósito
`POST /pos/v1/bin`	Consulta de BIN — devuelve el tipo de tarjeta y la disponibilidad de diferido
`GET /deferred/v2/bin/{bin}`	Opciones de diferido v2 — tipos de diferido y meses para un BIN
`GET /card/v1/deferred/{bin}`	Opciones de diferido v1 — meses de diferido disponibles para un BIN
`POST /pos/v1/transaction`	Lista de transacciones — consulta las transacciones de una terminal POS

Consulta de BIN

Llama a POST /pos/v1/bin con el BIN de la tarjeta (primeros 6–8 dígitos) para saber si la tarjeta admite pagos diferidos antes de continuar.

Solicitud:

{
  "bin": "43810200",
  "pos_details": {
    "terminal_id": "T00000000000",
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13"
  }
}

Respuesta:

{
  "card_type": "debit",
  "country": "PER",
  "deferred": false
}

Campo de respuesta	Descripción
`card_type`	`"credit"`, `"debit"` o `"prepaid"`.
`country`	ISO 3166-1 alpha-3 del país emisor de la tarjeta.
`deferred`	`true` si la tarjeta admite diferido.

Opciones de diferido

Usa estos endpoints para obtener las configuraciones de diferido válidas de un BIN específico antes de crear un cargo diferido.

Solo tarjetas de crédito

Las opciones de diferido solo están disponibles para tarjetas de crédito.

v2 — `GET /deferred/v2/bin/{bin}`

Devuelve los metadatos de la tarjeta junto con las opciones de diferido.

GET /deferred/v2/bin/43810200
Public-Merchant-Id: <your-public-key>

Campos de respuesta:

Campo	Descripción
`bank`	Nombre del banco emisor.
`brand`	Marca de la tarjeta (por ejemplo, `"visa"`, `"mastercard"`).
`cardType`	`"credit"`, `"debit"` o `"prepaid"`.
`country`	País emisor de la tarjeta.

v1 — `GET /card/v1/deferred/{bin}`

Devuelve los tipos de diferido y los meses de diferido disponibles.

GET /card/v1/deferred/43810200
Public-Merchant-Id: <your-public-key>

Ejemplo de respuesta:

[
  {
    "months": ["2", "3", "4", "5", "6", "7"],
    "monthsOfGrace": [],
    "type": "all"
  }
]

Usa los valores de type y months al construir el objeto deferred en un request de cargo.

Lista de transacciones

POST /pos/v1/transaction con transaction_type: "balanceInquiry" devuelve una lista de las transacciones registradas en una terminal POS. Aplica filtros para acotar los resultados.

WARNING

Devuelve un máximo de 10.000 transacciones.

Solicitud:

{
  "transaction_type": "balanceInquiry",
  "transaction_mode": "Authorization",
  "country": "PER",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 0,
    "iva": 0
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13",
    "has_print": true
  }
}

Campos de cada elemento de la respuesta:

Campo	Descripción
`transaction_reference`	Referencia de la transacción del lado del comercio.
`transaction_status`	`APPROVED`, `DECLINED`, etc.
`transaction_type`	Tipo de la transacción original.
`payment_brand`	Marca de la tarjeta usada.
`reading_type`	`ICC`, `MCR` o `NFC`.
`amount`	Objeto con los totales de la transacción.
`deferred`	Detalles del diferido, si aplica.
`merchant_id`	Identificador del comercio.
`pos_details`	Detalles de la terminal.

Autenticación

Endpoint	Cabecera
`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>`

Usar la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Consulta de BIN

Consulta el BIN de una tarjeta para obtener el tipo de tarjeta y la disponibilidad de diferido.

Opciones de diferido v2

Obtén los metadatos del BIN y las configuraciones de diferido disponibles (v2).

Opciones de diferido v1

Obtén los meses de diferido disponibles para un BIN (v1).

Lista de transacciones

Consulta las transacciones registradas en una terminal POS con filtros opcionales.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Información de la tarjeta

Resumen de endpoints#

Consulta de BIN#

Opciones de diferido#

v2 — GET /deferred/v2/bin/{bin}#

v1 — GET /card/v1/deferred/{bin}#

Lista de transacciones#

Autenticación#

Usar la API#

Endpoints disponibles#

Resumen de endpoints

Consulta de BIN

Opciones de diferido

v2 — `GET /deferred/v2/bin/{bin}`

v1 — `GET /card/v1/deferred/{bin}`

Lista de transacciones

Autenticación

Usar la API

Endpoints disponibles