Transfer In
| Procesador | Experiencia del cliente |
|---|---|
| Transferencia bancaria tradicional | Flujo seguro de redirección al banco. El cliente autoriza la transferencia en el portal web de su banco. |
| DeUna! | Flujo de billetera. El cliente paga desde la app de DeUna! con un QR dinámico, un deep link o un código de referencia. |
¡Ten en cuenta!
Activación del procesador
/transfer/v1/init empieza a devolver los campos de DeUna!.Flujo de pago
Solicita un token de Transfer In
Tu backend llama al endpoint de token usando tu Public Merchant ID. Debes incluir el monto de la transacción, los datos del documento del cliente y un Campos requeridos para Ecuador:
Tipos de documento aceptados en Ecuador:
callbackUrl: la URL donde aterriza el cliente después de completar el pago.Reglas del token: los tokens expiran en 30 minutos y son de un solo uso. Si la transacción falla o el token expira, debes solicitar uno nuevo.
| Campo | Descripción |
|---|---|
amount | Objeto con subtotalIva, subtotalIva0 e iva |
callbackUrl | URL de redirección después de la confirmación del pago |
userType | 0 = Persona Natural · 1 = Persona Jurídica |
documentType | CI, RUC o PAS (ver abajo) |
documentNumber | Mínimo 6 caracteres |
email | Correo del cliente |
currency | Siempre USD para Ecuador |
| Valor | Documento |
|---|---|
CI | Cédula de Identidad 🇪🇨 |
RUC | Registro Único de Contribuyentes 🇪🇨 |
PAS | Pasaporte 🇪🇨 |
Nota: bankIdno es requerido en Ecuador. No necesitas llamar al endpoint de lista de bancos para este país.
Inicia la transacción
Usando tu Private Merchant ID, llama al endpoint Init Transaction con el La respuesta depende del procesador habilitado para tu comercio:
El
token obtenido en el paso anterior. Kushki valida el token y devuelve los datos que necesitas para completar el pago.Transferencia bancaria tradicional
DeUna!
| Campo | Descripción |
|---|---|
redirectUrl | URL de un solo uso para redirigir al cliente a su banco |
ticketNumber | Identificador de la transacción en Kushki |
transactionReference | Referencia única de esta transacción |
details.status | Estado inicial: siempre initializedTransaction en este punto |
redirectUrl es de un solo uso: redirige a tu cliente a esa URL inmediatamente después de recibirla.El cliente completa el pago
Transferencia bancaria tradicional
DeUna!
El cliente es redirigido al portal de su banco y autoriza (o rechaza) la transferencia. Este paso ocurre por completo del lado del banco: tu backend no necesita hacer nada.Cuando el cliente termina, el banco lo redirige de vuelta a tu
callbackUrl.Consulta el estado de la transacción
Después de que el cliente aterriza en tu Estados posibles en Ecuador:
callbackUrl, llama al endpoint Get Status usando el token original como parámetro de ruta para confirmar el resultado final de la transacción.| Estado | Significado |
|---|---|
initializedTransaction | La transacción se creó pero aún no se completó |
approvedTransaction | Transferencia autorizada: los fondos están en camino |
declinedTransaction | La transferencia fue rechazada |
No tomes el regreso del cliente a tu callbackUrlcomo comprobante de pago. Confirma siempre con Get Status o con un webhook.
Integrar DeUna!
Renderizar el código QR
qr contiene una imagen PNG codificada en Base64, con el prefijo data:image/png;base64, ya incluido. Tu sitio debe leer el valor y renderizarlo como imagen en tu checkout: Kushki no aloja la imagen del QR por ti.No agregues el prefijo dos veces
qr ya trae el prefijo data:image/png;base64,, concatenarlo de nuevo produce un data URI inválido y la imagen falla en silencio: te queda un espacio en blanco sin error en consola.Expiración
| Ítem | Vigencia |
|---|---|
| Token de Transfer In | 30 minutos |
| QR, deep link y código de referencia de DeUna! | 3 minutos |
Límites de transacción
| Límite | Valor |
|---|---|
| Monto mínimo por transacción | USD 1.00, no configurable |
| Máximo por usuario, por día | USD 5,000 |
| Máximo por usuario, por mes | USD 36,000 |
| Moneda | Solo USD |
Disponibilidad por tipo de integración
| Capacidad | API · Kushki JS | Kajita · SmartLinks |
|---|---|---|
| Redirección por deep link | ✅ Sí | ✅ Sí |
| Código de referencia | ✅ Sí | ✅ Sí |
| QR dinámico | ✅ Sí | ❌ No se renderiza |
| Logo de DeUna! en el checkout | ✅ Tu propio diseño | ❌ Texto genérico de transferencia |
| Transferencia tradicional + DeUna! en paralelo | ✅ Sí | ❌ Solo un procesador |
Recomendación
Merchant ID
Objeto amount
amount es requerido tanto en el paso de Token como en el de Init Transaction. Usa la siguiente estructura según si la transacción tiene impuestos o no:Con impuestos (IVA)
Sin impuestos (IVA 0)
Con impuestos adicionales
{
"amount": {
"subtotalIva": 100.00,
"subtotalIva0": 0,
"iva": 12.00
}
}subtotalIva la base imponible y en iva el valor del impuesto. Envía 0 en subtotalIva0.Notificaciones por webhook
webhooks en tu petición de Init Transaction. 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/transfer-in"
]
}
]
}webhooks en la petición de la API dispara ambos canales. No son mutuamente excluyentes.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 (desde Kushki Console → Credentials) |
| Get Status | Private-Merchant-Id | Private Key |
Private-Merchant-Id en código de cliente o de frontend. Las peticiones de token con la Public Key se pueden hacer desde el frontend; todas las demás llamadas deben salir de tu backend.Usar la API
🟢 Producción
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Endpoints disponibles
Solicitar un token de Transfer In
Tokeniza los datos de la transacción. Requiere Public Merchant ID. El token es válido por 30 minutos y de un solo uso.¿Tienes una sugerencia sobre esta documentación? Escríbenos.
Modified at 2026-09-11 14:47:23