One Click y Pagos Programados
¡Ten en cuenta!
Proceso de pago
Etapa 1 — Registro de tarjeta de crédito o débito
Selecciona un medio de pago
En tu sitio web o app, el usuario selecciona el medio 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 aún 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 cargo pequeño lo realiza Kushki y se reversa automáticamente si resulta exitoso. Sirve para asegurar que la tarjeta del cliente pueda cobrarse después del registro.
Notificación de la suscripción
Kushki te informa el resultado del registro de la tarjeta para que puedas mostrarlo al usuario en pantalla.
Etapa 2 — Pago recurrente
Ejecución del pago
Kushki procesa automáticamente los cargos recurrentes a la tarjeta registrada. 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 corre 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 consecutivos a partir del Puedes personalizar la lógica de reintentos con el objeto Si el último intento de cobro es rechazado, 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 única vez. Kushki seguirá ejecutando los cobros 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 al día, para un total de 9 intentos.retryConfiguration:scheduled — Por intervalos
fixed — Días específicos
Reintenta cada N días. El siguiente ejemplo reintenta 3 veces al día, cada 2 días, durante todo el mes.
{
"retryConfiguration": {
"retryType": "scheduled",
"value": [2]
}
}Notificación del estado de la transacción
Se te notificará el estado de cada cargo automático mediante las Webhooks Notifications que expongas en tu sistema. También puedes revisar 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.Idempotencia
Cómo funciona
Idempotency-Key con un valor único al llamar a un endpoint soportado.4XX / 5XX), no se almacena ningún registro y el cliente puede reintentar con la misma llave.Cabecera
Reglas
| Regla | Detalle |
|---|---|
| Ventana de validez | 24 horas. Después de ese lapso, 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 soportados
Idempotency-Key es soportada en:Escenarios de error
5XX — Errores del servidor
4XX — Errores del cliente
No se almacena ningún registro de idempotencia. El cliente puede reintentar con la misma
Idempotency-Key. El reintento queda a criterio del integrador.Buenas prácticas
Idempotency-Key nueva para cada intento de transacción único.¿Tienes alguna sugerencia sobre esta documentación? Contáctanos.
Modified at 2026-09-11 14:47:13