Cuentas Bancarias API

Gestiona tus cuentas bancarias programáticamente.

Listar Mis Cuentas

Obtén un listado de todas las cuentas bancarias asociadas a tu usuario.
Nota: Necesitas tu USER_ID. Ver Cómo obtener mi ID.

GET /me/usersbank

curl -X GET https://api.pabilo.app/me/usersbank \
  -H "Authorization: Bearer TU_API_KEY"

Parámetros de consulta

client_id (opcional) — filtra el listado a las cuentas de un cliente específico tuyo. El resultado siempre queda acotado a tus propias cuentas: si el client_id no pertenece a tu usuario, la respuesta llega vacía.
Si autenticas como cliente, este parámetro se ignora: siempre se usa tu propio identificador, de modo que no puedes ver las cuentas de otros clientes.

GET /me/usersbank?client_id=CLIENT_ID

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

Respuesta de Ejemplo

json

{
    "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",
            "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": "584248343530 account",
            "provider": "MERCANTIL_EMP_TEST_V1",
            "bank_accounts": [
                {
                    "account_number": "01050054151054540721",
                    "account_type": "UNKNOWN"
                }
            ],
            "default_bank_account": {
                "account_number": "01050054151054540721",
                "account_type": "UNKNOWN"
            },
            "payment_link": true,
            "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

Cada cuenta bancaria expone el array verifications_types_available que indica qué tipos de verificación admite y qué campos debes enviar en cada caso. Usa esta información para construir peticiones dinámicas al endpoint de verificación sin necesidad de lógica por banco.

¿Cómo usarlo?

1. Lee verifications_types_available de la cuenta destino.

2. Elige el tipo de verificación (id) y envíalo como movement_type.

3. Envía en el body exactamente los campos listados en fields_required[].name de ese tipo.

Consulta el formato y tipo de dato de cada campo en la referencia de campos de verificación.

Estructura de `verifications_types_available`

Campo	Tipo	Descripción
id	string	Identificador del tipo de verificación. Envíalo como `movement_type` en la petición de verificación. Valores: `GENERIC`, `MOVIL_PAY`, `TRANSFER`, `C2P`
fields_required	array	Lista de campos que debes incluir en el body al verificar un pago con este tipo.
fields_required[].name	string	Constante que identifica el campo. Ver referencia completa de campos.
fields_required[].type	string	Tipo de dato esperado (`STRING`, `FULL_DNI`, `FULL_PHONE`, `BANK_ORIGIN_CODE`, `DATE`, etc.)

Ejemplo de uso en código

Construcción dinámica del body 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 destino
const account = user_banks.find(b => b.id === 'USER_BANK_ID');

// 3. Elige el tipo de verificación (ej. el primero disponible)
const verificationType = account.verifications_types_available[0];
const requiredFields = verificationType.fields_required.map(f => f.name);
// → ["REFERENCE_NUMBER", "PHONE_ORIGIN", "DNI_ORIGIN", "BANK_CODE_ORIGIN", "PAYMENT_DATE"]

// 4. Construye el body dinámicamente
const body = {
  movement_type: verificationType.id,   // "MOVIL_PAY"
  amount: 150.75,

  // Incluye solo los campos que pide el banco
  ...(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: '2024-02-12' }),
};

// 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());

Crear una Cuenta Bancaria

Registra una nueva cuenta bancaria para empezar a recibir pagos.

POST /usersbank

curl -X POST https://api.pabilo.app/usersbank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -d '{
    "user_id": "USER_ID",
    "bank_provider": "BANCO_DE_VENEZUELA",
    "username": "usuario_banco",
    "password": "password_banco",
    "description": "Mi Cuenta BVD"
  }'

Nota: Los credenciales bancarios se almacenan encriptados y son necesarios para la verificación automática.

Proveedores Soportados

Utiliza los siguientes valores para el campo bank_provider y ten en cuenta los campos requeridos para cada uno:

Banco	Valor (bank_provider)	Campos Requeridos
Banco de Venezuela (Personas)	VE_BAN	`username` (Usuario), `password` (Contraseña)
Banco de Venezuela (Empresas V2 - API)	VE_BAN_EMP_V2	`username` (Número de Cuenta), `password` (API Key)
Banco Mercantil (J)	MERCANTIL_EMP_V1	`username` (Client ID), `password` (Secret Key) Metadata Requerida: - `INTEGRATOR_ID` (ID Numérico) - `TERMINAL_ID` (ID del Terminal) - `MERCHANT_ID` (ID del Comercio)
Banesco (J)	VE_BANESCO_V1	`username` (Client ID), `password` (Client Secret) Metadata Requerida: - `ACCOUNT_NUMBER` (Número de cuenta, debe comenzar con `0134`) Metadata Opcional: - `DEVICE_IP` (IP del dispositivo; se usa la IP por defecto si no se especifica) - `SHOW_DATE_IN_MOVEMENTS`: `true` \| `false`
Banesco (J Sandbox)	VE_BANESCO_QA_V1	Igual que `VE_BANESCO_V1` (solo para pruebas)
Banco Plaza (J)	VE_BANK_PLAZA_V1	`username` (Client ID), `password` (Client Secret) Metadata Requerida: - `ACCOUNT_NUMBER` (Número de Cuenta)
Banco Plaza (J Sandbox)	VE_BANK_PLAZA_QA_V1	Igual que `VE_BANK_PLAZA_V1` (solo para pruebas)
Binance	BINANCE_APP	`username` (Clave API), `password` (Clave Secreta) Metadata Opcional: - `BINANCE_VALIDATION_TYPE`: `GLOBAL` \| `BY_USER` \| `BY_DATE` \| `BY_NOTE` \| `BY_ORDER` (default: `GLOBAL`)
Banco QA (Sandbox)	BANK_TEST	Sin credenciales adicionales (solo para pruebas)
Notificaciones Pabilo	NOTIFICATION_ACCOUNT	`user_bank_phone` (teléfono), `user_bank_dni` (cédula) Vincula un dispositivo Android para capturar pagos vía SMS/notificaciones.

Ejemplo para Banco Plaza:

json

{
  "user_id": "USER_ID",
  "bank_provider": "VE_BANK_PLAZA_V1",
  "username": "mi_client_id",
  "password": "mi_client_secret",
  "description": "Cuenta Plaza J",
  "metadata": [
    { "key_name": "ACCOUNT_NUMBER", "key_value": "01380000000000000000" }
  ]
}

Ejemplo para Mercantil con Metadata:

json

{
  "user_id": "USER_ID",
  "bank_provider": "MERCANTIL_EMP_V1",
  "username": "CLIENT_ID_MERCANTIL",
  "password": "SECRET_KEY_MERCANTIL",
  "description": "Cuenta Mercantil J1",
  "metadata": [
    { "key_name": "INTEGRATORID", "key_value": "12345" },
    { "key_name": "TERMINAL_ID", "key_value": "TERM001" },
    { "key_name": "MERCHANT_ID", "key_value": "MERC001" }
  ]
}

Ejemplo para Banesco (J):

json

{
  "user_id": "USER_ID",
  "bank_provider": "VE_BANESCO_V1",
  "username": "MI_CLIENT_ID_BANESCO",
  "password": "MI_CLIENT_SECRET_BANESCO",
  "description": "Cuenta Banesco J",
  "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" }
  ]
}

El número de cuenta (ACCOUNT_NUMBER) debe comenzar con 0134 y tener exactamente 20 dígitos. La IP (DEVICE_IP) y la opción de fecha (SHOW_DATE_IN_MOVEMENTS) son opcionales.

Ejemplo para Binance:

json

{
  "user_id": "USER_ID",
  "bank_provider": "BINANCE_APP",
  "username": "mi_api_key_binance",
  "password": "mi_secret_key_binance",
  "description": "Cuenta Binance",
  "metadata": [
    { "key_name": "BINANCE_VALIDATION_TYPE", "key_value": "GLOBAL" }
  ]
}

Valores para BINANCE_VALIDATION_TYPE: GLOBAL (sin filtro), BY_USER (primer nombre del pagador), BY_DATE (hora UTC, ej. 012044), BY_NOTE (nota del pagador).

Ejemplo para Banco QA (Sandbox):

json

{
  "user_id": "USER_ID",
  "bank_provider": "BANK_TEST",
  "description": "Cuenta de Pruebas"
}

El banco de pruebas BANK_TEST utiliza el movement_type: "GENERIC" y puedes usar la referencia de prueba 67890 para simular una validación de pago exitosa.

Ejemplo para Notificaciones Pabilo:

json

{
  "user_id": "USER_ID",
  "bank_provider": "NOTIFICATION_ACCOUNT",
  "description": "Notificaciones Caja 1",
  "user_bank_phone": "04241234567",
  "user_bank_dni": "V12345678",
  "metadata": []
}

Activar / Desactivar una Cuenta Bancaria

Alterna el estado activo de una cuenta bancaria. Si estaba activa pasa a desactivada, y viceversa. Solo el propietario de la cuenta puede realizar esta acción (los administradores también tienen acceso).

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"

json

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

Efecto sobre verificaciones

Una cuenta bancaria desactivada no podrá procesar verificaciones de pago mientras permanezca en ese estado. Si el cliente propietario está desactivado, la cuenta también queda inaccesible independientemente de su propio estado.

Eliminar una Cuenta Bancaria

Solicita la eliminación de una cuenta bancaria. El comportamiento varía según el tipo de cuenta:

DELETE /usersbank/:userBankId/to-trash

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

Plan	Comportamiento
Plan B2B2B (Integración)	La cuenta se elimina inmediatamente sin necesitar aprobación adicional.
Plan B2B Directo (Básico / Avanzado)	La cuenta entra en un proceso de aprobación. Queda marcada como `to_trash: true` y un administrador debe aprobar la eliminación definitiva.

json

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

Cuenta en proceso de eliminación

Mientras la cuenta tenga to_trash: true y esté pendiente de aprobación, no podrá procesar nuevas verificaciones de pago. Una vez que el administrador apruebe la eliminación, la cuenta desaparece permanentemente junto con su historial.

Cuentas Bancarias API

Listar Mis Cuentas

Parámetros de consulta

Respuesta de Ejemplo

Campos Dinámicos de Verificación

¿Cómo usarlo?

Estructura de verifications_types_available

Ejemplo de uso en código

Crear una Cuenta Bancaria

Proveedores Soportados

Ejemplo para Banco Plaza:

Ejemplo para Mercantil con Metadata:

Ejemplo para Banesco (J):

Ejemplo para Binance:

Ejemplo para Banco QA (Sandbox):

Ejemplo para Notificaciones Pabilo:

Activar / Desactivar una Cuenta Bancaria

Efecto sobre verificaciones

Eliminar una Cuenta Bancaria

Cuenta en proceso de eliminación

Estructura de `verifications_types_available`