Card Payments - Kushki Developer Portal

La API de Card te permite tokenizar los datos de la tarjeta y procesar pagos de forma segura. Kushki maneja toda la información sensible de la tarjeta: tu servidor solo envía el token.

¡Ten en cuenta!

La generación del token requiere tu Private Key (Private-Merchant-Id). Nunca la expongas en código de cliente o de frontend: llama siempre al endpoint de token 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": "Camila Rodríguez",
    "number": "5451951574925480",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121"
  },
  "totalAmount": 150000,
  "currency": "COP"
}

⚠️ Expiración del token: Los tokens expiran en poco tiempo. Úsalos de inmediato: no los guardes para usarlos después.

Haz un cargo

Llama a POST /card/v1/charges con el token y el desglose del monto. Incluye contactDetails y, opcionalmente, orderDetails y productDetails para el scoring antifraude.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 150000,
    "ice": 0,
    "iva": 0,
    "currency": "COP"
  },
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "firstName": "Camila",
    "lastName": "Rodríguez",
    "email": "user@example.com",
    "phoneNumber": "+573001234567"
  }
}

Un cargo exitoso devuelve un ticketNumber y un transactionReference.

Procesa la respuesta

Revisa transactionStatus: "APPROVAL" significa que el cargo fue autorizado.

{
  "ticketNumber": "922513792073660814",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521"
}

Para la respuesta completa (detalles de la tarjeta, nombre del banco, montos), incluye "fullResponse": "v2" en tu request de cargo.

Monedas

Colombia admite una moneda:

Moneda	Código
Peso colombiano	`COP`

Tipos de documento

Valor	Descripción
`CC`	Cédula de Ciudadanía 🇨🇴
`NIT`	Número de Identificación Tributaria 🇨🇴
`CE`	Cédula de Extranjería 🇨🇴
`TI`	Tarjeta de Identidad 🇨🇴
`PP`	Pasaporte 🇨🇴

Cargos diferidos (cuotas)

Colombia admite pagos diferidos (cuotas). Primero llama al endpoint de opciones de diferido para saber qué planes de cuotas están disponibles para el BIN de la tarjeta del cliente y luego incluye el plan en el request de cargo.

Paso 1 — Consulta los planes disponibles

GET /card/v1/deferred/{bin}

La respuesta incluye los meses disponibles y el type del diferido:

[
  {
    "months": ["2", "3", "4", "5", "6", "7"],
    "monthsOfGrace": [],
    "type": "all"
  }
]

Paso 2 — Envía el cargo

Modelo agregador

Modelo de adquirencia

Envía months como campo de primer nivel en el body del cargo (no dentro del objeto deferred):

{
  "token": "24e5cc0d47fc4b2ab098bdb7d0b94569",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 300000,
    "ice": 0,
    "iva": 0,
    "currency": "COP"
  },
  "months": 3,
  "contactDetails": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "firstName": "Camila",
    "lastName": "Rodríguez",
    "email": "user@example.com",
    "phoneNumber": "+573001234567"
  }
}

Flujo de preautorización

Usa la preautorización para reservar fondos sin capturarlos de inmediato.

Autoriza

POST /card/v1/preAuthorization: reserva fondos en la tarjeta. Devuelve un ticketNumber.

Reautoriza (opcional)

POST /card/v1/reauthorization: extiende la ventana de la autorización o ajusta el monto reservado. Envía el ticketNumber original.

Captura

POST /card/v1/capture: captura el monto reservado (o una parte). Envía el ticketNumber original.

Anula (si no vas a capturar)

DELETE /v1/charges/{ticketNumber}: cancela la autorización y libera los fondos reservados.

Anulación y reembolso

Operación	Endpoint	Notas
Void	`DELETE /v1/charges/{ticketNumber}`	Anula una transacción. Admite anulación total y parcial.
Refund	`DELETE /v1/refund/{ticketNumber}`	Devuelve los fondos al tarjetahabiente. Admite reembolso total y parcial.

Para una anulación o un reembolso parcial, incluye el objeto amount en el body del request con el monto parcial.

Cargos recurrentes y validación de tarjeta (`transactionMode`)

Incluye transactionMode en la solicitud de token para flujos recurrentes o validación de tarjeta con monto cero:

Valor	Descripción
`initialRecurrence`	Marca la primera transacción de una serie recurrente.
`subsequentRecurrence`	Cargos recurrentes posteriores: no se requiere CVV una vez procesado un `initialRecurrence`.
`accountValidation`	Validación de tarjeta con monto cero. Confirma que la tarjeta es válida sin cobrarla.

Cargo sin token (v2)

POST /card/v2/charges acepta los datos de la tarjeta directamente en el body del request, sin necesidad de una llamada previa de token. Útil para integraciones servidor a servidor donde ya tienes los datos de la tarjeta.

Webhooks

Incluye un array webhooks en tu request de cargo o de preautorización para recibir notificaciones en tiempo real:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Kushki envía un POST a cada URL cuando cambia el estado de la transacción.

3D Secure

Colombia admite dos modos de 3DS:

Modo	Descripción
Insecure 3DS	Kushki maneja el flujo 3DS a través de kushki.js. Incluye el `jwt` que obtienes de la librería al solicitar el token.
Motor 3DS propio	Operas tu propio servidor 3DS. Incluye los campos con el resultado de la autenticación en `threeDomainSecure` — `cavv`, `eci` y `specificationVersion` para Visa; `directoryServerTransactionID`, `eci`, `ucaf`, `specificationVersion` y `collectionIndicator` para Mastercard.

Valores de ECI:

Visa — 05 y 06 son seguros; 07 es riesgoso.

Mastercard — 01 y 02 son seguros; 00 es riesgoso.

Para procesar una transacción riesgosa, envía también acceptRisk: true. Al hacerlo, el comercio asume la responsabilidad ante contracargos.

Network Tokens (BETA)

Para una explicación completa de las dos formas de usar network tokens (trae tu propio token, o deja que Kushki cree uno), consulta Network Tokens.

Colombia admite procesar transacciones con tarjetas tokenizadas por la red (tokens aprovisionados por Visa o Mastercard a través de wallets digitales como Apple Pay).

Para usar esta funcionalidad, envía isNetworkToken: true en tu request de token o de cargo sin token e incluye el objeto networkToken con los metadatos adicionales:

Campo	Descripción
`deviceType`	Tipo de dispositivo que origina la transacción tokenizada
`requestorId`	ID único que la red de tarjetas asigna al solicitante del token
`source`	Origen del token
`walletId`	Identificador de la wallet digital: `"01"` para Apple Pay, `"04"` para otras wallets
`authenticationLevel`	Nivel de autenticación realizado durante el aprovisionamiento del token
`mvv`	Merchant Verification Value de 10 dígitos (solo transacciones Visa)

Incluye también el campo cryptogram en el objeto card cuando el network token traiga un criptograma de la wallet digital o del servicio de tokens del emisor. El valor debe tener entre 20 y 28 caracteres alfanuméricos.

⚠️ BETA: Esta funcionalidad está disponible en Colombia. Contacta a tu ejecutivo de cuenta de Kushki antes de habilitarla.

Información del BIN

GET /card/v1/bin/{bin} y GET /deferred/v2/bin/{bin} devuelven los metadatos de la tarjeta (banco, marca, tipo de tarjeta, país emisor) para un BIN dado. Úsalos para determinar la elegibilidad de diferido y mostrar el logo de la marca en el checkout.

Verificación de cuenta

Para verificar una tarjeta sin cobrarla, solicita un token con totalAmount: 0. El flujo de token ejecuta una validación con monto cero contra la tarjeta.

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de tarjeta

Tokeniza los datos de la tarjeta. Devuelve un token de un solo uso para un único cargo.

Hacer un cargo

Haz un cargo a una tarjeta usando un token. Admite cargos únicos, diferidos, 3DS, webhooks y scoring antifraude.

Cargo sin token (v2)

Envía los datos de la tarjeta y haz el cargo en una sola llamada, sin token previo.

Anular una transacción

Anula una transacción antes de la liquidación. Admite anulación total y parcial.

Reembolsar una transacción

Devuelve los fondos al tarjetahabiente. Admite reembolso total y parcial.

Consultar opciones de diferido

Devuelve los planes de cuotas disponibles para el BIN de una tarjeta. Llámalo antes de enviar un cargo diferido.

Preautorización

Reserva fondos sin capturarlos de inmediato.

Preautorización sin token (v2)

Preautoriza con los datos de la tarjeta directamente, sin paso previo de token.

Reautorizar

Extiende o ajusta una autorización pendiente.

Capturar

Captura un monto autorizado previamente.

Verificación de cuenta

Verifica una tarjeta con una solicitud de token de monto cero.

Validar el OTP

Valida una contraseña de un solo uso para flujos 3DS basados en OTP.

Información del BIN

Obtén los metadatos de la tarjeta (banco, marca, tipo, país) por BIN.

Información del BIN v2

Consulta extendida de BIN, incluida la elegibilidad de diferido.

¿Tienes una sugerencia sobre esta documentación? Escríbenos.

Pagos con tarjeta

Flujo de pago#

Monedas#

Tipos de documento#

Cargos diferidos (cuotas)#

Paso 1 — Consulta los planes disponibles#

Paso 2 — Envía el cargo#

Flujo de preautorización#

Anulación y reembolso#

Cargos recurrentes y validación de tarjeta (transactionMode)#

Cargo sin token (v2)#

Webhooks#

3D Secure#

Network Tokens (BETA)#

Información del BIN#

Verificación de cuenta#

Autenticación#

Uso de la API#

Endpoints disponibles#

Flujo de pago

Monedas

Tipos de documento

Cargos diferidos (cuotas)

Paso 1 — Consulta los planes disponibles

Paso 2 — Envía el cargo

Flujo de preautorización

Anulación y reembolso

Cargos recurrentes y validación de tarjeta (`transactionMode`)

Cargo sin token (v2)

Webhooks

3D Secure

Network Tokens (BETA)

Información del BIN

Verificación de cuenta

Autenticación

Uso de la API

Endpoints disponibles