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.

bash

curl 'https://api.pabilo.app/me/bank-access' \
  -H 'Authorization: Bearer TU_ACCESS_TOKEN'

json

{
  "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.

json

{
  "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.

Conectividad Bancaria

Multi-Banco

Cuentas Bancarias API

Consulta, registra y administra programáticamente las cuentas bancarias donde recibes pagos o desde donde emites vueltos.

Campos Dinámicos

Cada cuenta expone qué campos exige el banco para validar pagos a través de verifications_types_available.

Credenciales Seguras

Las credenciales bancarias y tokens se cifran con estándares de alta seguridad antes de almacenarse.

Control de Estado

Activa, pausa o elimina cuentas según las necesidades de tu comercio o clientes subcuentas.

Cuentas de clientes

Con una sesión del titular, GET /me/usersbank?client_id=CLIENT_ID limita el listado a las cuentas de uno de sus clientes. Al crear con POST /usersbank, puede indicar client_owner_id; el backend valida que sea un cliente suyo.

Con una sesión o llave de cliente, GET /me/usersbank devuelve exclusivamente sus cuentas y el alta asigna automáticamente su identidad. No es posible elegir otro dueño ni consultar cuentas de clientes hermanos. Requiere bank_accounts (lectura o escritura según la operación).

Los listados legacy globales son administrativos. Para integraciones use los endpoints /me.

1. Listar Cuentas Bancarias (GET /me/usersbank)

Obtén un listado de todas las cuentas bancarias asociadas a tu usuario autenticado.

GET

https://api.pabilo.app/me/usersbank

GET /me/usersbank

curl -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 el client_id no te pertenece, retorna un arreglo vacío.

GET /me/usersbank?client_id=CLIENT_ID

curl -X GET "https://api.pabilo.app/me/usersbank?client_id=685725869e6febc736848bc9" \
  -H "Authorization: Bearer TU_API_KEY"

Respuesta de Ejemplo

Respuesta JSON (200 OK)

{
  "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`).

Ejemplo: Construcción dinámica del payload de verificación

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

POST

https://api.pabilo.app/usersbank

POST /usersbank

curl -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: `INTEGRATOR_ID`: ID numérico del integrador `TERMINAL_ID`: ID del terminal asignado por el banco `MERCHANT_ID`: ID del comercio Mercantil
Banesco (J)	VE_BANESCO_V1	`username` (Client ID), `password` (Client Secret) Metadata requerida: `ACCOUNT_NUMBER`: Número de cuenta de 20 dígitos que comience con `0134` Metadata opcional: `DEVICE_IP`: IP pública autorizada (toma la IP por defecto si se omite) `SHOW_DATE_IN_MOVEMENTS`: `true` \| `false`
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: `ACCOUNT_NUMBER`: Número de cuenta Plaza de 20 dígitos (comienza con `0138`)
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: `BINANCE_VALIDATION_TYPE`: `GLOBAL` (por defecto), `BY_USER`, `BY_DATE`, `BY_NOTE`, `BY_ORDER`
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": "DEVICE_IP",
      "key_value": "152.53.88.89"
    },
    {
      "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)

BANK_TEST Sandbox

{
  "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.

PUT

https://api.pabilo.app/v1/usersbank/{user_bank_id}/toggle-disabled

PUT /v1/usersbank/:user_bank_id/toggle-disabled

curl -X PUT https://api.pabilo.app/v1/usersbank/685725c59e6febc736848bf5/toggle-disabled \
  -H "Authorization: Bearer TU_API_KEY"

Respuesta JSON

{
  "message": "Usersbank updated successfully",
  "usersbank": {
    "id": "685725c59e6febc736848bf5",
    "provider": "VE_BAN",
    "is_disabled": true
  },
  "is_disabled": true
}

Impacto Operativo

Una cuenta desactivada (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 varía según el modelo de suscripción contratado:

DELETE

https://api.pabilo.app/usersbank/{userBankId}/to-trash

DELETE /usersbank/:userBankId/to-trash

curl -X DELETE https://api.pabilo.app/usersbank/685725c59e6febc736848bf5/to-trash \
  -H "Authorization: Bearer TU_API_KEY"

Modalidad del Plan	Comportamiento del Sistema
Plan B2B2B (Integradores / SaaS)	La cuenta bancaria se elimina inmediatamente de forma atómica sin requerir aprobaciones manuales.
Plan B2B Directo (Comercios)	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.

Respuesta JSON

{
  "message": "Usersbank moved to trash successfully",
  "usersbank": {
    "id": "685725c59e6febc736848bf5",
    "provider": "VE_BAN",
    "to_trash": true
  }
}

Bloqueo de Operaciones en Estado to_trash

Mientras una cuenta permanezca con 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

Validación en Vivo

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.

PUT

https://api.pabilo.app/v1/usersbank/{user_bank_id}/change-secret

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

PUT /v1/usersbank/:user_bank_id/change-secret

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.

Validación en Vivo

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.

Costo (0.5 Créditos)

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.

Tiempos de Espera

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)

Respuesta JSON (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.