Async Card Recurring Charges - Kushki Developer Portal

Los cargos recurrentes con tarjeta asíncronos son un servicio exclusivo de Chile que registra la tarjeta de un cliente para cargos recurrentes a través del portal Webpay de Transbank. El cliente se redirige a Webpay para autenticarse y autorizar el registro de la tarjeta — después de eso, puedes cobrar la tarjeta registrada de forma programada o a demanda usando los endpoints estándar de One-Click.

Solo Chile 🇨🇱

Este servicio está disponible únicamente en Chile. Requiere una integración Transbank/Webpay activa y habilitada en tu cuenta de Kushki.

Cómo funciona

Solicita un token de cargo recurrente asíncrono

Llama a POST /subscriptions/v1/card-async/tokens con la moneda, el email y la URL a la que regresa el cliente después del registro.

{
  "currency": "CLP",
  "email": "user@example.com",
  "callbackUrl": "https://yoursite.com/subscription/return"
}

Devuelve un token de un solo uso, vigente por 30 minutos.

⚠️ Nota PCI: Puedes incluir cardNumber directamente en esta petición de forma opcional, pero solo si tu backend cumple con PCI DSS.

Inicia el cargo recurrente asíncrono

Llama a POST /subscriptions/v1/card-async/init con el token, los datos del plan, el monto y la fecha de inicio de cobro. La respuesta devuelve un redirectUrl y un subscriptionId.

{
  "token": "AbCDef123456Z7Ghi8901234jkLMNopQ",
  "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"
  },
  "language": "es",
  "fullResponse": "v2"
}

Respuesta:

{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "redirectUrl": "https://webpay.transbank.cl/..."
}

💡 Guarda el subscriptionId — lo necesitas para todos los cargos, autorizaciones y operaciones de gestión futuras.

El cliente se autentica en Webpay

Redirige al cliente al redirectUrl. Ahí se autentica y autoriza el registro de la tarjeta en el portal de Transbank, y luego regresa a tu callbackUrl.

La suscripción está activa — cobra la tarjeta

Cuando el cliente regrese, la suscripción queda activa. Usa los endpoints estándar de One-Click para gestionarla y cobrarla:

POST /subscriptions/v1/card/{subscriptionId} — cargo a demanda

GET /subscriptions/v1/card/search/{subscriptionId} — consulta la información de la suscripción

PATCH /subscriptions/v1/card/{subscriptionId} — actualiza el plan

DELETE /subscriptions/v1/card/{subscriptionId} — cancela la suscripción

Los cargos recurrentes programados se procesan automáticamente según periodicity y startDate.

Reserva de fondos antes de la captura

Para flujos en los que quieres reservar fondos antes de confirmar un cargo sobre una suscripción existente.

Límite de captura de 7 días

Tienes un máximo de 7 días calendario para capturar después de una autorización. Pasado ese plazo, Transbank libera automáticamente los fondos reservados.

Autoriza

POST /subscriptions/v1/card/{subscriptionId}/authorize — Reserva fondos en la tarjeta registrada. No hace falta redirigir a Webpay — la tarjeta ya está guardada.

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "name": "Catalina",
  "lastName": "Fuentes",
  "email": "user@example.com",
  "fullResponse": "v2"
}

Devuelve un ticketNumber.

Captura

POST /subscriptions/v1/card/{subscriptionId}/capture — Captura el monto reservado dentro de 7 días.

{
  "ticketNumber": "319228478889680318",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "fullResponse": "v2"
}

Moneda

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

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`	Intervalo recurrente personalizado

Lógica de reintentos

Si un cargo programado se rechaza, Kushki reintenta automáticamente. Por defecto: 3 reintentos en 3 días consecutivos. Configúralo con retryConfiguration:

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

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

Diferencias con One-Click estándar

	Cargos recurrentes asíncronos	One-Click estándar
Registro	El cliente se redirige a Transbank/Webpay	Basado en token, sin redirección
Procesador	Transbank (Webpay)	Red de tarjetas directa
Autorización/Captura	Sin redirección — usa la tarjeta guardada	Sin redirección — usa la tarjeta guardada
Solo Chile	✅ Sí	✅ Sí (mediante la integración con Webpay)

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de cargo recurrente asíncrono

Solicita un token para iniciar el flujo de registro de la tarjeta. Vigente por 30 minutos.

Iniciar un cargo recurrente asíncrono

Inicializa la suscripción. Devuelve una URL de redirección a Webpay y un subscriptionId.

Autorizar pagos

Reserva fondos en una tarjeta ya registrada — sin redirección a Webpay.

Capturar un pago autorizado

Captura un monto previamente autorizado en la suscripción.

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

Cargos recurrentes con tarjeta asíncronos

Cómo funciona#

Reserva de fondos antes de la captura#

Moneda#

Opciones de periodicidad#

Lógica de reintentos#

Diferencias con One-Click estándar#

Autenticación#

Uso de la API#

Endpoints disponibles#

Cómo funciona

Reserva de fondos antes de la captura

Moneda

Opciones de periodicidad

Lógica de reintentos

Diferencias con One-Click estándar

Autenticación

Uso de la API

Endpoints disponibles