Saltar al contenido

    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.

    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.

    Crear el comercio sin generar credenciales de acceso
    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.

    Vincular la cuenta receptora al cliente existente
    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.

    Asignar o cambiar el cliente de una cuenta existente
    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.

    Desvincular del cliente y volver al titular de Pabilo
    {
      "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

    Cobrar a nombre del comercio receptor
    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.

    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.

    PropiedadTipoDescripción
    idstringTipo de verificación soportado (envíalo como movement_type al verificar). Valores posibles: GENERIC, MOVIL_PAY, TRANSFER, C2P.
    fields_requiredarrayLista de campos obligatorios requeridos por el banco para este tipo de verificación.
    fields_required[].namestringIdentificador de la constante del campo (ej. REFERENCE_NUMBER, PHONE_ORIGIN, DNI_ORIGIN).
    fields_required[].typestringTipo 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 / ProveedorCódigo (bank_provider)Credenciales & Metadata Requerida
    Banco de Venezuela (Personas)VE_BANusername (Usuario BDV en línea), password (Contraseña)
    Banco de Venezuela (Empresas V2 - API)VE_BAN_EMP_V2username (Número de Cuenta 20 dígitos), password (API Key del BDV)
    Banco Mercantil (J)MERCANTIL_EMP_V1username (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_V1username (Client ID), password (Client Secret)
    Metadata requerida:
    • ACCOUNT_NUMBER: Número de cuenta de 20 dígitos que comience con 0134
    Configuración automática:

    Pabilo configura el origen autorizado para la conexión con Banesco; no debes enviar ni configurar una IP de dispositivo.

    Metadata opcional:
    • SHOW_DATE_IN_MOVEMENTS: true | false
    Banesco (J Sandbox)VE_BANESCO_QA_V1Igual que VE_BANESCO_V1 (entorno de pruebas/sandbox).
    Banco Plaza (J)VE_BANK_PLAZA_V1username (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_V1Igual que VE_BANK_PLAZA_V1 (entorno de pruebas/sandbox).
    Binance PayBINANCE_APPusername (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_TESTSin credenciales bancarias requeridas. Simula pagos exitosos con la referencia 67890 y movement_type: "GENERIC".
    Notificaciones Pabilo (SMS / App)NOTIFICATION_ACCOUNTuser_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)

    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)

    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)

    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

    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
    }

    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:

    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 PlanComportamiento del Sistema
    Cuenta con baja directa autorizadaLa cuenta bancaria se elimina inmediatamente de forma atómica sin requerir aprobaciones manuales.
    Cuenta con revisión de bajaLa 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
      }
    }

    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
    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ámetroUbicaciónRequeridoDescripción
    user_bank_idURL pathSíID de la cuenta bancaria en Pabilo.
    secretBody (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ódigoErrorMotivo
    429PASSWORD_CHANGE_TRY_TOO_FREQUENTDebes esperar al menos 30 segundos entre intentos.
    400PASSWORD_CHANGE_TOO_FREQUENTEl secreto ya fue cambiado exitosamente hace menos de 30 minutos.
    400NOT_ENOUGH_CREDITSSaldo insuficiente (requiere al menos 0.5 créditos).
    400 / 500USER_BANCK_BAD_PASSWORDEl banco rechazó la contraseña o API Key suministrada.