One-Click & Scheduled Payments - Kushki Developer Portal

Los Pagos One-Click y Programados te permiten registrar la tarjeta de un cliente una sola vez y cobrarla varias veces —a demanda o automáticamente según un calendario— sin volver a pedir los datos de la tarjeta. Esto también se conoce como tokenización y ejecución de cargos recurrentes.

Admite cargos one-click (a demanda) y cargos recurrentes programados, con ciclos de facturación y lógica de reintentos configurables.

Proceso de pago

Un pago por suscripción funciona en 2 etapas principales: el registro de la tarjeta y la ejecución de los cargos recurrentes.

Etapa 1 — Registro de la tarjeta

El usuario elige el método de pago

En tu sitio web o app, el usuario elige el método de pago. Déjale claro que su tarjeta queda registrada para cargos recurrentes.

Solicita un token de cargo recurrente

Llama a POST /subscriptions/v1/card/tokens con los datos de la tarjeta y la moneda. Devuelve un token de un solo uso que se usa para crear la suscripción.

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

Crea la suscripción

Llama a POST /subscriptions/v1/card con el token, los datos del plan y la información de contacto. Kushki ejecuta un cargo pequeño de validación y lo reversa automáticamente: así confirma que la tarjeta se puede cobrar.

{
  "token": "gV3ox6100000sAxClU033646vnnJsT83",
  "planName": "Plan Mensual",
  "periodicity": "monthly",
  "startDate": "2026-06-01",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "contactDetails": {
    "documentType": "RUT",
    "documentNumber": "12345678-9",
    "firstName": "Catalina",
    "lastName": "Fuentes",
    "email": "user@example.com",
    "phoneNumber": "+56912345678"
  }
}

Una respuesta exitosa devuelve un subscriptionId: guárdalo para gestionar los cargos futuros.

Etapa 2 — Cargos recurrentes

Facturación automática

Kushki procesa los cargos recurrentes a la tarjeta registrada de forma automática, según el monto y el periodo definidos en la suscripción.

La facturación corre todos los días desde las 6 AM GMT-5. Configura startDate antes de esa hora si quieres el primer cargo el mismo día.

Lógica de reintentos

Si un cargo se rechaza, Kushki reintenta automáticamente. Por defecto, 3 reintentos durante 3 días consecutivos desde el startDate original.

Personaliza la lógica de reintentos con retryConfiguration:

`retryType`	Comportamiento
`schedule`	Reintenta cada N días durante todo el periodo
`fixed`	Reintenta solo en días específicos del mes

{
  "retryConfiguration": {
    "retryType": "fixed",
    "value": [5, 15, 25]
  }
}

Notificaciones de transacción

Recibes notificaciones por webhook por cada intento de cargo, aprobado o declinado. También están disponibles en la Kushki Console.

Cargo a demanda (one-click)

Para cobrar una tarjeta registrada de inmediato, sin esperar el ciclo de facturación programado:

POST /subscriptions/v1/card/{subscriptionId}

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  }
}

Moneda

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

CLP no tiene decimales

Envía siempre los montos como enteros. Enviar 10000.50 devuelve 400 Bad Request.

Tipos de documento

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

Diferido en suscripciones

Chile admite cargos diferidos en los pagos one-click. Llama siempre primero a Request Deferred Options para verificar los planes disponibles para el BIN de la tarjeta.

Cuotas Comercio — Modelo de adquirencia (Beta)

Cuotas Emisor — Modelo agregador

⚠️ Beta: Cuotas Comercio requiere creditType: "03" y está en fase Beta para Chile. Contacta al equipo de Kushki para activarlo.

Envía el objeto deferred dentro de la petición de cargo:

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 30000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "deferred": {
    "creditType": "03",
    "months": 6
  }
}

Disponible de 2 a 12 meses.

Flujo de preautorización de la suscripción

Usa la preautorización para reservar fondos en una tarjeta registrada antes de confirmar el cargo. Es útil para flujos de hoteles y arriendos.

Preautoriza

POST /subscriptions/v1/card/{subscriptionId}/authorize: reserva fondos en la tarjeta registrada. Devuelve un ticketNumber.

Las retenciones de autorización expiran después de 28 días (crédito) o 7 días (débito).

Captura

POST /subscriptions/v1/card/{subscriptionId}/capture: captura el monto reservado. Envía el ticketNumber de la preautorización.

Gestiona tus suscripciones

Operación	Endpoint	Descripción
Consultar información	`GET /subscriptions/v1/card/search/{subscriptionId}`	Obtiene el estado actual y la configuración
Actualizar tarjeta	`PUT /subscriptions/v1/card/{subscriptionId}/card`	Reemplaza la tarjeta sin cancelar la suscripción
Actualizar plan	`PATCH /subscriptions/v1/card/{subscriptionId}`	Modifica el monto, la frecuencia o las fechas
Agregar cargo temporal	`PUT /subscriptions/v1/card/{subscriptionId}`	Aplica un cargo o descuento extra por una vez al siguiente ciclo
Cancelar	`DELETE /subscriptions/v1/card/{subscriptionId}`	Cancela y desactiva la suscripción

Opciones de periodicidad

Valor	Descripción
`daily`	Cada 1 día
`weekly`	Cada 7 días
`biweekly`	Cada 15 días
`monthly`	Cada 30 días
`threefortnights`	Cada seis semanas (42 días)
`bimonthly`	Cada 60 días
`quarterly`	Cada 90 días
`fourmonths`	Cada 120 días
`halfYearly`	Cada 180 días
`yearly`	Cada 360 días
`custom`	Para pagos one-click (a demanda)

Idempotencia

Incluye la cabecera Idempotency-Key para reintentar operaciones de forma segura:

Regla	Detalle
Ventana de validez	24 horas
Largo máximo	56 caracteres
Formato	UUIDv4 recomendado

Disponible en: preautorizaciones de suscripción, anulaciones y reembolsos.

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de cargo recurrente

Tokeniza los datos de la tarjeta para registrarla para cargos recurrentes.

Crear un cargo recurrente

Crea una nueva suscripción con el token de la tarjeta registrada. Acepta Cuotas Comercio para flujos de Oneclick Mall.

Hacer un pago One-Click

Ejecuta un cargo a demanda sobre una tarjeta registrada. Admite diferido.

Consultar un cargo recurrente

Obtén los detalles y el estado actual de una suscripción.

Actualizar la tarjeta del cargo recurrente

Reemplaza la tarjeta asociada a una suscripción activa.

Actualizar un cargo recurrente

Modifica el monto, la frecuencia o las fechas de una suscripción existente.

Agregar un cargo o descuento temporal

Aplica un cargo o descuento extra por una vez al siguiente ciclo de facturación.

Cancelar un cargo recurrente

Cancela y desactiva una suscripción activa.

Preautorización de suscripción

Reserva fondos en una tarjeta registrada sin capturar de inmediato.

Captura de suscripción

Captura un monto previamente autorizado en una tarjeta registrada.

¿Tienes alguna sugerencia sobre esta documentación? Contáctanos.

Pagos One-Click y Programados

Proceso de pago#

Etapa 1 — Registro de la tarjeta#

Etapa 2 — Cargos recurrentes#

Cargo a demanda (one-click)#

Moneda#

Tipos de documento#

Diferido en suscripciones#

Flujo de preautorización de la suscripción#

Gestiona tus suscripciones#

Opciones de periodicidad#

Idempotencia#

Autenticación#

Uso de la API#

Endpoints disponibles#

Proceso de pago

Etapa 1 — Registro de la tarjeta

Etapa 2 — Cargos recurrentes

Cargo a demanda (one-click)

Moneda

Tipos de documento

Diferido en suscripciones

Flujo de preautorización de la suscripción

Gestiona tus suscripciones

Opciones de periodicidad

Idempotencia

Autenticación

Uso de la API

Endpoints disponibles