Cash-out

Cash-out te permite enviar dinero que los destinatarios retiran en efectivo en miles de puntos físicos de toda Colombia, sin necesidad de cuenta bancaria. El destinatario recibe un PIN que presenta en cualquier punto de pago afiliado para retirar los fondos.

¡Ten en cuenta!

Por nuestras políticas de riesgo, los métodos de pago disponibles y el tipo de integración pueden variar una vez que completes la afiliación. Te indicaremos cómo proceder si este proceso aplica a tu comercio.

Necesitas saldo en tu wallet

Las transacciones de Cash-out se debitan del saldo de tu wallet de dispersión de Kushki. Asegúrate de tener saldo suficiente antes de iniciar un Cash-out.

Flujo de pago

Una dispersión con Cash-out tiene 3 pasos: tokenización, inicialización (entrega del PIN) y confirmación.

Solicitar un token de Cash Out

Tu backend llama al endpoint de token con tu Public Merchant ID y envía los datos de identificación del destinatario y el monto de la dispersión.

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.

Campos obligatorios:

Campo	Descripción
`name`	Nombre del destinatario
`lastName`	Apellido del destinatario
`documentNumber`	Número de documento del destinatario
`totalAmount`	Monto a dispersar
`currency`	Siempre `COP` para Colombia

Campos opcionales:

Campo	Descripción
`documentType`	`CC`, `NIT`, `CE`, `TI` o `PP` (por defecto, `CC`)
`email`	Correo electrónico del destinatario
`phoneNumber`	Teléfono del destinatario (por ejemplo, `+573912345678`)
`description`	Descripción interna del pago

Tipos de documento aceptados en 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 token y el objeto amount. Kushki valida el token, debita el saldo de tu wallet y devuelve:

Un PIN (pin): el código de retiro en efectivo que compartes con el destinatario.

La URL del comprobante en PDF (pdfUrl): comprobante imprimible.

Un ticketNumber para hacer seguimiento y gestionar la dispersión.

Campos obligatorios:

Campo	Descripción
`token`	Token del paso anterior
`amount`	Objeto con `subtotalIva`, `subtotalIva0`, `iva` y `currency`

Campos opcionales:

Campo	Descripción
`expirationDate`	Fecha de expiración del PIN (`YYYY-MM-DD HH:mm:ss`, UTC). Si la omites, expira a los 7 días.
`metadata`	Pares clave-valor propios para tus registros internos
`webhooks`	Configuración de notificaciones en tiempo real

El destinatario retira el efectivo

Comparte el PIN con el destinatario. Va a cualquier punto de pago afiliado, presenta su documento y el PIN, y retira el efectivo.

Este paso ocurre por completo del lado del destinatario: no requiere ninguna acción en tu backend.

Consulta el estado de la transacción

Llama al endpoint Transaction Status con el ticketNumber para confirmar si el efectivo se retiró.

Estados posibles:

Estado	Significado
`initializedTransaction`	PIN generado: en espera del retiro en efectivo
`approvedTransaction`	Efectivo retirado por el destinatario
`expiredTransaction`	PIN expirado sin retiro

Objeto amount

El objeto amount es obligatorio en la solicitud de Init Transaction.

Sin impuestos (IVA 0)

Con IVA

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 50000,
    "iva": 0,
    "currency": "COP"
  }
}

Envía el monto completo en subtotalIva0. Todos los montos en COP.

Notificaciones por Webhook

Incluye el objeto webhooks en tu solicitud de Init Transaction para recibir notificaciones de dispersión en tiempo real:

{
  "webhooks": [
    {
      "events": ["approvedTransaction", "declinedTransaction"],
      "headers": [
        { "label": "Authorization", "value": "Bearer your-token" }
      ],
      "urls": [
        "https://merchant.example.com/webhooks/cash-out"
      ]
    }
  ]
}

Si ya tienes un Webhook configurado en la Console, agregar el objeto webhooks en la solicitud del API dispara ambos canales a la vez.

Gestión de dispersiones

Una vez inicializado un Cash-out, puedes modificarlo o cancelarlo mientras siga en estado initializedTransaction:

Acción	Cuándo usarla
Update	Ajusta el monto de la dispersión antes de que el destinatario retire el efectivo
Delete	Cancela la dispersión y devuelve los fondos a tu wallet

Una vez que el destinatario retira el efectivo (approvedTransaction), la transacción ya no se puede actualizar ni eliminar.

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

Nunca expongas tu 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 Out

Tokeniza los datos del destinatario y el monto de la dispersión. Requiere Public Merchant ID. El token vale 30 minutos y es de un solo uso.

Iniciar transacción

Inicializa la dispersión en efectivo y devuelve el PIN y el comprobante en PDF. Debita el monto del saldo de tu wallet.

Estado de la transacción

Consulta el estado actual de una transacción de Cash-out con su ticketNumber.

Actualizar una transacción

Actualiza el monto de la dispersión de una transacción de Cash-out ya inicializada.

Eliminar una transacción

Cancela una transacción de Cash-out y devuelve los fondos a tu wallet.

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

Flujo de pago#

Objeto amount#

Notificaciones por Webhook#

Gestión de dispersiones#

Autenticación#

Uso del API#

Endpoints disponibles#

Flujo de pago

Objeto amount

Notificaciones por Webhook

Gestión de dispersiones

Autenticación

Uso del API

Endpoints disponibles