Introducción a Raw card-present API

26 junio 2025

Raw card-present API te permite integrar una terminal POS a nuestra red de pagos para procesar transacciones de forma rápida y segura. Puedes realizar diferentes operaciones con esta integración.

Características

Operaciones

Estas son las operaciones disponibles para integraciones a través de Raw card-present API:

• Venta
• Propina (pre y post)
• Pagos diferidos
• Reserva de saldo (pre-authorization) y captura (Capture)
• Reautorizaciones (reauthorization)
• Búsqueda de transacciones
• Cancelaciones y devoluciones

Tarjetas

Las siguientes son las redes y marcas de tarjeta aceptadas a través de integraciones Raw card-present API:

• Visa
• Mastercard
• Carnet
• Sodexo
• Sí Vale
• Edenred

Requisitos

Antes de poder realizar una integración, deberás cumplir con los siguientes requisitos:

• Completar el proceso de afiliación.
• Tener una cuenta de pruebas.
• Contar con terminales POS con certificación PCI PTS V6.0, EMV Contactless L1, EMV L1 y EMV L2.
• Recibir las llaves públicas y llaves privadas con las cuales podrás autenticar, validar y autorizar las transacciones provenientes de tu comercio.
• Realizar la firma de un Acuerdo de confidencialidad (NDA) del servicio HSM (Hardware Security Module), en el que se cargará la información de las claves criptográficas compartidas. Este proceso asegurará el resguardo de las claves y de esta manera, tu comercio podrá acceder al portal de MYHSM.
• Crear y mantener la información de los Security Officer (SO), incluyendo los detalles de contacto y los grupos de SO correctos dentro del portal. Estas personas serán las responsables de la seguridad en el proceso de intercambio de claves.
• Contar con un HSM (Hardware Security Module) para el almacenamiento seguro de claves de cifrado.

Certificación con marcas (Visa y Mastercard)

Se requiere certificación con las marcas Visa y Mastercard en los siguientes casos:

1. Cuando se realiza una nueva integración con Kushki debido a la incorporación de un nuevo adquirente o red de tarjetas (Visa, Mastercard, Amex, Diners).
2. Antes de lanzar un nuevo modelo de terminal o actualizar su firmware.
3. Si se modifica el kernel EMV o la lógica de transacción que impacta el flujo de pago.
4. Si así lo requiere alguno de los esquemas de las marcas (Visa, Mastercard, etc.).

Tipos de certificación

Cada marca tiene un proceso específico:

• Visa: requiere certificación con los protocolos ADVT (Acquirer Device Validation Toolkit) y CDET (Contactless Device Evaluation Toolkit).
• Mastercard: se requiere pasar la certificación M-TIP (Mastercard Terminal Integration Process).

Estas certificaciones validan que el hardware y software involucrado cumplen con los estándares técnicos y de seguridad requeridos por cada marca.

Acompañamiento durante la certificación

Kushki acompaña a los comercios en este proceso con el soporte de sus equipos de Ingeniería e Integraciones, garantizando que los escenarios cubiertos reflejen la operativa real del comercio.

También existen casas certificadoras autorizadas por las marcas que pueden brindar asistencia directa en la validación y ejecución del proceso. El comercio puede decidir con cuál entidad contratar este acompañamiento.

Entorno de certificación

La certificación no se realiza en el ambiente de pruebas tradicional, sino en un entorno dedicado:

https://api-qa-acq.orizaba.kushki.dev

Este ambiente está específicamente habilitado para ejecutar los casos de prueba requeridos por Visa y Mastercard.

¿Qué escenarios deben certificarse?

Solo es necesario certificar los escenarios reales que se operarán con Kushki. No es obligatorio validar casos que no se utilizarán.

Algunos ejemplos de escenarios que pueden formar parte de la certificación incluyen:

• Pagos con tarjeta débito o crédito.
• Transacciones contactless (sin contacto).
• Pagos por montos bajos (por debajo del monto piso) o montos altos.
• Transacciones con opción de cuotas.
• Combinaciones de los anteriores para cada marca.

La cantidad exacta y naturaleza de los casos a certificar dependerá del modelo de operación del comercio.

Ambientes

Realiza todas las adecuaciones a tu sistema mediante pruebas en el ambiente de desarrollo dev.

Cuando estés listo, podrás cambiar al ambiente de producción live para procesar transacciones reales.

Procesa un pago

Te contamos a continuación el proceso general del funcionamiento de pagos con tarjeta presente:

INTEGRACIÓN

La integración entre Kushki y tu comercio se establecerá a través de una API REST, la cuál emplea un sistema de claves criptográficas que permite el intercambio seguro de información mediante el cifrado de la información sensible que se lee de las tarjetas de tus clientes para procesar sus solicitudes de manera rápida y bajo estrictos estándares de seguridad y confidencialidad.

PROCESO DE PAGO DEL CLIENTE

Tu cliente presenta su tarjeta de crédito o tarjeta de débito física o digital en tu punto de venta. La terminal POS de tu comercio, la cual podrá estar conectada a través de USB, bluetooth u otros tipos de conexión, realiza las siguientes acciones:

• Realiza la lectura de los datos recibidos de tu cliente por medio de banda magnética, chip o pagos sin contacto (NFC).
• Envía la información leída de manera cifrada a tu backend para que este pueda enviar la información a Kushki por medio de la API REST.
• La API de Kushki procesa la solicitud y regresa una respuesta a tu backend con la aprobación o denegación de la solicitud recibida. En caso de ser una transacción exitosa, Kushki debita el monto de la transacción de la cuenta de tu cliente.

Claves de cifrado

Es requerido realizar una ceremonia de intercambio de claves criptográficas entre Kushki y tu comercio a través de módulos de seguridad de hardware (HSM) para asegurar la integridad y seguridad de la información. Deberás cifrar la información leída de la tarjeta de los clientes mediantes el proceso DUKPT utilizando las claves recibidas. Descubre más sobre el intercambio de claves criptográficas y revisa los datos de prueba.

Credenciales

Para enviar solicitudes a la API, deberás contar con tus credenciales válidas. Para obtener tus credenciales, inicia sesión en el panel de administración de acuerdo al ambiente (dev o live), selecciona el módulo de Desarrolladores en el menú lateral y selecciona la opción de Credenciales.

Puedes añadir una nueva credencial o utilizar una previamente creada.

Realizar un cobro

Consume el endpoint Single payment enviando la información requerida para procesar una transacción. Debes generar la mensajería de acuerdo a los datos leídos de la tarjeta a través de la terminal POS.

Ejemplo de una solicitud de cobro:

{
  "card": {
    "card_holder_name": "John Doe"
  },
  "amount": {
    "iva": 0,
    "tip": 0,
    "currency": "MXN",
    "subtotal_iva": 0,
    "subtotal_iva0": 2000
  },
  "country": "MEX",
  "pos_details": {
    "brand": "SUNMI",
    "model": "P2-EU",
    "version": "Kushki SunmiV1.1.13",
    "location": {
      "latitude": -0.1842214,
      "longitude": -78.4212761
    },
    "has_print": true,
    "terminal_id": "PB04209860189"
  },
  "card_details": {
    "tracks": {
      "track_ksn": "FFFF4357486333600002",
      "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
    },
    "enc_tlv": "CE447A062C49774934E42A7F826668C0A53CE9AF633A510E66C8031171AAFCF8CE29857B19101326ED67512533B86C51ED16C5E624DA97EDA72864A39763822418FCAC5439D2F1F72F6FC0BAA6EED37630767D9D161612654E49944FC435525C6C356177B1BD0A545C19FF5E47685E35B02B20B307BDE2A26FAD2F42D7CB00BE9C53FD05BECE71110919ADE3158398B8B02003F682374B942C4B6D7FD54DE2B65A9C66125DF28A80",
    "pin_ksn": "FFFF4357486333600002",
    "reading_type": "NFC"
  },
  "contact_details": {
    "email": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "document_type": "0",
    "document_number": "123666",
    "second_last_name": ""
  },
  "transaction_mode": "Authorization",
  "transaction_type": "charge",
  "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341"
}

Revisa el artículo Acepta pagos para más información.