Introducción a Raw card-present API

16 octubre 2024

Raw card-present API te permite integrar una terminal POS con certificación PCI PTS V6.0, EMV Contactless L1, EMV L1 y EMV L2 a nuestra red de pagos para procesar transacciones de forma rápida y segura. Puedes realizar diferentes operaciones con esta integración.

Características

Terminales

Puedes integrar terminales POS que cuenten con certificaciones PCI PTS V6.0, EMV Contactless L1, EMV L1 y EMV L2. Revisa con tu gerente de cuenta la compatibilidad de tus terminales.

Operaciones

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

• Venta
• Cashback
• 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.

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.