GET /v1/platforms incluye currency en cada plataforma. GET /me/usersbank también incluye currency, resuelta por el backend desde la plataforma o el proveedor de cuentas antiguas. Esta moneda alimenta el selector de Verificar pago: no es necesario mantener un mapa de bancos y monedas en el frontend.
Bancos habilitados y valores predeterminados
GET /v1/platforms es público: cada plataforma publica default_enabled, always_enabled, sus proveedores y sus canales compatibles. Sin selección personalizada se habilitan las plataformas predeterminadas, incluidos los canales de notificaciones compatibles, Binance, Exterior por Gmail y la cuenta demo. La cuenta demo está siempre habilitada.
GET /me/bank-access requiere sesión o API key y devuelve el acceso efectivo. Un cliente hereda las integraciones del propietario sin recibir su plan, saldo ni límites. Las cuentas creadas con sesión o API key de cliente quedan vinculadas a ese cliente.
curl 'https://api.pabilo.app/me/bank-access' \
-H 'Authorization: Bearer TU_ACCESS_TOKEN'{
"show_all_hidden_banks": false,
"platforms": [
{
"platform": "exterior",
"providers": [],
"enable_gmail": true,
"enable_notification_app": false,
"enable_notification_sms": false
}
]
}La respuesta anterior es un ejemplo abreviado. platforms contiene las integraciones efectivamente habilitadas para la sesión.
Un administrador autorizado puede configurar PUT /v1/admin/users/:userId/custom-data. Con show_all_hidden_banks: true se habilita también la creación en todos los proveedores implementados y los canales compatibles, aunque exista una selección personalizada. Al desactivarlo vuelve a aplicarse esa selección. Omitir el campo conserva su valor.
{
"show_all_hidden_banks": true
}allowed_platform_providers: [] restaura los valores predeterminados del catálogo. Una lista no vacía define una selección personalizada. Las credenciales del banco, la capacidad del proveedor y la pertenencia de las cuentas al cliente continúan validándose.
Cuentas Bancarias API
Consulta, registra y administra programáticamente las cuentas bancarias donde recibes pagos o desde donde emites vueltos.
Cada cuenta expone qué campos exige el banco para validar pagos a través de verifications_types_available.
Las credenciales bancarias y tokens se cifran con estándares de alta seguridad antes de almacenarse.
Activa, pausa o elimina cuentas según las necesidades de tu comercio o clientes subcuentas.
B2B2B: conectar la cuenta bancaria de tu cliente
Si tu empresa integra Pabilo para que otros comercios cobren, vincula cada cuenta al cliente que recibe el dinero. Así, el enlace de pago muestra el nombre de ese comercio en Le pagas a, no el de tu empresa integradora.
1. Crea o elige el cliente y guarda su ID
El cliente debe existir y pertenecer al titular de tu integración. Consulta cómo crear un cliente en Clientes API. Si ya existe, reutiliza su id; también puedes obtener tus clientes con GET /v1/clients/myclients. No crees otro registro por cada cuenta o cobro.
curl -X POST https://api.pabilo.app/v1/clients/create \
-H "appKey: API_KEY_DEL_TITULAR" \
-H "Content-Type: application/json" \
-d '{
"name": "Comercio Centro",
"company_name": "Comercio Centro, C.A.",
"type": "company",
"generate_nick": false
}'Guarda client.id de la respuesta como CLIENTE_RECEPTOR_ID. Este ejemplo no crea un inicio de sesión ni envía credenciales; si tu cliente necesita acceder al portal, sigue la guía de Clientes API. Crear la cuenta bancaria no crea automáticamente el cliente.
2. Envía ese ID en client_owner_id al crear la cuenta
Con la sesión o llave del titular, añade client_owner_id al cuerpo de POST /usersbank. Es el ID del cliente de Pabilo, no el Client ID que algunos bancos entregan como credencial. Mantén las credenciales y la metadata requeridas por el proveedor elegido.
curl -X POST https://api.pabilo.app/usersbank \
-H "appKey: API_KEY_DEL_TITULAR" \
-H "Content-Type: application/json" \
-d '{
"client_owner_id": "CLIENTE_RECEPTOR_ID",
"bank_provider": "VE_BAN",
"username": "USUARIO_BANCARIO_DEL_CLIENTE",
"password": "CLAVE_BANCARIA_DEL_CLIENTE",
"description": "Cuenta BDV de Comercio Centro"
}'Sustituye los IDs de ejemplo por los IDs reales de las respuestas. El servidor obtiene el usuario titular desde la autenticación y valida que el cliente le pertenezca. Con JWT o API key del propio cliente, omite client_owner_id: Pabilo asigna su identidad automáticamente y no permite elegir otro cliente.
Guarda userbank.id de la respuesta como CUENTA_RECEPTORA_ID. Para comprobar la vinculación, usa GET /me/usersbank?client_id=CLIENTE_RECEPTOR_ID con el acceso del titular y verifica el client_owner_id de la cuenta. Listar requiere lectura de bank_accounts; crear requiere escritura. La llave debe incluir la cuenta en su alcance cuando tenga una selección explícita.
¿La cuenta ya existe? Asigna o cambia el cliente sin recrearla
No borres la cuenta ni vuelvas a enviar sus credenciales. El titular puede vincular una cuenta antigua o corregir su cliente con PUT /v1/usersbank/:user_bank_id/client-owner. Usa el JWT del propio titular: este cambio no acepta sesiones de empleado, cliente ni API keys.
curl -X PUT https://api.pabilo.app/v1/usersbank/CUENTA_RECEPTORA_ID/client-owner \
-H "Authorization: Bearer JWT_DEL_TITULAR" \
-H "Content-Type: application/json" \
-d '{"client_owner_id":"CLIENTE_RECEPTOR_ID"}'El cliente debe pertenecer al mismo titular. El cuerpo debe incluir client_owner_id: un ID válido asigna o cambia la asociación; null la elimina. Omitir el campo o enviar una cadena vacía devuelve 400.
{
"client_owner_id": null
}Solo cambia esa asociación: conserva el ID de la cuenta, credenciales, teléfono, cédula, configuración de pago, referencias e historial. Los enlaces existentes consultan el receptor desde la cuenta y reflejan el nuevo nombre al recargarlos; no se reasigna el historial de consumos ya registrado.
Si la cuenta está enlazada a notificaciones o a cuentas de respaldo cuyo cliente quedaría incompatible, el cambio se rechaza sin modificar nada. Revisa y desvincula primero esas relaciones; este endpoint no las mueve ni las borra automáticamente. Las cuentas virtuales de recolección se administran desde su módulo, no desde este endpoint.
3. Genera el enlace usando la cuenta de ese cliente
curl -X POST https://api.pabilo.app/v1/paymentlink \
-H "appKey: API_KEY_DEL_TITULAR" \
-H "Content-Type: application/json" \
-d '{
"user_bank_id": "CUENTA_RECEPTORA_ID",
"name": "Pedido de Comercio Centro",
"amount": 100,
"currency": "VEF",
"type": "default",
"notification_by_whastapp": true
}'Usa acceso del titular autorizado sobre la cuenta receptora. Abre paymentlink.url de la respuesta: Le pagas a toma company_name del cliente asociado a la cuenta o, si está vacío, su name. Las cuentas sin cliente asociado conservan el nombre del titular de Pabilo; también se usa ese nombre si el cliente fue eliminado o deshabilitado. No necesitas activar white_label para identificar al receptor.
No confundas los dos clientes: user_bank.client_owner_id identifica al comercio receptor. El client_id opcional de un enlace identifica al comprador al que se dirige el cobro; no cambia quién recibe el dinero ni el nombre de Le pagas a. Consulta los demás parámetros en Enlaces de pago API.
Con una sesión o llave de cliente, GET /me/usersbank devuelve exclusivamente sus cuentas; no permite consultar las de otros clientes. Los listados legacy globales son administrativos: para integraciones usa los endpoints /me.
1. Listar Cuentas Bancarias (GET /me/usersbank)
Obtén un listado de todas las cuentas bancarias asociadas a tu usuario autenticado.
https://api.pabilo.app/me/usersbankcurl -X GET https://api.pabilo.app/me/usersbank \
-H "Authorization: Bearer TU_API_KEY"Parámetros de Consulta (Query Params)
client_id(opcional, string): Filtra el listado a las cuentas pertenecientes a un subcliente específico. El resultado siempre queda restringido a tus cuentas; si elclient_idno te pertenece, retorna un arreglo vacío.
curl -X GET "https://api.pabilo.app/me/usersbank?client_id=685725869e6febc736848bc9" \
-H "Authorization: Bearer TU_API_KEY"Respuesta de Ejemplo
{
"message": "Usersbank fetched successfully",
"user_banks": [
{
"id": "685725c59e6febc736848bf5",
"created_at": "2025-06-21T21:36:05.659Z",
"updated_at": "2026-01-01T15:59:17.877Z",
"user_id": "685725869e6febc736848bf1",
"description": "Mi cuenta principal",
"provider": "VE_BAN",
"bank_accounts": [
{
"account_number": "01020656110100004041",
"account_type": "CUENTA DE AHORRO"
}
],
"default_bank_account": {
"account_number": "01020656110100004041",
"account_type": "CUENTA DE AHORRO"
},
"user_bank_phone": {
"countryCode": "58",
"number": "4248343530"
},
"payment_link": true,
"to_trash": false,
"metadata": null,
"verifications_types_available": [
{
"id": "GENERIC",
"fields_required": [
{
"name": "REFERENCE_NUMBER",
"type": "STRING"
}
]
}
]
},
{
"id": "698e270a94dc637846e7a9eb",
"created_at": "2026-02-12T19:16:26.576Z",
"updated_at": "2026-02-12T21:38:32.598Z",
"user_id": "685725869e6febc736848bf1",
"description": "Cuenta Mercantil Jurídica",
"provider": "MERCANTIL_EMP_V1",
"bank_accounts": [
{
"account_number": "01050054151054540721",
"account_type": "CORRIENTE"
}
],
"default_bank_account": {
"account_number": "01050054151054540721",
"account_type": "CORRIENTE"
},
"payment_link": true,
"to_trash": false,
"verifications_types_available": [
{
"id": "MOVIL_PAY",
"fields_required": [
{
"name": "REFERENCE_NUMBER",
"type": "STRING"
},
{
"name": "PHONE_ORIGIN",
"type": "FULL_PHONE"
},
{
"name": "DNI_ORIGIN",
"type": "FULL_DNI"
},
{
"name": "BANK_CODE_ORIGIN",
"type": "BANK_ORIGIN_CODE"
},
{
"name": "PAYMENT_DATE",
"type": "DATE"
}
]
},
{
"id": "TRANSFER",
"fields_required": [
{
"name": "REFERENCE_NUMBER",
"type": "STRING"
},
{
"name": "DNI_ORIGIN",
"type": "FULL_DNI"
},
{
"name": "BANK_CODE_ORIGIN",
"type": "BANK_ORIGIN_CODE"
},
{
"name": "PAYMENT_DATE",
"type": "DATE"
}
]
}
]
}
]
}Campos Dinámicos de Verificación (verifications_types_available)
Cada cuenta bancaria expone un arreglo verifications_types_available que define con exactitud qué tipos de movimiento admite y cuáles campos debes enviar en la petición de verificación, permitiéndote construir formularios dinámicos.
¿Cómo interpretar y usar este arreglo?
1. Inspecciona verifications_types_available de la cuenta seleccionada.
2. Elige el tipo deseado (id) y envíalo en el body como movement_type (ej. "GENERIC" o "MOVIL_PAY").
3. En el body de verificación, incluye exactamente los campos indicados en fields_required[].name para ese tipo.
Para el detalle de formatos de cada campo, consulta la referencia completa de campos de verificación →
| Propiedad | Tipo | Descripción |
|---|---|---|
| id | string | Tipo de verificación soportado (envíalo como movement_type al verificar). Valores posibles: GENERIC, MOVIL_PAY, TRANSFER, C2P. |
| fields_required | array | Lista de campos obligatorios requeridos por el banco para este tipo de verificación. |
| fields_required[].name | string | Identificador de la constante del campo (ej. REFERENCE_NUMBER, PHONE_ORIGIN, DNI_ORIGIN). |
| fields_required[].type | string | Tipo de dato esperado (STRING, FULL_DNI, FULL_PHONE, BANK_ORIGIN_CODE, DATE). |
// 1. Obtén las cuentas del usuario
const { user_banks } = await fetch("https://api.pabilo.app/me/usersbank", {
headers: { "Authorization": "Bearer TU_API_KEY" }
}).then(r => r.json());
// 2. Selecciona la cuenta bancaria destino
const account = user_banks.find(b => b.id === "698e270a94dc637846e7a9eb");
// 3. Elige el tipo de verificación (ej. MOVIL_PAY)
const verificationType = account.verifications_types_available.find(v => v.id === "MOVIL_PAY");
const requiredFields = verificationType.fields_required.map(f => f.name);
// 4. Construye el body dinámicamente según lo que exige el banco
const body = {
movement_type: verificationType.id, // "MOVIL_PAY"
amount: 150.75,
...(requiredFields.includes("REFERENCE_NUMBER") && { bank_reference: "98765432" }),
...(requiredFields.includes("PHONE_ORIGIN") && { phone_pagador: "04141234567" }),
...(requiredFields.includes("DNI_ORIGIN") && { dni_pagador: { dni_type: "V", dni_number: "12345678" } }),
...(requiredFields.includes("BANK_CODE_ORIGIN") && { bank_origin: "0102" }),
...(requiredFields.includes("PAYMENT_DATE") && { fecha_pago: "2026-08-03" }),
};
// 5. Verifica el pago
const result = await fetch(`https://api.pabilo.app/userbankpayment/${account.id}/betaserio`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer TU_API_KEY"
},
body: JSON.stringify(body),
}).then(r => r.json());2. Crear una Cuenta Bancaria (POST /usersbank)
Registra una nueva cuenta bancaria conectando las credenciales necesarias para la consulta electrónica.
https://api.pabilo.app/usersbankcurl -X POST https://api.pabilo.app/usersbank \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_API_KEY" \
-d '{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "VE_BAN",
"username": "usuario_banco",
"password": "password_banco",
"description": "Mi Cuenta BDV"
}'Proveedores Soportados (bank_provider)
Especifica el valor correspondiente de bank_provider y adjunta las credenciales o metadatos requeridos:
| Banco / Proveedor | Código (bank_provider) | Credenciales & Metadata Requerida |
|---|---|---|
| Banco de Venezuela (Personas) | VE_BAN | username (Usuario BDV en línea), password (Contraseña) |
| Banco de Venezuela (Empresas V2 - API) | VE_BAN_EMP_V2 | username (Número de Cuenta 20 dígitos), password (API Key del BDV) |
| Banco Mercantil (J) | MERCANTIL_EMP_V1 | username (Client ID), password (Secret Key)Metadata requerida:
|
| Banesco (J) | VE_BANESCO_V1 | username (Client ID), password (Client Secret)Metadata requerida:
Pabilo configura el origen autorizado para la conexión con Banesco; no debes enviar ni configurar una IP de dispositivo. Metadata opcional:
|
| Banesco (J Sandbox) | VE_BANESCO_QA_V1 | Igual que VE_BANESCO_V1 (entorno de pruebas/sandbox). |
| Banco Plaza (J) | VE_BANK_PLAZA_V1 | username (Client ID), password (Client Secret)Metadata requerida:
|
| Banco Plaza (J Sandbox) | VE_BANK_PLAZA_QA_V1 | Igual que VE_BANK_PLAZA_V1 (entorno de pruebas/sandbox). |
| Binance Pay | BINANCE_APP | username (Binance API Key), password (Secret Key)Metadata opcional:
|
| Banco de Pruebas (QA Sandbox) | BANK_TEST | Sin credenciales bancarias requeridas. Simula pagos exitosos con la referencia 67890 y movement_type: "GENERIC". |
| Notificaciones Pabilo (SMS / App) | NOTIFICATION_ACCOUNT | user_bank_phone (teléfono receptor) y user_bank_dni (cédula del titular). Vincula un dispositivo Android para capturar pagos vía SMS bancario o notificaciones push. |
Ejemplos de Creación con Metadata
Banco Plaza (J)
{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "VE_BANK_PLAZA_V1",
"username": "mi_client_id_plaza",
"password": "mi_client_secret_plaza",
"description": "Cuenta Plaza Principal",
"metadata": [
{
"key_name": "ACCOUNT_NUMBER",
"key_value": "01380000000000000000"
}
]
}Banco Mercantil (J)
{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "MERCANTIL_EMP_V1",
"username": "CLIENT_ID_MERCANTIL",
"password": "SECRET_KEY_MERCANTIL",
"description": "Cuenta Mercantil Jurídica",
"metadata": [
{
"key_name": "INTEGRATOR_ID",
"key_value": "12345"
},
{
"key_name": "TERMINAL_ID",
"key_value": "TERM001"
},
{
"key_name": "MERCHANT_ID",
"key_value": "MERC001"
}
]
}Banesco (J)
{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "VE_BANESCO_V1",
"username": "CLIENT_ID_BANESCO",
"password": "CLIENT_SECRET_BANESCO",
"description": "Cuenta Banesco Jurídica",
"metadata": [
{
"key_name": "ACCOUNT_NUMBER",
"key_value": "01340000000000000000"
},
{
"key_name": "SHOW_DATE_IN_MOVEMENTS",
"key_value": "true"
}
]
}Binance Pay
{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "BINANCE_APP",
"username": "mi_api_key_binance",
"password": "mi_secret_key_binance",
"description": "Cuenta Binance USDT",
"metadata": [
{
"key_name": "BINANCE_VALIDATION_TYPE",
"key_value": "GLOBAL"
}
]
}Banco QA (Sandbox de Pruebas)
{
"user_id": "685725869e6febc736848bf1",
"bank_provider": "BANK_TEST",
"description": "Cuenta de Pruebas Sandbox"
}3. Activar / Desactivar Cuenta Bancaria
Alterna el estado operativo de una cuenta bancaria entre activa e inactiva.
https://api.pabilo.app/v1/usersbank/{user_bank_id}/toggle-disabledcurl -X PUT https://api.pabilo.app/v1/usersbank/685725c59e6febc736848bf5/toggle-disabled \
-H "Authorization: Bearer TU_API_KEY"{
"message": "Usersbank updated successfully",
"usersbank": {
"id": "685725c59e6febc736848bf5",
"provider": "VE_BAN",
"is_disabled": true
},
"is_disabled": true
}Impacto Operativo
is_disabled: true) no procesará nuevas verificaciones de pago ni vueltos. Si el cliente o subcuenta propietaria se encuentra deshabilitada, la cuenta queda automáticamente inaccesible independientemente de su propio estado.4. Eliminar una Cuenta Bancaria
Solicita la baja de una cuenta bancaria registrada. El flujo depende de la autorización de eliminación configurada para el titular:
https://api.pabilo.app/usersbank/{userBankId}/to-trashcurl -X DELETE https://api.pabilo.app/usersbank/685725c59e6febc736848bf5/to-trash \
-H "Authorization: Bearer TU_API_KEY"| Modalidad del Plan | Comportamiento del Sistema |
|---|---|
| Cuenta con baja directa autorizada | La cuenta bancaria se elimina inmediatamente de forma atómica sin requerir aprobaciones manuales. |
| Cuenta con revisión de baja | La cuenta entra en un proceso de aprobación de seguridad. Se marca como to_trash: true y un administrador aprueba su eliminación definitiva para proteger la conciliación contable. |
{
"message": "Usersbank moved to trash successfully",
"usersbank": {
"id": "685725c59e6febc736848bf5",
"provider": "VE_BAN",
"to_trash": true
}
}Bloqueo de Operaciones en Estado to_trash
to_trash: true pendiente de aprobación, quedará suspendida y no admitirá nuevas verificaciones de pago ni emisión de vueltos.5. Actualizar Contraseña o API Key
Actualiza programáticamente las credenciales de acceso de tu cuenta bancaria (contraseña de banco en línea, API Secret o API Key) con verificación en tiempo real ante la entidad financiera.
https://api.pabilo.app/v1/usersbank/{user_bank_id}/change-secretUso por API vs. Panel Web
Este endpoint está diseñado para integraciones programáticas y servidores que se autentican con API Key o Bearer Token.
Si deseas cambiar la contraseña manualmente desde el panel web de Pabilo, se utiliza el formulario interactivo de la plataforma con código de confirmación por correo o SMS.
curl -X PUT https://api.pabilo.app/v1/usersbank/6615a2b3c4e5f60012345678/change-secret \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_API_KEY" \
-d '{
"secret": "NUEVA_CONTRASEÑA_O_API_KEY"
}'| Parámetro | Ubicación | Requerido | Descripción |
|---|---|---|---|
| user_bank_id | URL path | Sí | ID de la cuenta bancaria en Pabilo. |
| secret | Body (JSON) | Sí | Nueva contraseña bancaria, API Secret o API Key según el proveedor de la cuenta. |
Pabilo comprueba el acceso con el banco antes de guardar. Si las credenciales funcionan, se actualiza la cuenta y se desbloquea automáticamente si estaba bloqueada.
Solo se descuentan 0.5 créditos si el banco valida el nuevo secreto exitosamente. Si la clave es rechazada por el banco, no se cobra nada.
Debes esperar al menos 30 segundos entre intentos y un máximo de 1 actualización exitosa cada 30 minutos por cuenta.
Respuesta Exitosa (200 OK)
{
"message": "Usersbank secret changed successfully",
"usersbank": {
"id": "6615a2b3c4e5f60012345678",
"description": "Cuenta Principal",
"provider": "VE_BAN",
"is_disabled": false,
"is_block_by_bank": false
}
}Errores Frecuentes
| Código | Error | Motivo |
|---|---|---|
| 429 | PASSWORD_CHANGE_TRY_TOO_FREQUENT | Debes esperar al menos 30 segundos entre intentos. |
| 400 | PASSWORD_CHANGE_TOO_FREQUENT | El secreto ya fue cambiado exitosamente hace menos de 30 minutos. |
| 400 | NOT_ENOUGH_CREDITS | Saldo insuficiente (requiere al menos 0.5 créditos). |
| 400 / 500 | USER_BANCK_BAD_PASSWORD | El banco rechazó la contraseña o API Key suministrada. |