API Raw Card Present Payments 🇨🇱 - Kushki Developer Portal

La API Card Present te permite procesar pagos presenciales con tarjeta directamente desde tus terminales POS en Chile. Un único conjunto de endpoints cubre todo el ciclo de vida del pago: cargos únicos, autorización y captura en dos pasos, anulaciones, reembolsos y consultas de transacciones — en los canales de lectura chip (ICC), banda magnética (MCR) y contactless (NFC).

Operaciones disponibles

Pagos únicos

Procesa cargos inmediatos — únicos, diferidos (Cuotas Comercio y Cuotas Emisor), con cashback o con propina — en una sola llamada a la API.

Pagos en dos pasos

Bloquea el monto (preautorización) y captura cuando estés listo. Admite reautorización y operaciones sin lectura de tarjeta.

Anulaciones y reembolsos

Anula una autorización (void), reversa una transacción (reverse) o reembolsa un pago ya liquidado — total o parcial, con o sin lectura de tarjeta.

Información de la tarjeta

Consulta los datos del BIN, verifica la disponibilidad de diferido y revisa las opciones de Cuotas Comercio / Cuotas Emisor antes de iniciar un cargo.

Consultar transacciones

Busca y pagina las transacciones de tus terminales POS con filtros por fecha, BIN, dígitos de la tarjeta o referencia.

Cómo funciona

Todas las operaciones presenciales comparten una estructura de request común, construida alrededor de tres objetos principales: la intención de la transacción, los datos de la tarjeta y los detalles de la terminal.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "CHL",
  "client_transaction_id": "<uuid-v4>",
  "amount": {
    "currency": "CLP",
    "subtotal_iva": 0,
    "subtotal_iva0": 10000,
    "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": -33.4489,
      "longitude": -70.6693
    }
  }
}

Conceptos clave

Moneda

Chile usa CLP (peso chileno). El CLP no tiene decimales: todos los montos son enteros.

"amount": {
  "currency": "CLP",
  "subtotal_iva": 0,
  "subtotal_iva0": 10000,
  "iva": 0
}

Canales de lectura

Envía card_details.reading_type para indicar cómo se presentó la tarjeta.

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 (por ejemplo, transacciones de bajo monto, contactless)

Operaciones sin lectura de tarjeta

Chile tiene soporte completo para las operaciones sin lectura de tarjeta: no hace falta leer la tarjeta en anulaciones, reversos, reembolsos, capturas ni reautorizaciones. Envía omit_card: true para omitir card_details y cvm_type.

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

Cargos diferidos

Chile admite dos tipos de pagos diferidos. Llama siempre primero al BIN lookup para confirmar que la tarjeta admite el tipo de cuotas que quieres usar.

Tipo	Cómo activarlo	Rango
Cuotas Comercio (cuotas ofrecidas por el comercio)	`is_deferred: true` + `deferred.credit_type: "03"`	2–12 meses
Cuotas Emisor (cuotas ofrecidas por el emisor)	`is_deferred: true` — sin `credit_type`	2–48 meses

Beta

Cuotas Comercio (cuotas ofrecidas por el comercio) está actualmente en fase Beta. Contacta al equipo de Kushki para habilitar esta funcionalidad en tu Kushki Console.

Cortes de reverso, anulación y reembolso

Operación	Corte
Reverso (mismo día)	Antes de las 23:59 hora local de Chile — se usa para verificar el resultado de una transacción afectada por un timeout o un problema de comunicación
Anulación (mismo día)	Antes de las 23:59 hora local de Chile
Reembolso	Disponible después del corte de anulación, hasta 120 días desde la transacción original

Cashback

Chile admite cashback en el momento de un pago presencial. Envía is_cashback: true e incluye cashback_amount.

WARNING

El cashback solo está disponible con tarjetas locales y no se admite en transacciones contactless (NFC).

Idempotencia

Cada request debe incluir un client_transaction_id único (UUID v4). Reutilizar el mismo ID en los reintentos es seguro: Kushki devuelve el resultado de la transacción original sin crear un duplicado.

Modelos de integración

Chile admite los modelos Adquirente y Agregador.

Modelo	Descripción	Campos requeridos
Adquirente	Integración directa — el comercio está registrado directamente con Kushki	Body de request estándar
Agregador	Marketplace / facilitador de pagos — los subcomercios transaccionan bajo tu paraguas	Agrega el objeto `sub_merchant` al request

Agregador — objeto `sub_merchant`

"sub_merchant": {
  "mcc": "5411",
  "id_affiliation": "987654321",
  "soft_descriptor": "Mi Comercio Chile",
  "city": "Santiago",
  "country_ans": "CHL",
  "zip_code": "7550000",
  "address": "Av. Apoquindo 4501",
  "social_reason": "Mi Comercio Chile SpA",
  "code": "SUB001CHL"
}

Cifrado

Los datos de la tarjeta (TLV, track data, PIN blocks) deben cifrarse con el protocolo DUKPT (Derived Unique Key Per Transaction) antes de enviarse a la API. Kushki y el comercio 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 completo.

Webhooks

Kushki envía notificaciones webhook para todos los eventos presenciales: cargos, autorizaciones, capturas, anulaciones, reversos y reembolsos. Configura tus endpoints de webhook desde la Console (Developers > Webhooks).

WARNING

Los webhooks presenciales solo se pueden configurar desde la Console. No se admite la configuración de webhooks por API.

Autenticación

Operación	Cabecera
Cargos, anulaciones, reversos, reembolsos, BIN lookup, consulta de transacciones (analytics)	`Private-Credential-Id: <your-private-credential>`
Opciones de diferido	`Public-Merchant-Id: <your-public-key>`

Ambientes

🟢 Producción

🧪 Sandbox (UAT)

🔬 Certificación Visa / MC

https://api.kushkipagos.com/

Recursos adicionales

Proceso de intercambio de llaves

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

Datos de prueba

Montos y escenarios para pruebas en sandbox en Chile.

Catálogo de errores

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

Buenas prácticas

Buenas prácticas de seguridad e integración para pagos presenciales.

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

Pagos presenciales (API RAW)

Operaciones disponibles#

Cómo funciona#

Conceptos clave#

Moneda#

Canales de lectura#

Verificación del tarjetahabiente (cvm_type)#

Operaciones sin lectura de tarjeta#

Cargos diferidos#

Cortes de reverso, anulación y reembolso#

Cashback#

Idempotencia#

Modelos de integración#

Agregador — objeto sub_merchant#

Cifrado#

Webhooks#

Autenticación#

Ambientes#

Recursos adicionales#

Operaciones disponibles

Cómo funciona

Conceptos clave

Moneda

Canales de lectura

Verificación del tarjetahabiente (`cvm_type`)

Operaciones sin lectura de tarjeta

Cargos diferidos

Cortes de reverso, anulación y reembolso

Cashback

Idempotencia

Modelos de integración

Agregador — objeto `sub_merchant`

Cifrado

Webhooks

Autenticación

Ambientes

Recursos adicionales