Card Payments - Kushki Developer Portal

Acepta pagos con tarjeta de crédito y débito en Chile 🇨🇱: cargos únicos, Cuotas Comercio, Cuotas Emisor, flujos de preautorización y network tokens.

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 trabaja con tokens.

Se requiere la Private Key

La generación del token requiere tu Private Key (Private-Merchant-Id). Nunca la expongas en código del lado del cliente ni del 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 total. Devuelve un token de un solo uso, válido para un único cargo.

{
  "card": {
    "name": "Catalina Fuentes",
    "number": "5451951574925480",
    "expiryMonth": "05",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 10000,
  "currency": "CLP"
}

⚠️ Expiración del token: Los tokens expiran en poco tiempo. Úsalos de inmediato: no los guardes para 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": 10000,
    "ice": 0,
    "iva": 0,
    "currency": "CLP"
  },
  "contactDetails": {
    "documentType": "RUT",
    "documentNumber": "12345678-9",
    "firstName": "Catalina",
    "lastName": "Fuentes",
    "email": "user@example.com",
    "phoneNumber": "+56912345678"
  }
}

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 el request del cargo.

Moneda

Chile admite dos monedas:

Moneda	Código	Notas
Peso chileno	`CLP`	Solo montos enteros: sin decimales
Unidad de Fomento	`UF`	Unidad monetaria indexada

CLP no tiene decimales

Envía siempre los montos en CLP como números enteros (por ejemplo, 10000).

Tipos de documento

Valor	Descripción
`RUT`	Rol Único Tributario 🇨🇱
`CC`	Cédula de Identidad 🇨🇱
`PP`	Pasaporte 🇨🇱

Modelos de integración

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

Operación	Acquirer	Aggregator
Request a card token	✅	✅
Make a charge or deferred charge	✅	✅
Create payment (tokenless)	✅	—
Void a transaction	✅	✅
Refund a transaction	✅	✅
Request deferred options	✅	✅
Authorize payments	✅	✅
Preauthorization (tokenless)	✅	—
Reauthorize payments	✅	—
Capture an authorized payment	✅	✅
Verify Account	✅	—
Validate OTP	✅	✅
BIN Info / BIN Info v2	✅	✅
Cargos recurrentes (`transactionMode`)	✅	—
Motor 3DS propio	✅	—
Motor de suscripciones propio	✅	—

Cargos diferidos (cuotas)

Chile admite dos tipos de diferido. Llama siempre primero al endpoint de opciones de diferido para verificar que el BIN de la tarjeta admite cuotas y para obtener las opciones de meses válidas.

Paso 1 — Consulta los planes disponibles

GET /card/v1/deferred/{bin}

Ejemplo de respuesta:

[
  {
    "months": ["2", "3", "6", "12"],
    "monthsOfGrace": [],
    "type": "03"
  }
]

El campo type te dice qué tipos de diferido admite el BIN:

`type`	Significado
`all`	Todos los tipos disponibles: incluye Cuotas Comercio y Cuotas Emisor
`03`	Solo Cuotas Comercio (cuotas del comercio, sin interés)

Paso 2 — Envía el cargo

Cuotas Comercio (Merchant Installments) — Beta

Cuotas Emisor (Issuer Installments)

⚠️ Beta: Cuotas Comercio (creditType 03) está en fase Beta para Chile. La estructura de datos y la lógica pueden cambiar sin aviso previo. Contacta al equipo de Kushki para habilitar esta funcionalidad.

El comercio absorbe el costo de las cuotas. Envía el objeto deferred con creditType: "03". Disponible de 2 a 12 meses. Los tres campos (graceMonths, creditType y months) son obligatorios.

{
  "token": "24e5cc0d47fc4b2ab098bdb7d0b94569",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 30000,
    "ice": 0,
    "iva": 0,
    "currency": "CLP"
  },
  "deferred": {
    "graceMonths": "00",
    "creditType": "03",
    "months": 6
  },
  "contactDetails": {
    "documentType": "RUT",
    "documentNumber": "12345678-9",
    "firstName": "Catalina",
    "lastName": "Fuentes",
    "email": "user@example.com",
    "phoneNumber": "+56912345678"
  }
}

Flujo de preautorización

Usa la preautorización para reservar fondos sin capturarlos de inmediato: es ideal para flujos de hotelería, arriendo de autos o marketplace.

Autoriza

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

En Chile la autorización expira después de:

28 días para tarjetas de crédito

7 días para tarjetas de débito

Reautoriza (opcional)

POST /card/v1/reauthorization: extiende el monto o el efecto de la autorización original. Envía el ticketNumber original. La moneda debe coincidir con la de la autorización original.

Si el pago no se captura dentro de 7 días (débito) o 28 días (crédito), el banco emisor puede devolverle al tarjetahabiente los fondos retenidos.

Captura

POST /card/v1/capture: captura los fondos reservados (monto total o parcial). Usa el ticketNumber de la autorización, no de una reautorización.

El monto máximo a capturar puede ser hasta un 10% mayor que la autorización inicial más las reautorizaciones que no se hayan cancelado.

Anula (si no vas a capturar)

DELETE /v1/charges/{ticketNumber}: cancela la autorización y libera los fondos reservados. Una vez cancelada, no se pueden hacer reautorizaciones sobre esa transacción.

Anulación y reembolso

Operación	Endpoint	Notas
Anulación	`DELETE /v1/charges/{ticketNumber}`	Cancela una transacción antes de la liquidación.
Reembolso	`DELETE /v1/refund/{ticketNumber}`	Devuelve los fondos al tarjetahabiente después de la liquidación.

En Chile, tanto la anulación como el reembolso admiten montos totales y parciales. Para una operación parcial, incluye el objeto amount en el cuerpo del request.

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

Incluye transactionMode en la solicitud de token para flujos recurrentes o para validar la tarjeta con monto cero. Disponible solo bajo el modelo Acquirer.

Valor	Descripción
`initialRecurrence`	Primera transacción de una serie recurrente. Envía los datos completos de la tarjeta (número, expiración, CVV) para registrarla.
`subsequentRecurrence`	Cargos recurrentes posteriores: puedes omitir el CVV una vez que se procesó un `initialRecurrence`.
`accountValidation`	Validación de tarjeta con monto cero. Pon `totalAmount` en `0` y después llama a `POST /card/v1/validation`.

Motor de suscripciones propio

Si tienes tu propio motor de suscripciones (solo comercios con PCI Compliance), procesa los cargos recurrentes así:

Registra la tarjeta

Solicita un token con transactionMode: "initialRecurrence".

Haz el cargo inicial

Cobra con ese token y guarda el transactionReference de la respuesta.

Tokeniza para los cargos siguientes

Solicita un token con transactionMode: "subsequentRecurrence".

Cobra las transacciones subsecuentes

Envía el transactionReference que guardaste en el campo initialRecurrenceReference del request del cargo.

Para Mastercard, incluye citMit como campo informativo cuando proceses suscripciones externas. Los valores son C101–C104 para transacciones iniciadas por el cliente y M101–M104, M205–M208 para las iniciadas por el comercio.

Cargo sin token (v2)

POST /card/v2/charges acepta los datos de la tarjeta directamente en el cuerpo del request, sin necesidad de una llamada previa de token. Es para integraciones server-to-server en las que ya tienes los datos de la tarjeta.

Servicio On-demand — requiere PCI DSS

Los endpoints sin token solo están disponibles para empresas con PCI DSS compliance, bajo el modelo Acquirer. Contacta a Kushki antes de habilitarlos.

Limitaciones:

Solo disponible para Visa y Mastercard.

No es compatible con las herramientas antifraude Siftscience ni TransUnion.

No es compatible con la herramienta de autenticación 3DS de Kushki: usa tu propio motor 3DS.

No es compatible con la autenticación OTP de Kushki.

3D Secure

Chile admite dos enfoques de 3DS:

3DS administrado por Kushki

Agrega estos campos a la solicitud de token:

Campo	Valores	Descripción
`authValidation`	`url`, `iframe`	Tipo de integración: `url` para redirección, `iframe` para embeber.
`callbackUrl`	string	Callback al que se envía la respuesta de la autenticación 3DS.

Si la transacción dispara una regla de 3DS, la respuesta del token también devuelve:

{
  "token": "sBkQ7F110000tI1HVq116862fd5Ah3mG",
  "url": "https://uat-auth.kushkipagos.com?token=...",
  "secureService": "3dsecure",
  "secureId": "1f5584db-0c5b-c729-a19c-6eb0283ca448"
}

Muéstrale la url al tarjetahabiente para que complete la autenticación.

Motor 3DS propio

Disponible bajo el modelo Acquirer. Incluye el objeto threeDomainSecure en el request de token, cargo o preautorización:

Marca	Campos obligatorios
Visa	`cavv`, `eci`, `specificationVersion`
Mastercard	`directoryServerTransactionID`, `eci`, `ucaf`, `specificationVersion`, `collectionIndicator`

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 además acceptRisk: true. Al hacerlo, el comercio asume la responsabilidad por chargebacks.

Network Tokens

BETA

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

Pon isNetworkToken: true e incluye el objeto networkToken:

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

Incluye también cryptogram en el objeto de la tarjeta cuando el network token traiga un cryptogram de la billetera o del servicio de tokenización del emisor. El valor debe tener entre 20 y 28 caracteres alfanuméricos.

⚠️ Beta: Contacta a tu ejecutivo de cuenta de Kushki antes de habilitar esta funcionalidad.

Verificación de cuenta

Para verificar que una tarjeta está activa sin cobrarle:

Solicita un token con transactionMode: "accountValidation" y totalAmount: 0.

Llama a POST /card/v1/validation con ese token.

Disponible solo bajo el modelo Acquirer.

Comprobante

GET /webhook/v1/transaction/receipt/{transactionReference} devuelve un PDF del comprobante de compra, codificado en Base64, con el valor de la boleta de venta y servicios.

Este endpoint solo está disponible en Chile.

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.

Información del BIN

GET /card/v1/bin/{bin} y GET /deferred/v2/bin/{bin} devuelven la metadata de la tarjeta (banco, marca, tipo de tarjeta, país emisor) para un BIN dado, y aceptan los primeros 8 o 10 dígitos.

Para los comercios chilenos, la respuesta ayuda a decidir si continúas con una solicitud de token de tarjeta (cuando cardType es CREDIT) y qué opciones de cuotas ofrecer. Úsala también para mostrar el logo de la marca de la tarjeta en el checkout.

Validar el OTP

POST /rules/v1/secureValidation valida el OTP que ingresa el cliente, usando el secureId que devuelve la solicitud de token. El cliente tiene 5 minutos y 3 intentos con el mismo secureId.

Sandbox

Para simular una validación de OTP aprobada en sandbox, usa 150 para CLP. Cualquier otro valor da una validación declinada.

Idempotencia

Incluye la cabecera Idempotency-Key para reintentar operaciones sin crear duplicados:

Regla	Detalle
Ventana de validez	24 horas: después de ese plazo, la misma llave genera una transacción nueva
Longitud máxima	56 caracteres
Unicidad	Debe ser única por tipo de transacción
Formato	UUIDv4 u otro generador con suficiente entropía

Soportada en Void a transaction y Refund a transaction (tanto para cargos únicos como para preautorizaciones y cargos de suscripción), y en las preautorizaciones de suscripción.

Kushki guarda el código de estado y el cuerpo de la respuesta solo si el request original resulta exitoso. Si el request falló con un 4XX o 5XX, no se guarda registro de idempotencia y puedes reintentar con la misma llave sin problema.

Autenticación

Usar 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

Cobra una tarjeta con un token. Admite cargos únicos, Cuotas Comercio, Cuotas Emisor, 3DS, webhooks y scoring antifraude.

Cargo sin token (v2)

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

Anular una transacción

Cancela 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 un BIN. Llámalo antes de enviar cualquier 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 antes de que expire.

Capturar

Captura un monto autorizado previamente.

Verificar la cuenta

Verifica una tarjeta con una solicitud de token de monto cero, sin cargo.

Validar el OTP

Valida una contraseña de un solo uso para los flujos 3DS con OTP.

Información del BIN v2

Consulta extendida de BIN, con elegibilidad de diferido y metadata de la tarjeta.

Información del BIN

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

Comprobante

Obtén el comprobante de compra como PDF codificado en Base64.

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

Pagos con tarjeta

Flujo de pago#

Moneda#

Tipos de documento#

Modelos de integración#

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)#

Motor de suscripciones propio#

Cargo sin token (v2)#

3D Secure#

3DS administrado por Kushki#

Motor 3DS propio#

Network Tokens#

Verificación de cuenta#

Comprobante#

Webhooks#

Información del BIN#

Validar el OTP#

Idempotencia#

Autenticación#

Usar la API#

Endpoints disponibles#

Flujo de pago

Moneda

Tipos de documento

Modelos de integración

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`)

Motor de suscripciones propio

Cargo sin token (v2)

3D Secure

3DS administrado por Kushki

Motor 3DS propio

Network Tokens

Verificación de cuenta

Comprobante

Webhooks

Información del BIN

Validar el OTP

Idempotencia

Autenticación

Usar la API

Endpoints disponibles