Kiwi Smart · Kiwi Verifica
API para verificar Pago Móvil
Conecta tu tienda web, tu sistema administrativo o tu bot y confirma los Pago Móvil directamente contra el banco, sin capturas y sin revisar la banca a mano. Cada pago solo se puede usar una vez.
Disponible hoy: cuentas de persona natural del Banco de Venezuela (BDV). Kiwi Verifica solo consulta movimientos: nunca transfiere ni mueve dinero.
1. Antes de empezar
- Tu negocio necesita el módulo Kiwi Verifica de Kiwi Smart.
- En tu panel, en Configuración → Cobros, enlaza tu cuenta de Pago Móvil BDV.
- En Pagos recibidos → API de Kiwi Verifica, crea una llave. Se muestra una sola vez: guárdala como secreto en tu servidor.
2. Autenticación
Todas las peticiones van a https://api.smart.agenciakiwi.com con tu llave en la cabecera:
Authorization: Bearer ksk_xxxxxxxx_...La llave identifica a tu negocio. Úsala solo desde tu servidor, nunca desde una página web o una app que vean tus clientes. Si se filtra, revócala en el panel y crea otra.
3. Verificar un pago
POST/v1/verifica/verifications
Busca el pago en tus cuentas enlazadas. Si lo encuentra, lo marca como usado: el mismo pago no sirve para otro cobro.
| Campo | Tipo | Descripción |
|---|---|---|
reference | texto | Referencia del Pago Móvil, solo dígitos. Mínimo los últimos 4; mejor 6 o más. |
amount | número | Monto exacto en bolívares, por ejemplo 1500.50. |
externalId | texto | Id del cobro en tu sistema (hasta 80 caracteres: letras, números y . _ : -). Repetirlo devuelve la misma respuesta, así que puedes reintentar sin miedo. |
date | AAAA-MM-DD | Opcional. Fecha del pago; obligatoria en la práctica si la referencia tiene menos de 6 dígitos. |
accountId | texto | Opcional. Cuenta donde buscar (de GET /v1/verifica/accounts). Sin ella, busca en todas. |
curl -X POST https://api.smart.agenciakiwi.com/v1/verifica/verifications \
-H "Authorization: Bearer $KIWI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reference":"004512345678","amount":1500.50,"externalId":"pedido-1042"}'{ "status": "MATCHED", "verificationId": "c9x...", "accountId": "pa_..." }| status | Qué significa | Qué hacer |
|---|---|---|
MATCHED | El pago está en el banco con ese monto y quedó marcado como usado. | Da el cobro por pagado. |
NOT_FOUND | No aparece (todavía). | Un pago puede tardar unos minutos en verse. Reintenta con el mismo externalId a los 2–5 minutos y revisa referencia y monto. |
ALREADY_USED | Ese pago ya se usó para otro cobro. | No lo aceptes: es un comprobante repetido. |
AMBIGUOUS | Hay más de un pago posible. | Pide la referencia completa o la fecha exacta. |
4. Pagos recibidos
GET/v1/verifica/payments?limit=50&accountId=...
Los últimos abonos que Kiwi Verifica leyó del banco (máximo 200), con used y, si lo usaste por la API, tu externalId.
[{ "id": "...", "accountId": "pa_...", "reference": "004512345678", "amount": "1500.50",
"date": "16-10-2026 08:48", "description": "PAGO MOVIL ...", "receivedAt": "2026-10-16T12:50:03Z",
"used": true, "usedAt": "2026-10-16T12:51:10Z", "externalId": "pedido-1042" }]5. Cuentas
GET/v1/verifica/accounts
Tus cuentas enlazadas y su estado: OK, PENDING (primera lectura en curso), ERROR (la última lectura falló; se reintenta sola) o PAUSED (hay que volver a enlazarla en el panel).
6. Errores
| HTTP | code | Causa |
|---|---|---|
| 400 | VALIDATION_ERROR | Algún campo no es válido. |
| 401 | API_KEY_INVALID | Llave ausente, mal escrita o revocada. |
| 403 | MODULE_NOT_ENABLED / TENANT_INACTIVE | Kiwi Verifica no está contratado o el negocio está suspendido. |
| 404 | ACCOUNT_NOT_FOUND | El accountId no es tuyo o no está enlazado. |
| 409 | NO_LINKED_ACCOUNT | Aún no enlazaste ninguna cuenta. |
| 429 | — | Demasiadas peticiones (100 por minuto). Espera y reintenta. |
| 502 / 504 | VERIFICA_* | Falla temporal al consultar. Reintenta con el mismo externalId. |
7. Bueno saber
- Kiwi Verifica lee el banco cada 5 minutos y además consulta al momento cuando verificas un pago que no ha visto.
- El BDV permite una sola sesión a la vez: si el titular está dentro de su banca en línea justo en ese instante, la lectura se salta y se repite en el siguiente ciclo.
- Es una conexión con la banca en línea del BDV hecha por Agencia Kiwi, no un servicio oficial del banco. Si el banco cambia su sistema puede haber pausas mientras lo adaptamos.
- Las credenciales bancarias se guardan cifradas y se borran al desenlazar la cuenta.