Pagos One-Click y programados
¡Ten en cuenta!
Proceso de pago
Flujo de pago recurrente
Etapa 1 — Registro de la tarjeta de crédito o débito
Selecciona un método de pago
En tu sitio web o app, el usuario selecciona el método de pago. Asegúrate de que quede claro para el pagador que su tarjeta de crédito o débito quedará registrada para cargos recurrentes.
Ingresa los datos de la tarjeta
El usuario ingresa los datos de su tarjeta. Tu sitio web o app debe verificar que la información de la tarjeta sea correcta — por ejemplo, que la fecha de expiración no esté vencida o que el número de tarjeta pase el algoritmo de Luhn.
Nota: En esta etapa todavía no se puede confirmar que la tarjeta sea válida.
Envía los datos a Kushki
Kushki recibe los datos y verifica si hay fondos suficientes ejecutando un cargo de validación de la suscripción. Este cobro pequeño lo hace Kushki y se reversa automáticamente si es exitoso. Sirve para asegurar que la tarjeta del cliente se pueda cobrar después del registro.
Notificación de la suscripción
Kushki te informa el resultado del registro de la tarjeta para que puedas mostrárselo al usuario en pantalla.
Etapa 2 — Pago recurrente
Ejecución del pago
Kushki procesa los cargos recurrentes a la tarjeta registrada de forma automática. Los pagos se ejecutan y se repiten según el monto y el periodo definidos en la suscripción.La lógica de facturación se ejecuta todos los días a partir de las 6 AM GMT-5. Asegúrate de crear la suscripción antes de esa hora si quieres que el primer pago ocurra el mismo día del registro. Al crear una suscripción, debes definir el campo Lógica de reintentos Si un pago es rechazado, Kushki reintenta el cargo automáticamente. Por defecto, hay 3 reintentos durante 3 días seguidos a partir del Puedes personalizar la lógica de reintentos con el objeto Si el último intento de cargo es declinado, Kushki puede notificarte vía Webhook. En ese caso, te recomendamos contactar al tarjetahabiente y ofrecerle alternativas — por ejemplo, actualizar la tarjeta registrada o solicitar un One-click payment por una sola vez. Kushki seguirá ejecutando los cargos automáticos en los periodos siguientes.
startDate.startDate original. Por ejemplo, para una suscripción mensual con startDate: 10-01-2021 y un rechazo el 10-02-2021, el pago se reintentará hasta el 13-02-2021 — 3 veces por día, para un total de 9 intentos.retryConfiguration:scheduled — Por intervalo
fixed — Días específicos
Reintenta cada N días. El ejemplo siguiente reintenta 3 veces por día, cada 2 días, durante todo el mes.
{
"retryConfiguration": {
"retryType": "scheduled",
"value": [2]
}
}Notificación del estado de la transacción
Recibirás una notificación del estado de cada cargo automático mediante las Webhook notifications que expone tu sistema. También puedes verificar las transacciones, sus detalles y su estado directamente en la Kushki Console.
Uso de la API
Public-Merchant-Id y un Private-Merchant-Id.🟢 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.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 adicional por una sola vez al siguiente ciclo de facturación.Pagos diferidos en suscripciones
Modelo de adquirencia
Modelo de agregador
Envía el objeto Valores comunes de
deferred con creditType, graceMonths y months dentro de la solicitud de cargo:{
"deferred": {
"creditType": "01",
"graceMonths": "00",
"months": 3
}
}creditType para Colombia:| Código | Descripción |
|---|---|
01 | Cuotas — diferido estándar |
02 | Cuotas con período de gracia — diferido con meses de gracia |
Flujo de preautorización de suscripción
Producto en versión beta 🔐👨💻
Preautoriza
Llama a Subscription Pre-Authorization (La autorización expira 28 días después para tarjetas de crédito y 7 días después para tarjetas de débito, contados desde el momento de la solicitud.
POST /subscriptions/v1/card/{subscriptionId}/preAuthorization). El banco reserva el monto en la tarjeta del cliente.Captura
Llama a Subscription Capture (
POST /subscriptions/v1/card/{subscriptionId}/capture) con el ticketNumber de la respuesta de la preautorización para cobrar los fondos reservados.Idempotencia
Cómo funciona
Idempotency-Key con un valor único al llamar a un endpoint compatible.4XX / 5XX), no se guarda ningún registro y el cliente puede reintentar con la misma llave.Cabecera
Reglas
| Regla | Detalle |
|---|---|
| Ventana de vigencia | 24 horas. Después de ese tiempo, la misma llave genera una nueva transacción. |
| Longitud máxima | 56 caracteres |
| Unicidad | Debe ser única por tipo de transacción |
| Formato recomendado | UUIDv4 o una cadena aleatoria equivalente de alta entropía |
Endpoints compatibles
Idempotency-Key es compatible con:Escenarios de error
5XX — Errores del servidor
4XX — Errores del cliente
No se guarda ningún registro de idempotencia. El cliente puede reintentar con la misma
Idempotency-Key. El reintento queda a discreción del integrador.Buenas prácticas
Idempotency-Key nueva para cada intento de transacción único.¿Tienes una sugerencia sobre esta documentación? Contáctanos.
Modified at 2026-09-11 14:48:17