Card Async

Card Async es un método de pago exclusivo de Chile que procesa transacciones con tarjeta a través del portal Webpay de Transbank. A diferencia del flujo de tarjeta estándar, el cliente se redirige al portal de Transbank para autenticarse y completar el pago — tu servidor recibe el resultado de forma asíncrona.

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 Card Async

Llama a POST /card-async/v1/tokens con el monto total, la URL de retorno y la moneda. Devuelve un token de un solo uso.

{
  "totalAmount": 10000,
  "returnUrl": "https://yoursite.com/payment/return",
  "currency": "CLP",
  "email": "user@example.com",
  "description": "Compra en Mi Comercio Chile"
}

⚠️ Vigencia del token: Los tokens vencen en 30 minutos y solo se pueden usar para una única transacción. Solicita un token nuevo cuando venza.

Inicia la transacción

Llama a POST /card-async/v1/init con el token y el monto. La respuesta devuelve un redirectUrl — envía ahí a tu cliente para que complete el pago en el portal Webpay de Transbank.

{
  "token": "AbCDef123456Z7Ghi8901234jkLMNopQ",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 10000,
    "iva": 0,
    "ice": 0,
    "currency": "CLP"
  },
  "webhooks": ["https://yoursite.com/kushki/notify"],
  "fullResponse": "v2"
}

Respuesta:

{
  "redirectUrl": "https://webpay.transbank.cl/...",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521"
}

El cliente completa el pago en Webpay

El cliente se autentica y confirma el pago en el portal de Transbank. Al terminar, Transbank lo redirige de vuelta a tu returnUrl.

Consulta el estado de la transacción

Llama a GET /card-async/v1/status/{token} para obtener el resultado final. Usa el token del paso 1 como parámetro de ruta.

Una respuesta exitosa incluye:

{
  "status": "approvedTransaction",
  "ticketNumber": "319228478889680318",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "approvedTransactionAmount": 10000,
  "lastFourDigits": "1234",
  "cardType": "CREDIT"
}

Flujo de preautorización

Usa la preautorización para reservar fondos sin capturarlos de inmediato — por ejemplo, en flujos de hotelería, arriendo o marketplace.

Límite de captura de 7 días

Tienes un máximo de 7 días calendario para capturar después de una preautorización. Pasado ese plazo, Transbank libera automáticamente los fondos reservados. Este límite no se puede extender.

Solicita un token

Igual que en un cargo normal — llama a POST /card-async/v1/tokens con el monto a reservar.

Preautoriza

POST /card-async/v1/preAuthorization — Devuelve un redirectUrl para redirigir al cliente a Transbank.

{
  "token": "AbCDef123456Z7Ghi8901234jkLMNopQ",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 30000,
    "iva": 0
  }
}

El cliente se autentica en Webpay

El cliente se redirige al portal de Transbank y confirma la retención.

Consulta el estado y el ticketNumber

GET /card-async/v1/status/{token} — Cuando el cliente regrese, consulta este endpoint para confirmar la autorización y obtener el ticketNumber que necesitas para la captura.

Captura

POST /card-async/v1/capture — Cobra los fondos reservados usando el ticketNumber de la respuesta de estado. Debes hacerlo dentro de 7 días calendario.

{
  "ticketNumber": "319228478889680318",
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 30000,
    "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

CLP no admite decimales

Envía siempre los montos como enteros (por ejemplo, 10000). Si envías 10000.50, la respuesta es 400 Bad Request.

Valores del estado de la transacción

Estado	Descripción
`requestedToken`	Token creado — la transacción aún no se ha inicializado
`initializedTransaction`	Transacción inicializada — esperando la acción del cliente en Webpay
`approvedTransaction`	Pago aprobado
`declinedTransaction`	Pago rechazado por el emisor o el procesador

Autenticación

Uso de la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de Card Async

Solicita un token con el monto del pago y la URL de retorno. Vigente por 30 minutos y de un solo uso.

Iniciar transacción

Inicializa la transacción. Devuelve una URL de redirección a Webpay para el cliente.

Preautorización

Reserva fondos sin capturarlos de inmediato. Devuelve una URL de redirección a Webpay. Ventana de captura de 7 días.

Capturar

Captura un monto previamente autorizado usando el ticketNumber de la respuesta de estado.

Consultar estado

Consulta el resultado final de la transacción usando el token del paso de solicitud del token.

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

Cómo funciona#

Flujo de preautorización#

Moneda#

Valores del estado de la transacción#

Autenticación#

Uso de la API#

Endpoints disponibles#

Cómo funciona

Flujo de preautorización

Moneda

Valores del estado de la transacción

Autenticación

Uso de la API

Endpoints disponibles