Card Present Payments (API Raw) - Kushki Developer Portal

La API Card Present te permite procesar pagos presenciales con tarjeta directamente desde tus terminales POS en Perú. 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).

Beta

Los pagos presenciales están en fase Beta. Contacta a tu ejecutivo de cuenta para obtener acceso.

Operaciones disponibles

Pagos únicos

Procesa cargos inmediatos — únicos, diferidos, 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 captura 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 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.

POST /pos/v1/transaction
Private-Merchant-Id: <your-private-key>
Content-Type: application/json

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "country": "PER",
  "client_transaction_id": "<uuid-v4>",
  "amount": {
    "currency": "PEN",
    "subtotal_iva": 0,
    "subtotal_iva0": 500,
    "iva": 0
  },
  "card_details": {
    "reading_type": "ICC",
    "enc_tlv": "<encrypted-tlv>",
    "pin_ksn": "<ksn-value>"
  },
  "cvm_type": "pin",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "1.1.13"
  }
}

Conceptos clave

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`
`MCR`	Banda magnética	`tracks.enc_track2`, `tracks.track_ksn`
`NFC`	Contactless	`enc_tlv` y/o `tracks` según la tarjeta

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

Para anulaciones, reversos, reembolsos, capturas y reautorizaciones en las que volver a leer la tarjeta no es práctico, envía omit_card: true. En este caso los campos card_details y cvm_type son opcionales.

Cargos diferidos

Para procesar un pago en cuotas, envía is_deferred: true e incluye el objeto deferred. Llama siempre primero al endpoint BIN lookup para confirmar que la tarjeta admite cuotas.

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

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 en lugar de crear un duplicado.

Monedas

Moneda	Código
Sol peruano	`PEN`
Dólar estadounidense	`USD`

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 Key Exchange Process 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).

Consulta Introduction para la verificación de firma y Card Payments / Refunds para la estructura del body del webhook.

WARNING

Los webhooks de pagos 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, reembolsos, listado de transacciones	`Private-Merchant-Id: <your-private-key>`
BIN lookup, información de la tarjeta	`Private-Credential-Id: <your-private-credential>`
Opciones de diferido, información del BIN	`Public-Merchant-Id: <your-public-key>`
Consulta de transacciones (analytics)	`Private-Credential-Id: <your-private-credential>`

Cómo usar la API

🟢 Producción

🧪 Sandbox (UAT)

[https://api.kushkipagos.com/](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 Perú.

Catálogo de errores

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

Notas de versión

Últimos cambios e historial de versiones de la API Card Present.

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

Pagos presenciales (API RAW)

Operaciones disponibles#

Cómo funciona#

Conceptos clave#

Canales de lectura#

Verificación del tarjetahabiente (cvm_type)#

Operaciones sin lectura de tarjeta#

Cargos diferidos#

Idempotencia#

Monedas#

Cifrado#

Webhooks#

Autenticación#

Cómo usar la API#

Recursos adicionales#

Operaciones disponibles

Cómo funciona

Conceptos clave

Canales de lectura

Verificación del tarjetahabiente (`cvm_type`)

Operaciones sin lectura de tarjeta

Cargos diferidos

Idempotencia

Monedas

Cifrado

Webhooks

Autenticación

Cómo usar la API

Recursos adicionales