Cash in
¡Ten en cuenta!
Flujo de pago
Solicitar un token de Cash In
Tu backend llama al endpoint de token con tu Public Merchant ID y envía los datos de identificación del cliente y el monto del pago.Campos obligatorios:
Tipos de documento aceptados en Colombia:
Reglas del token: los tokens expiran en 30 minutos y son de un solo uso. Solicita uno nuevo si la transacción falla o si el token expira.
| Campo | Descripción |
|---|---|
name | Nombre del cliente |
lastName | Apellido del cliente |
identification | Número de documento del cliente |
documentType | Ver los tipos de documento más abajo |
totalAmount | Monto total a cobrar |
currency | Siempre COP para Colombia |
| Valor | Documento |
|---|---|
CC | Cédula de Ciudadanía 🇨🇴 |
NIT | Número de Identificación Tributaria 🇨🇴 |
CE | Cédula de Extranjería 🇨🇴 |
TI | Tarjeta de Identidad 🇨🇴 |
PP | Pasaporte 🇨🇴 |
Init Transaction
Con tu Private Merchant ID, llama al endpoint Init Transaction con el Un PIN ( La URL del comprobante en PDF ( Un objeto Un Campos opcionales:
Puntos de pago disponibles en Colombia: El objeto
token. Kushki valida el token y devuelve:pin): el número de referencia que el cliente presenta en el punto de pago.pdfUrl): comprobante imprimible para entregar al cliente.agreementDetails con todos los puntos de pago disponibles y sus números de convenio.ticketNumber para hacer seguimiento a la transacción.| Campo | Descripción |
|---|---|
expirationDate | Fecha de expiración del PIN (YYYY-MM-DD HH:mm:ss, UTC). Debe ser al menos 1 día después de la creación. Por defecto, 7 días. |
amount | Desglose con subtotalIva, subtotalIva0, iva y, opcionalmente, extraTaxes |
webhooks | Configuración de notificaciones en tiempo real |
fullResponse | Envíalo en "v2" para recibir el objeto details completo en la respuesta |
metadata | Pares clave-valor propios para tu uso interno |
agreementDetails de la respuesta lista las redes de recaudo activas. Las redes típicas en Colombia son:| Red | Procesador |
|---|---|
| Baloto | BancoBogota |
| Carulla | BancoBogota |
| Efecty | Payvalida |
| Bancolombia | Payvalida |
El cliente paga en un punto de pago
Comparte el PIN y el comprobante con tu cliente. Va a cualquier punto de pago afiliado y presenta el PIN para completar el pago en efectivo.Este paso ocurre por completo del lado del cliente: no requiere ninguna acción en tu backend.
Consulta el estado de la transacción
Llama al endpoint Transaction Status con el Estados posibles:
ticketNumber para confirmar si el pago se completó.| Estado | Significado |
|---|---|
initializedTransaction | PIN generado: en espera del pago en el punto de recaudo |
approvedTransaction | Pago en efectivo recibido y confirmado |
expiredTransaction | PIN expirado sin pago |
Objeto amount
amount es opcional en la solicitud de Init Transaction. Si lo omites, se usa el monto de la solicitud del token.Con IVA
Sin impuestos (IVA 0)
Con impuestos adicionales
{
"amount": {
"subtotalIva": 42017,
"subtotalIva0": 0,
"iva": 7983
}
}subtotalIva la base gravable y en iva el valor del impuesto. Todos los montos en COP.Notificaciones por Webhook
webhooks en tu solicitud de Init Transaction para recibir notificaciones de pago en tiempo real:{
"webhooks": [
{
"events": ["approvedTransaction", "declinedTransaction"],
"headers": [
{ "label": "Authorization", "value": "Bearer your-token" }
],
"urls": [
"https://merchant.example.com/webhooks/cash-in"
]
}
]
}webhooks en la solicitud del API dispara ambos canales a la vez.Pruebas en Sandbox
| Escenario | Valor de identification |
|---|---|
| ✅ Transacción exitosa | Cualquier número válido |
| ⏳ Inicializada (pendiente) | 9999999999 |
| ❌ Transacción declinada | 1000000000 |
Autenticación
| Paso | Cabecera | Tipo de llave |
|---|---|---|
| Request a Token | Public-Merchant-Id | Public Key (desde Kushki Console → Credentials) |
| Init Transaction | Private-Merchant-Id | Private Key |
| Get Status | Private-Merchant-Id | Private Key |
| Update Transaction | Private-Merchant-Id | Private Key |
| Delete Transaction | Private-Merchant-Id | Private Key |
Private-Merchant-Id en código de cliente o frontend. Las solicitudes de token con la Public Key se pueden hacer desde el frontend; todas las demás llamadas deben salir de tu backend.Uso del API
🟢 Producción
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Endpoints disponibles
Solicitar un token de Cash In
Tokeniza los datos del cliente y el monto del pago. Requiere Public Merchant ID. El token vale 30 minutos y es de un solo uso.Iniciar transacción
Inicializa el pago en efectivo y devuelve el PIN, la URL del comprobante en PDF y los puntos de pago disponibles.Estado de la transacción
Consulta el estado actual de una transacción de Cash in con su ticketNumber.¿Tienes una sugerencia sobre esta documentación? Contáctanos.
Modified at 2026-09-11 14:48:35