Cash in

Permite que tus clientes sin cuenta bancaria compren tus productos o servicios desde tu sitio web.

Si tus usuarios no tienen cuenta bancaria, o prefieren evitar cargos adicionales como intereses o comisiones, el pago en efectivo es la opción ideal. Con este método, tus clientes solo necesitan una referencia de pago y efectivo para completar una compra en cualquier punto de recaudación autorizado.

¡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.

Proceso de pago

El proceso de pago en efectivo tiene tres etapas principales: generar una referencia de pago, realizar el pago en un punto físico y confirmar la recepción.

Flujo de pago de Cash In

Solicita un token de Cash In

El cliente selecciona efectivo como método de pago en el checkout. Tu frontend llama al endpoint de token con tu Public Merchant ID y los datos de identidad del cliente.

Campos obligatorios:

Campo	Tipo	Descripción
`name`	string	Nombre del cliente
`lastName`	string	Apellido del cliente
`identification`	string	Número de documento del cliente (solo dígitos)
`documentType`	string	`CI`, `RUC` o `PP` (ver abajo)
`totalAmount`	number	Monto total de la transacción
`currency`	string	Siempre `USD` para Ecuador
`email`	string	Correo del cliente (opcional)
`description`	string	Descripción del pago (opcional)

Tipos de documento aceptados en Ecuador:

Valor	Documento
`CI`	Cédula de Identidad 🇪🇨
`RUC`	Registro Único de Contribuyentes 🇪🇨
`PP`	Pasaporte 🇪🇨

Init Transaction

Tu backend llama al endpoint Init Transaction con el token del paso anterior y tu Private Merchant ID. Kushki genera un PIN y un comprobante de pago (PDF) que el cliente presentará en el punto de recaudación.

Campos de la solicitud:

Campo	Obligatorio	Por defecto	Descripción
`token`	✅	—	Token del paso anterior
`amount`	✅	—	Objeto amount (ver la estructura más abajo)
`expirationDate`	❌	7 días	Fecha hasta la que el PIN es válido. Formato: `YYYY-MM-DD HH:mm:ss` (UTC). Debe ser al menos 1 día después de crear el token.
`metadata`	❌	—	Pares clave-valor personalizados para tus registros
`webhooks`	❌	—	URL de notificación en tiempo real
`fullResponse`	❌	—	Envía `"v2"` para recibir la respuesta extendida

Campos de la respuesta:

Campo	Descripción
`pin`	Código de referencia de pago que el cliente presenta en el punto de recaudación
`pdfUrl`	URL del comprobante de pago imprimible
`ticketNumber`	Identificador de la transacción en Kushki — úsalo para consultar el estado
`transactionReference`	Referencia única basada en UUID para esta transacción
`details.expiration`	Timestamp Unix (ms) de la fecha de expiración del PIN
`details.transactionStatus`	Siempre `initializedTransaction` en este punto
`details.agreementDetails`	Lista de puntos de recaudación autorizados y sus números de convenio

Comparte ambos pin y pdfUrl con el cliente — puede usar cualquiera de los dos para pagar en un punto de recaudación.

El cliente paga en un punto de recaudación

El cliente va a cualquier punto de recaudación físico autorizado con su PIN o el comprobante impreso. El cajero valida la referencia y acepta el pago en efectivo por el monto de la transacción.

En este paso no se requiere ninguna acción de tu backend.

Consulta el estado de la transacción

Después de la ventana de pago, consulta el endpoint Transaction Status usando el ticketNumber como parámetro de ruta para confirmar si el pago se completó.

Estados de transacción en Ecuador:

Estado	Significado
`initializedTransaction`	PIN generado — el pago aún no se realiza
`approvedTransaction`	Efectivo recibido — fondos acreditados en tu cuenta
`expiredTransaction`	El PIN expiró antes de que el cliente pagara

Objeto amount

El objeto amount es obligatorio en el paso Init Transaction. La estructura depende de si la transacción tiene impuestos:

Sin impuestos (IVA 0)

Con impuestos IVA

Con impuesto ICE

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 100.00,
    "iva": 0,
    "ice": 0,
    "currency": "USD"
  }
}

Envía el monto completo en subtotalIva0. Deja los demás campos en 0.

Gestiona una transacción

Una vez inicializada la transacción, puedes actualizarla o cancelarla antes de que el cliente complete el pago.

Actualiza el monto

Usa el endpoint Update (PATCH /cash/v1/charges/{ticketNumber}) para modificar el totalAmount de una transacción de cash in existente antes de que el cliente pague.

Solo se puede actualizar el campo totalAmount.

Elimina la transacción

Usa el endpoint Delete (DELETE /cash/v1/charges/{ticketNumber}) para cancelar una transacción e invalidar el PIN antes de que el cliente realice el pago.

Notificaciones por webhook

Incluye el objeto webhooks en tu solicitud de Init Transaction para recibir notificaciones de pago en tiempo real. Esto es independiente de los webhooks configurados en la Kushki Console — ambos canales se disparan al mismo tiempo.

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

Pruebas en Sandbox

Escenarios de prueba

Usa estos valores de identification para simular distintos resultados en el ambiente Sandbox:

`identification`	Resultado simulado
Cualquier número válido	`approvedTransaction`
`9999999999`	`initializedTransaction` (pago pendiente)
`1000000000`	`declinedTransaction`

Después de inicializar la transacción, usa el endpoint Transaction Status para verificar el resultado simulado.

Autenticación

Paso	Cabecera	Tipo de llave
Solicitar un token	`Public-Merchant-Id`	Public Key (Kushki Console → Credentials)
Init Transaction	`Private-Merchant-Id`	Private Key (Kushki Console → Credentials)
Transaction Status	`Private-Merchant-Id`	Private Key
Actualizar la transacción	`Private-Merchant-Id`	Private Key
Eliminar la transacción	`Private-Merchant-Id`	Private Key

Nunca expongas tu Private-Merchant-Id en código del lado del cliente. Solo la solicitud de token usa la Public Key y se puede llamar desde el frontend.

Códigos de error

Código	Mensaje	Causa
`C001`	Cuerpo de la petición inválido	Cuerpo mal formado o faltan campos obligatorios
`C003`	Token inválido	El token enviado es inválido o expiró
`C005`	Id de transacción no válido	`ticketNumber` inválido en la ruta
`C006`	Monto de la transacción inválido	El monto de la transacción no es válido
`C017`	La fecha de expiración no es válida	`expirationDate` está en el pasado o es menos de 1 día después de la creación
`C018`	La transacción no existe o ha sido eliminada	La transacción ya fue eliminada o no existe
`C023`	No es posible actualizar la transacción	La transacción no se puede actualizar (ya fue pagada o expiró)
`C040`	El ID de comercio no corresponde a la credencial enviada	Las llaves Public y Private pertenecen a comercios distintos
`C066`	Las credenciales no son correctas o no coinciden	Las credenciales son incorrectas o no coinciden
`K004`	ID de comercio o credencial no válido	ID de comercio o credencial inválido

Usa la API

🟢 Producción

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Endpoints disponibles

Solicitar un token de Cash In

Tokeniza los datos del cliente y del monto. Requiere Public Merchant ID.

Iniciar transacción

Genera el PIN de pago y la URL del comprobante. Requiere Private Merchant ID.

Estado de la transacción

Devuelve el estado actual de una transacción de cash in por ticketNumber.

Actualizar una transacción de Cash In

Actualiza el totalAmount de una transacción inicializada antes del pago.

Eliminar una transacción de Cash In

Cancela e invalida el PIN de una transacción inicializada.

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

Proceso de pago#

Objeto amount#

Gestiona una transacción#

Notificaciones por webhook#

Pruebas en Sandbox#

Autenticación#

Códigos de error#

Usa la API#

Endpoints disponibles#

Proceso de pago

Objeto amount

Gestiona una transacción

Notificaciones por webhook

Pruebas en Sandbox

Autenticación

Códigos de error

Usa la API

Endpoints disponibles