API Raw Card Present Payments - Kushki Developer Portal

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

Una sola base URL y un solo endpoint principal cubren todo el ciclo de vida del pago: cargos únicos, autorización y captura en dos pasos, reversos, anulaciones, reembolsos y consultas de transacciones — en los canales de lectura chip (ICC), banda magnética (MCR) y contactless (NFC).

Operaciones disponibles

Pagos únicos

Cargos inmediatos — único, diferido, con cashback o con propina — en una sola llamada a la API.

Pagos en dos pasos

Reserva un monto (preautorización) y captura cuando estés listo. Soporta reautorización.

Anulaciones y reembolsos

Reversa una transacción con resultado desconocido, anúlala el mismo día o reembolsa un pago ya liquidado — total o parcial.

Consulta de transacciones

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

Cómo funciona

Todas las operaciones Card Present se envían al mismo endpoint y comparten una estructura de request común construida sobre cuatro objetos: la intención de la transacción, el monto, los datos de la tarjeta y los datos de la terminal.

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "COL",
  "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
  "amount": {
    "currency": "COP",
    "subtotal_iva": 0,
    "subtotal_iva0": 50000,
    "iva": 0,
    "tip": 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",
  "contact_details": {
    "document_type": "0",
    "document_number": "1234567890",
    "first_name": "Andrés",
    "last_name": "Martínez",
    "second_last_name": "Rojas",
    "email": "user@example.com",
    "phone_number": "+573912345678"
  },
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.28",
    "has_print": true,
    "terminal_id": "PB04209860189",
    "location": {
      "latitude": 4.7110,
      "longitude": -74.0721
    }
  }
}

Requeridos en la raíz: amount, card_details, client_transaction_id, country, pos_details, contact_details, transaction_type y cvm_type.

Conceptos clave

Moneda

Colombia usa COP (peso colombiano). Los montos se envían en pesos enteros — sin decimales.

"amount": {
  "currency": "COP",
  "subtotal_iva": 0,
  "subtotal_iva0": 50000,
  "iva": 0
}

¡Tenlo en cuenta!

No rellenes los montos con 00 para simular centavos — 50000 son cincuenta mil pesos, no quinientos. Rellenar cobraría a tu cliente 100× el monto previsto.

Los impuestos viajan dentro de amount: iva, subtotal_iva, subtotal_iva0 y el objeto opcional extra_taxes (iac, ice, airport_tax, travel_agency). Envía en 0 cualquier impuesto que no aplique a la transacción.

Canales de lectura

Envía card_details.reading_type para indicar 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 (por ejemplo, transacciones de bajo valor o contactless)

Identificación del tarjetahabiente (`contact_details`)

contact_details es requerido en Colombia, y document_type es el único campo obligatorio dentro de él.

`document_type`	Significado
`-1`	No se envía documento — `document_number` no es requerido
`0`	DNI — `document_number` es requerido (solo Colombia)
`1`	Pasaporte — `document_number` es requerido (solo Colombia)

document_number acepta hasta 11 caracteres. second_last_name aplica solo en Colombia. phone_number sigue el estándar E.164 (+573912345678).

Tipos y modos de transacción

Campo	Valores permitidos
`transaction_type`	`charge`, `preAuth`, `capture`, `reAuthorization`, `refund`
`transaction_mode`	`Authorization`, `Reverse`, `Void`

Cargos diferidos

Para diferir un pago, envía is_deferred: true y el objeto deferred con la cantidad de meses de diferido acordada con el tarjetahabiente:

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

WARNING

Colombia no usa credit_type ni graceMonths — esos pertenecen a Cuotas Comercio en Chile y a MSI en México. Basta con enviar solo months.

Cashback

Colombia admite cashback al momento de un pago presencial. Envía is_cashback: true y el monto en cashback_amount.

Importante

El cashback funciona solo con tarjetas locales.

El cashback no está soportado en transacciones contactless — asegúrate de que reading_type no sea NFC.

Propinas

Las propinas se cobran junto con el pago: incluye el valor en amount.tip en el charge original. En Colombia no existe una operación de post-tip separada.

Reverso, anulación y reembolso

Qué operación aplica depende del día y la hora en que se procesan la transacción original y la solicitud de cancelación.

Operación	Cuándo aplica
Reverso	Se excedió el tiempo de procesamiento y el resultado del cargo es desconocido (por ejemplo, un timeout). Solo el mismo día, antes de las 23:59 — espera al menos 1 minuto después de la transacción antes de reversar. Envía `transaction_mode: "Reverse"` y el `client_transaction_id` original.
Anulación	Se sabe que la transacción fue aprobada y se cancela el mismo día, antes de las 23:59 (aproximado) — el corte exacto depende del procesador. Se realizan hasta 3 intentos; una vez aprobada, el cargo desaparece del estado de cuenta del tarjetahabiente. Envía `transaction_mode: "Void"` y el `transaction_reference` original.
Reembolso	Se solicita después del corte de anulación, en un día distinto, o cuando ya se agotaron los 3 intentos de anulación. Máximo 120 días desde la transacción original. Se admiten reembolsos parciales incluyendo el objeto `amount`.

Los reembolsos son la única operación que se envía a una ruta distinta:

WARNING

Las operaciones sin tarjeta (omit_card: true) no están disponibles en Colombia. Están disponibles de forma general en Chile y en Beta en México y Perú. Toda anulación, reverso, reembolso, captura y reautorización en Colombia requiere leer la tarjeta.

Idempotencia

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

Modelos de integración

Modelo	Descripción	Campos requeridos
Adquirente	Integración directa — el comercio está registrado con Kushki	Body del request estándar
Agregador	Marketplace / facilitador de pagos — los subcomercios transan 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 Colombia",
  "city": "Bogotá",
  "country_ans": "COL",
  "zip_code": "110221",
  "address": "Cra. 7 #71-52",
  "social_reason": "Mi Comercio Colombia S.A.S.",
  "code": "SUB001COL"
}

mcc es un Merchant Category Code de 4 caracteres, country_ans sigue ISO 3166-1 alpha-3 y social_reason aplica solo a transacciones Visa.

Cifrado

Los datos de la tarjeta — TLV, track data y PIN blocks — deben cifrarse con el protocolo DUKPT (Derived Unique Key Per Transaction) antes de enviarse a la API. El track data debe cifrarse en formato hexadecimal, reemplazando = por una D mayúscula. Kushki y tu organización intercambian 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 el procedimiento paso a paso.

Webhooks

Kushki envía notificaciones POST a tu endpoint configurado para cada evento de Card Present: cargos, preautorizaciones, capturas, reversos, anulaciones y reembolsos.

WARNING

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

Consulta Webhooks — Introducción para conocer las cabeceras de autenticación, la verificación de firma y las IP estáticas.

Autenticación

Cada request debe incluir la credencial de tu comercio en la cabecera:

Operación	Cabecera
Cargos, preautorizaciones, capturas, reversos, anulaciones, reembolsos	`Private-Credential-Id: <your-private-credential>`
Consulta de transacciones (analytics)	`Private-Credential-Id: <your-private-credential>`

Entornos

🟢 Producción

🧪 Sandbox (UAT)

🔬 Certificación Visa / MC

https://api.kushkipagos.com/

Recursos adicionales

Objeto Amount

Referencia completa de 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 Colombia.

Catálogo de errores

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

Buenas prácticas

Buenas prácticas de seguridad e integración para Card Present.

Notas de versión

Historial de versiones y changelog de la API Card Present en Colombia.

¿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)#

Identificación del tarjetahabiente (contact_details)#

Tipos y modos de transacción#

Cargos diferidos#

Cashback#

Propinas#

Reverso, anulación y reembolso#

Idempotencia#

Modelos de integración#

Agregador — objeto sub_merchant#

Cifrado#

Webhooks#

Autenticación#

Entornos#

Recursos adicionales#

Operaciones disponibles

Cómo funciona

Conceptos clave

Moneda

Canales de lectura

Verificación del tarjetahabiente (`cvm_type`)

Identificación del tarjetahabiente (`contact_details`)

Tipos y modos de transacción

Cargos diferidos

Cashback

Propinas

Reverso, anulación y reembolso

Idempotencia

Modelos de integración

Agregador — objeto `sub_merchant`

Cifrado

Webhooks

Autenticación

Entornos

Recursos adicionales