API Raw Card Present - Kushki Developer Portal

La API Raw de Card Present te da acceso directo y de bajo nivel a la infraestructura de pagos de Kushki para procesar transacciones presenciales con tarjeta en México. Tú te haces cargo de todo el stack de integración — el firmware de la terminal, el cifrado DUKPT, la lectura de la tarjeta y la construcción del request — y a cambio obtienes la máxima flexibilidad.

Una sola base URL cubre todas las operaciones del ciclo de vida del pago: cargos, autorizaciones en dos pasos, anulaciones, reembolsos, flujos sin lectura de tarjeta, consultas de BIN, opciones de diferido MSI y consultas de transacciones.

URLs base

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Secciones de la API

Pagos únicos

Cargo único, diferido MSI (Meses Sin Intereses) y propina — todo en una sola llamada a la API

Pagos en dos pasos

Flujo de preautorización → captura. Admite reautorización y operaciones sin lectura de tarjeta.

Anulaciones y reembolsos

Anulaciones y reversos el mismo día, y reembolsos después de la liquidación — con o sin lectura de tarjeta.

Información de la tarjeta

Consulta de BIN y de opciones de MSI. Llámalas siempre antes de iniciar un cargo diferido.

Consultar transacciones

Búsqueda paginada de transacciones con filtros por fecha, BIN, últimos dígitos o referencia.

Autenticación

Cada request debe incluir tu llave de comercio en la cabecera que corresponda según la operación:

Operación	Cabecera
Cargos, anulaciones y reembolsos	`Private-Merchant-Id: <your-private-key>`
Consulta de BIN y listado de transacciones	`Private-Credential-Id: <your-private-credential>`
Opciones de diferido MSI	`Public-Merchant-Id: <your-public-key>`
Consultar transacciones (analytics)	`Private-Credential-Id: <your-private-credential>`

Anatomía del request

Todas las operaciones de escritura comparten la misma estructura base:

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "MEX",
  "client_transaction_id": "ae6dd41a-9173-4ec7-8734-3178454ef341",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  },
  "card_details": {
    "reading_type": "ICC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>",
    "tracks": {
      "enc_track2": "<encrypted-track2>",
      "track_ksn": "<ksn-value>"
    }
  },
  "cvm_type": "pin",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189",
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332
    }
  }
}

Conceptos clave

Moneda

México usa MXN (peso mexicano). El MXN admite dos decimales.

"amount": {
  "currency": "MXN",
  "subtotal_iva": 580,
  "subtotal_iva0": 0,
  "iva": 80
}

Consulta El objeto Amount para ver la referencia completa de campos y ejemplos de cálculo del IVA.

Canales de lectura de la tarjeta

Envía card_details.reading_type según cómo se presentó la tarjeta en la terminal:

Valor	Canal	Datos de tarjeta requeridos
`ICC`	Chip (EMV)	`enc_tlv`, `pin_ksn`, `tracks.enc_track2`, `tracks.track_ksn`
`MCR`	Banda magnética	`tracks.enc_track1`, `tracks.enc_track2`
`NFC`	Contactless	`enc_tlv`, `tracks.enc_track2`, `tracks.track_ksn`

Verificación del tarjetahabiente (`cvm_type`)

Valor	Significado
`pin`	PIN en línea — el PIN block cifrado se envía en `card_details.pin_block`
`signature`	Firma en la terminal
`none`	Sin CVM (transacciones de bajo monto o contactless)

MSI — Meses Sin Intereses

México admite el diferido MSI. Llama siempre primero a Get BIN Info para confirmar que la tarjeta lo admite y obtener las opciones de meses válidas.
Para disparar un cargo MSI, agrega el objeto deferred con el valor de months que devuelve GET /card/v1/deferred/{bin}:

{
  "is_deferred": true,
  "deferred": {
    "months": "6",
    }
}

WARNING

Los cargos MSI por debajo del monto mínimo del plazo elegido se rechazan. Revisa la tabla siguiente antes de enviar el request.

Montos mínimos para MSI en México

Meses	Monto mínimo
3	$300 MXN
6	$600 MXN
9	$900 MXN
12	$1,200 MXN
18	$1,800 MXN

Operaciones sin lectura de tarjeta

Beta

Las operaciones sin lectura de tarjeta están actualmente en fase Beta en México. Contacta al equipo de Kushki para habilitar esta funcionalidad.

Envía omit_card: true para omitir card_details y cvm_type. Está disponible en capturas, reautorizaciones, anulaciones, reversos y reembolsos.

{
  "transaction_type": "capture",
  "transaction_mode": "Authorization",
  "omit_card": true,
  "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
  "amount": {
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  }
}

Cortes de anulación y reembolso

Operación	Ventana
Anulación	El mismo día, antes de las 22:59 hora local de México
Reverso sin lectura de tarjeta	El mismo día, antes de las 22:59 hora local de México — usa `client_transaction_id`
Reembolso	Después del corte de anulación, hasta 120 días desde la transacción original

Idempotencia

Cada request debe incluir un `client_transaction_id` único (UUID v4). Si reintentas el mismo request con el mismo ID, Kushki devuelve el resultado original: no se crea una transacción duplicada.

Modelos de integración

Modelo	Descripción	Requerido
Adquirente	El comercio está registrado directamente con Kushki	Body de request estándar
Agregador	Marketplace o facilitador de pagos — los subcomercios operan bajo tu paraguas	Agrega `sub_merchant` al request

Agregador — objeto `sub_merchant`

"sub_merchant": {
  "mcc": "5411",
  "id_affiliation": "987654321",
  "soft_descriptor": "Mi Comercio México",
  "city": "Ciudad de México",
  "country_ans": "MEX",
  "zip_code": "06600",
  "address": "Av. Insurgentes Sur 1234",
  "social_reason": "Mi Comercio México S.A. de C.V.",
  "code": "SUB001MEX"
}

Cifrado

Todos los datos de la tarjeta — TLV, track data y PIN blocks — deben cifrarse con el protocolo DUKPT antes de enviarse a la API. Kushki y tu organización intercambian las Base Derivation Keys (BDK) mediante una ceremonia segura de Key Encryption Key (KEK) antes de salir a producción.
Consulta Proceso de intercambio de llaves para conocer el procedimiento paso a paso.

Webhooks

Kushki envía notificaciones POST al endpoint que configures para cada evento presencial: cargos, preautorizaciones, capturas, anulaciones, reversos y reembolsos.

WARNING

Los webhooks presenciales solo se pueden configurar desde la Console (Developers > Webhooks). No se admite la configuración de webhooks por API.

Evento	Referencia del body del webhook
Charge, preAuth, capture, void, reverse	Pagos con tarjeta
Refund	Reembolsos
Consulta Webhooks — Introducción para conocer las cabeceras de autenticación, la verificación de la firma y las IPs estáticas.

Documentación de referencia

El objeto Amount

Referencia completa de los campos del objeto amount — IVA, subtotales, propina e impuestos adicionales.

Proceso de intercambio de llaves

Ceremonia DUKPT/KEK requerida antes de procesar transacciones en producción.

Datos de prueba

Montos y escenarios de tarjeta para pruebas en sandbox en México.

Catálogo de errores

Códigos de estado HTTP y códigos de error ISO para Visa y Mastercard.

Webhooks

Recibe notificaciones de pago.

Notas de versión

Historial de versiones y changelog de la API Card Present en México.

¿Tienes una sugerencia sobre esta documentación? Contáctanos.

Pagos presenciales (API RAW)

URLs base#

Secciones de la API#

Autenticación#

Anatomía del request#

Conceptos clave#

Moneda#

Canales de lectura de la tarjeta#

Verificación del tarjetahabiente (cvm_type)#

MSI — Meses Sin Intereses#

Operaciones sin lectura de tarjeta#

Cortes de anulación y reembolso#

Idempotencia#

Cada request debe incluir un client_transaction_id único (UUID v4). Si reintentas el mismo request con el mismo ID, Kushki devuelve el resultado original: no se crea una transacción duplicada.#

Modelos de integración#

Agregador — objeto sub_merchant#

Cifrado#

Webhooks#

Documentación de referencia#

URLs base

Secciones de la API

Autenticación

Anatomía del request

Conceptos clave

Moneda

Canales de lectura de la tarjeta

Verificación del tarjetahabiente (`cvm_type`)

MSI — Meses Sin Intereses

Operaciones sin lectura de tarjeta

Cortes de anulación y reembolso

Idempotencia

Cada request debe incluir un `client_transaction_id` único (UUID v4). Si reintentas el mismo request con el mismo ID, Kushki devuelve el resultado original: no se crea una transacción duplicada.

Modelos de integración

Agregador — objeto `sub_merchant`

Cifrado

Webhooks

Documentación de referencia