Card Payments - Kushki Developer Portal

La API de Card te permite tokenizar los datos de la tarjeta y procesar pagos de forma segura en México. Kushki maneja toda la información sensible de la tarjeta: tu servidor solo envía el token. Todos los montos van en pesos mexicanos (MXN).

¡Tenlo en cuenta!

Hay dos credenciales y no son intercambiables:

Public Key (Public-Merchant-Id): tokenización y consultas de tarjeta — POST /card/v1/tokens, POST /rules/v1/secureValidation, GET /card/v1/deferred/{bin}, GET /card/v1/bin/{bin} y GET /deferred/v2/bin/{bin}.

Private Key (Private-Merchant-Id): todas las operaciones que mueven dinero — cargos, preautorizaciones, reautorizaciones, capturas, anulaciones y reembolsos.

Nunca expongas la Private Key en código del lado del cliente ni del frontend: llama a esos endpoints desde tu backend.

Flujo de pago

Solicita un token de tarjeta

Llama a POST /card/v1/tokens desde tu backend con los datos de la tarjeta y el monto de la transacción. La respuesta devuelve un token de un solo uso, válido para un único cargo.

{
  "card": {
    "name": "Juan Pérez",
    "number": "4242424242424242",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 116,
  "currency": "MXN"
}

Haz el cargo

Envía POST /card/v1/charges con el token y el desglose del monto (amount). El IVA en México normalmente es del 16 %.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 100,
    "subtotalIva0": 0,
    "iva": 16,
    "currency": "MXN"
  }
}

Modelos de integración

Algunas capacidades solo están disponibles en el modelo Acquirer. Confirma tu modelo con tu ejecutivo de cuenta de Kushki antes de integrar.

Capacidad	Disponibilidad
Network tokens (`isNetworkToken`, `networkToken`, `cryptogram`)	Solo Acquirer — BETA en México
`isoErrorCode` en cargos declinados	Solo Acquirer, y únicamente cuando `fullResponse` es `v2`
`messageFields` (códigos de respuesta adicionales de la marca)	Solo Acquirer

Tipos de documento

Tipo	Descripción
`CC`	Documento de identidad.
`CURP`	Clave Única de Registro de Población.
`RFC`	Registro Federal de Contribuyentes.

Pagos diferidos — Meses Sin Intereses (MSI)

México admite pagos diferidos con Meses Sin Intereses (MSI).

Consulta los planes disponibles

Llama a GET /card/v1/deferred/{bin} con el BIN de la tarjeta para obtener los planes de MSI que permite el emisor. Este es el endpoint recomendado para MSI. Admite los primeros seis u ocho dígitos del número de tarjeta.

Envía el cargo diferido

Envía POST /card/v1/charges incluyendo el objeto deferred:

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": { "subtotalIva": 100, "subtotalIva0": 0, "iva": 16, "currency": "MXN" },
  "deferred": {
    "creditType": "03",
    "graceMonths": "0",
    "months": 6
  }
}

creditType: "03" corresponde a Meses Sin Intereses. Los valores disponibles de months dependen del banco emisor.

Pagos en dos pasos (preautorización y captura)

Reserva los fondos ahora y captúralos después: útil para pedidos que se confirman luego del checkout.

Preautoriza

POST /card/v1/preAuthorization reserva el monto en la cuenta del tarjetahabiente.

Captura

POST /card/v1/capture cobra el monto reservado (total o parcial).

Reautoriza (opcional)

POST /card/v1/reauthorization ajusta un monto preautorizado antes de la captura.

Pagos sin token

Si tu integración cumple con PCI, puedes enviar los datos de la tarjeta directamente, sin el paso aparte de token:

POST /card/v2/charges: cargo sin token.

POST /card/v2/preAuthorization: preautorización sin token.

3D Secure

Puedes dejar que Kushki ejecute el challenge de 3DS o enviar el resultado de tu propio motor de autenticación.

3DS gestionado por Kushki

Envía require3DS en true al solicitar el token (POST /card/v1/tokens). Kushki ejecuta el challenge y devuelve el resultado de la autenticación.

Motor 3DS propio

Si usas tu propio motor, envía el objeto threeDomainSecure en el cargo. Los campos obligatorios dependen de la marca de la tarjeta:

Campo	Visa	Mastercard
`cavv`	Obligatorio	—
`ucaf`	—	Obligatorio
`eci`	Obligatorio	Obligatorio
`specificationVersion`	Obligatorio	Obligatorio
`collectionIndicator`	—	Obligatorio
`directoryServerTransactionID`	—	Obligatorio

specificationVersion admite 2.0.0 y 2.2.0. El soporte para 3D Secure 1.0.2 terminó en octubre de 2022, así que hay que usar la versión 2 del protocolo.

Electronic Commerce Indicator (eci): es el valor que devuelve el directory server con el resultado del intento de autenticación.

Marca	Valor	Significado
Visa	`05`, `06`	Transacción segura.
Visa	`07`	Transacción riesgosa. Envía `acceptRisk` en `true` para procesarla.
Mastercard	`01`, `02`	Transacción segura.
Mastercard	`00`	Transacción riesgosa. Envía `acceptRisk` en `true` para procesarla.

collectionIndicator (solo Mastercard):

Valor	Para ECI	Significado
`0`	`00`	La autenticación 3DS falló o no se pudo intentar.
`1`	`01`	El emisor no está listo, pero hay traslado de responsabilidad porque el comercio sí solicitó 3DS.
`2`	`02`	Transacción autenticada por el emisor, con traslado de responsabilidad.

Responsabilidad

Al enviar acceptRisk en true, el comercio asume la responsabilidad en caso de chargebacks.

Network Tokens

Un network token reemplaza el PAN de la tarjeta por un token provisionado por la red de pago (Visa, Mastercard) o por una wallet digital. BETA — disponible solo en el modelo Acquirer.

Envía isNetworkToken en true junto con el objeto networkToken. Si omites el campo o lo envías en false, el número de tarjeta se trata como un PAN tradicional.

Disponible en:

POST /card/v1/tokens: acepta además cryptogram.

POST /card/v2/charges: cargo sin token.

Campo	Descripción
`walletId`	`01` para Apple Pay, `04` para otras wallets.
`requestorId`	Identificador del solicitante del token que asigna la red.
`source`	Origen del token.
`deviceType`	Tipo de dispositivo del que proviene el token.
`authenticationLevel`	Nivel de autenticación aplicado.
`mvv`	Merchant Verification Value.

Anulaciones y reembolsos

Acción	Endpoint	Cuándo
Anulación	`DELETE /v1/charges/{ticketNumber}`	Reversa el mismo día, antes de la liquidación.
Reembolso	`DELETE /v1/refund/{ticketNumber}`	Después de la liquidación: devuelve los fondos al tarjetahabiente.

Idempotencia

Envía la cabecera Idempotency-Key para reintentar una operación de forma segura, sin duplicarla. Las llaves tienen una vigencia de 24 horas.

Endpoint	`Idempotency-Key`
`DELETE /v1/charges/{ticketNumber}` (anulación)	Obligatoria
`DELETE /v1/refund/{ticketNumber}` (reembolso)	Opcional

Validación de OTP e información de la tarjeta

POST /rules/v1/secureValidation: valida el challenge de OTP cuando se requiere autenticación. Envía secureServiceId y otpValue; los dos son obligatorios.

GET /card/v1/bin/{bin}: obtén la información del BIN de la tarjeta (marca, tipo, emisor). Admite solo los primeros seis dígitos.

GET /deferred/v2/bin/{bin}: la misma información, admitiendo los primeros ocho a diez dígitos.

Los tres endpoints no son intercambiables: cada uno admite una longitud de BIN distinta, y solo GET /card/v1/deferred/{bin} devuelve planes de MSI.

Pagos con tarjeta

Flujo de pago#

Modelos de integración#

Tipos de documento#

Pagos diferidos — Meses Sin Intereses (MSI)#

Pagos en dos pasos (preautorización y captura)#

Pagos sin token#

3D Secure#

3DS gestionado por Kushki#

Motor 3DS propio#

Network Tokens#

Anulaciones y reembolsos#

Idempotencia#

Validación de OTP e información de la tarjeta#

Flujo de pago

Modelos de integración

Tipos de documento

Pagos diferidos — Meses Sin Intereses (MSI)

Pagos en dos pasos (preautorización y captura)

Pagos sin token

3D Secure

3DS gestionado por Kushki

Motor 3DS propio

Network Tokens

Anulaciones y reembolsos

Idempotencia

Validación de OTP e información de la tarjeta