One-Click and 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.

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": "Juan García",
    "number": "5451951574925480",
    "expiryMonth": "05",
    "expiryYear": "28",
    "cvv": "123"
  },
  "currency": "MXN"
}

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": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "contactDetails": {
    "documentType": "CURP",
    "documentNumber": "GACJ800101HDFRRN09",
    "firstName": "Juan",
    "lastName": "García",
    "email": "user@example.com",
    "phoneNumber": "+525512345678"
  }
}

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": 500,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  }
}

Moneda

Moneda	Código	Notas
Peso mexicano	`MXN`	Dos decimales: los montos usan centavos (por ejemplo, `500.00`)

Tipos de documento

Valor	Descripción
`CURP`	Clave Única de Registro de Población 🇲🇽
`RFC`	Registro Federal de Contribuyentes 🇲🇽
`PP`	Pasaporte 🇲🇽
`CC`	Identity Document 🇲🇽

Meses sin intereses (MSI) en suscripciones

México admite Meses Sin Intereses (MSI) en los cargos one-click. Envía el objeto deferred con creditType: "03", graceMonths: "00" y el número de months en la petición de cargo.

Llama siempre primero a Request Deferred Options para verificar los planes disponibles para el BIN de la tarjeta.

Montos mínimos requeridos para MSI

Meses	Monto mínimo
3	$300 MXN
6	$600 MXN
9	$900 MXN
12	$1,200 MXN
18	$1,800 MXN

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 900,
    "iva": 0,
    "ice": 0,
    "currency": "MXN"
  },
  "deferred": {
    "creditType": "03",
    "graceMonths": "00",
    "months": 9
  }
}

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`	Se cobra cada día
`weekly`	Se cobra cada semana
`biweekly`	Se cobra cada dos semanas
`monthly`	Se cobra cada mes
`bimonthly`	Se cobra cada dos meses
`quarterly`	Se cobra cada tres meses
`biannual`	Se cobra cada seis meses
`annual`	Se cobra cada año
`custom`	Intervalo personalizado: especifica `periodDays`

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/

OTP en sandbox

Cuando una tarjeta requiere validación por OTP en el ambiente de sandbox, usa 555 para las transacciones en MXN.

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.

Hacer un pago One-Click

Ejecuta un cargo a demanda sobre una tarjeta registrada. Admite meses sin intereses (MSI).

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#

Meses sin intereses (MSI) 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

Meses sin intereses (MSI) 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