Dashboard

Introducción

Este documento ofrece una guía clara y estructurada para integrar y consumir los servicios de la API de SIRP.
Incluye:

  • La descripción de cada endpoint disponible.

  • Los parámetros requeridos u opcionales.

  • El formato esperado de los datos enviados y recibidos.

  • Ejemplos prácticos de solicitudes (request) y respuestas (response) en formato JSON.

Está diseñada para facilitar el trabajo de desarrolladores que desean conectar sus plataformas con los servicios de pago y consulta ofrecidos por SIRP.

Autenticación

Cada solicitud a esta API requiere una cabecera de autenticación con el nombre Hash, donde debe proporcionarse el valor en formato Bearer.

Hash Bearer

hash: Bearer [tu_hash]

Integración Con API

Transferencias

  • URL: https://api.sirppayments.com/sandbox/transferencias
  • Método: POST
  • Descripción: Consulta si la transferencia fue acreditada en la cuenta bancaria de SIRP.

Parámetros:
  • cedula: Número de identificación personal del usuario (cédula de identidad).
  • cod_banco: Código identificador del banco del remitente.
  • fecha: Fecha de la transacción en formato YYYY-MM-DD.
  • monto: Monto del pago expresado en formato decimal, con punto como separador decimal.
  • ref: Referencia de la transacción, compuesta por 8 dígitos.
  • tx_id: ID de la tx en su sistema

Ejemplo de Solicitud:
{
  "cedula": 12345678,
  "cod_banco": "0102",
  "fecha": "2025-01-13",
  "monto": "100.00",
  "ref": "12345678",
  "tx_id": "ssd85-sdsd457-sdsd"
}

Ejemplo de Respuesta exitosa
{
    "success":
    {
        "code":200,
        "message":"transferencia validada",
        "codigo":"NO35J3"
    }
}

Ejemplo de Respuesta pendiente
{
    "pending":
    {
        "code":202,
        "message":"No se encontro la transferencia.",
        "codigo":"NO35J3"
    }
}

Ejemplo de Respuesta erronea
{
    "error":
    {
        "code":201,
        "message":"Referencia ya existe",
        "codigo":"NO35J3"
    }
}

Pago Móvil

  • URL: https://api.sirppayments.com/sandbox/pago-movil
  • Método: POST
  • Descripción: Consulta si el pago móvil fue acreditado en la cuenta bancaria de SIRP.

Parámetros:
  • cedula: Número de identificación personal del usuario (cédula de identidad).
  • cod_banco: Código identificador del banco del remitente. (Opcional al usar la version v2 de Depósito)
  • telefono: Número telefónico del remitente. (Opcional al usar la version v2 de Depósito)
  • fecha: Fecha de la transacción en formato YYYY-MM-DD. (Opcional al usar la version v2 de Depósito)
  • monto: Monto del pago expresado en formato decimal, con punto como separador decimal.
  • ref: Referencia bancaria de la transacción, compuesta por 8 dígitos. (Opcional al usar la version v2 de Depósito)
  • tx_id: ID de la tx en su sistema

Ejemplo de Solicitud:
Version v1
{
  "cedula": 11306779,
  "cod_banco": "0151",
  "telefono": "04125896532",
  "fecha": "20250312",
  "monto": "325.92",
  "ref": "73531673",
  "tx_id": "ssd85-sdsd-sdsd"
}

Version v2
{
  "cedula": 11306779,
  "monto": "325.92",
  "tx_id": "ssd85-sdsd-sdsd"
}

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": "Procesado correctamente.",
        "codigo": "PYPQQ5"
    }
}

Ejemplo de Respuesta pendiente
{
    "pending":
    {
        "code":202,
        "message":"Transacción no encontrada.",
        "codigo":"NO35J3"
    }
}

Ejemplo de Respuesta erronea
{
    "error":
    {
        "code":201,
        "message":"Referencia ya existe",
        "codigo":"NO35J3"
    }
}

Retiros

  • URL: https://api.sirppayments.com/sandbox/retiros
  • Método: POST
  • Descripción: Permite procesar un retiro desde la cuenta del sistema SIRP hacia el cliente final. El retiro se realiza siempre y cuando el comercio tenga saldo disponible en su cuenta dentro de la plataforma.

Parámetros:
  • tipo_cedula: Tipo de identificación del usuario. Valores permitidos: 'V' (Venezolano), 'E' (Extranjero), 'P' (Pasaporte).
  • cedula: Número de identificación personal del usuario (cédula de identidad).
  • nombre: Nombres y apellidos del usuario registrado como titular de la cuenta de banco.
  • tipo_cuenta: Indica si el destino del pago es una cuenta bancaria (1) o un número telefónico (2).
  • cuenta: Número de cuenta bancaria o número de teléfono, dependiendo del valor indicado en 'tipo_cuenta'.
  • cod_banco: Código numérico que identifica al banco.
  • monto: Cantidad a retirar, expresada en formato decimal con punto como separador decimal.
  • descripcion: Descripción de la transacción (opcional)
  • tx_id: ID de la tx en su sistema (opcional)
  • version: Acepta v1 y v2 (Cualquier valor distinto usara por defecto v1)

Ejemplo de Solicitud:
{
  "tipo_cedula": "V",
  "cedula": 12345678,
  "nombre": "John Doe",
  "tipo_cuenta": 1,
  "cuenta": "1234567890123456",
  "cod_banco": "0102",
  "monto": "500.00",
  "descripcion": "Test withdrawal", //(opcional)
  "tx_id": "rets5-sdsd-sdsd"
}

Ejemplo de Respuesta exitosa
{
    "success":
    {
        "code":200,
        "message":". Referencia: 210339482",
        "reference":"210339482",
        "codigo":"HFAA1X"
    }
}

Depósito

  • URL: https://api.sirppayments.com/sandbox/deposito
  • Método: POST
  • Descripción: Crea una orden de pago y devuelve los datos necesarios para completar el depósito.

Parámetros:
  • moneda: Opcional solo acepta valor "USD" cualquier otro sera reemplazado por "VES"
  • monto: Cantidad a retirar, expresada en formato decimal con punto como separador decimal.
  • cedula: Número de identificación personal del usuario (cédula de identidad).
  • tx_id: ID de la tx en su sistema
  • tipo: Tipo de pago: pm para Pago Móvil, tb para Transferencia Bancaria.
  • version: Acepta v1 y v2 (Cualquier valor distinto usara por defecto v1)

Ejemplo de Solicitud:
{
    "monto": "10.00",
    "tipo": "pm", // Type: its value must be 'pm' for 'pago móvil;, 'tb' for 'Transferencia'
    "cedula": "23926767",
    "tx_id": "223344", // Your ID tx
    "version": "v1",
    "moneda":"USD" //(Oopcional)The only value available is "USD" any other will be taken as "VES"
}

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": [
            {
                "nombre": "SERVICIOS INTEGRALES RP C.A",
                "rif": "J-410468190",
                "telefono": "0414-286-56-68",
                "num_cuenta": "0171-0002-57-6003038424",
                "info_banco": "BANCO ACTIVO, C.A. BANCO UNIVERSAL (0171)",
                "codigo": "2D0C_TO",
                "monto": "32040.00" // Only for field "moneda" is "USD"
            }
        ]
    }
}

Ejemplo de Respuesta erronea
{
    "error": {
        "code": 201,
        "message": "El tipo debe ser 'pm' o 'tb'"
    }
}

{
    "error": {
        "code": 406,
        "message": "{Campo} no puede ir vacio." // example "monto no puede ir vacio"
    }
}

{
    "error": {
        "code": 201,
        "message": "Ya existe el ID {your tx id}"
    }
}

Nota:

Dependiendo del valor enviado en el campo tipo, posteriormente se deberá utilizar uno de los siguientes endpoints para procesar el pago:

El endpoint seleccionado dependerá del tipo de pago indicado en la solicitud.

La versión "v2" solo es valida para pago móvil (pm), las transferencias (tb) siempre usaran v1.

Transacciones

  • URL: https://api.sirppayments.com/sandbox/transacciones
  • Método: POST
  • Descripción: Consulta el historial de transacciones registradas en la plataforma.

Parámetros:
  • fecha_start: Fecha de inicio en formato AAAA-MM-DD H:i:s. ✅ Si no se especifica, se usa la fecha actual.
  • fecha_end: Fecha de fin en formato AAAA-MM-DD H:i:s. ✅ Si no se especifica, se usa la fecha actual.
  • page: Número de página para paginación de resultados.
  • hasta: Cantidad de resultados por página.
  • cedula: Filtro opcional por número de identificación del cliente.
  • codigo: Filtro opcional por ID de transacción en el sistema SIRP. (puede ser string o array)
  • tx_id: Filtro opcional por ID de transacción en el sistema del cliente. (puede ser string o array)

Ejemplo de Solicitud:
{
  "fecha_start": "2025-07-07 00:00:00",
  "fecha_end": "2025-07-24 23:59:59",
  "page": 1,
  "hasta": 10,
  "codigo": "HZ3TPO", //(opcional)
  "cedula":"12345678",//(opcional)
  "tx_id": "ssddet"//(opcional)
}

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": [
            {
                "tipo": "retiros",
                "referencia": "154573235",
                "dni": "12345678",
                "monto": "12.75",
                "neto": "35.00",
                "codigo": "HZ3TPO",
                "fecha": "2025-07-24 06:11:55",
                "estado": "Completado",
                "mensaje": "Retiro realizado."
            }
        ]
    }
}

Nota sobre filtros y rango de fechas:

Aunque se puedan usar los filtros opcionales codigo, cedula o tx_id para refinar la búsqueda, siempre se aplicará el filtro de rango de fechas definido por fecha_start y fecha_end.

  • Si alguno de los filtros opcionales se incluye, la consulta se limitará a los registros que cumplan con esos valores dentro del rango de fechas especificado.
  • Si no se envía el rango de fechas (fecha_start o fecha_end), por defecto se utilizará el día actual completo (desde las 00:00:00 hasta las 23:59:59) para filtrar los registros.
  • Si se envía un rango de fechas superior a 30 días, se actualizara automatico, a 30 días a partir de la decha de inicio (fecha_start ) para filtrar los registros.
  • Si (hasta ) tiene un valor superior a 50 se ajustara a 50 automaticamente.

Desencriptar Código

  • URL: https://api.sirppayments.com/sandbox/des-codigo/{code_encrypted}
  • Método: GET
  • Descripción: Recibe un código encriptado como parámetro en la URL y devuelve su valor desencriptado. El código debe pasarse en la ruta en lugar de `{code_encrypted}`.

Ejemplo de Solicitud:
GET https://api.sirppayments.com/sandbox/des-codigo/abc123encryptedcode

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": "BUS8AW"
    }
}

Obtener Cuentas SIRP

  • URL: https://api.sirppayments.com/sandbox/informacion
  • Método: GET
  • Descripción: Este endpoint permite obtener la lista de cuentas bancarias habilitadas por SirpPayment para recibir pagos.

Ejemplo de Solicitud:
GET https://api.sirppayments.com/sandbox/informacion

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": [
            {
                "nombre": "SERVICIOS INTEGRALES RP C.A",
                "rif": "J-410468190",
                "telefono": "0414-286-56-68",
                "num_cuenta": "0171-0002-57-6003038424",
                "info_banco": "BANCO ACTIVO, C.A. BANCO UNIVERSAL (0171)"
            }
        ]
    }
}

Obtener Bancos

  • URL: https://api.sirppayments.com/sandbox/bancos-v
  • Método: GET
  • Descripción: Este endpoint permite obtener la lista completa de bancos disponibles y soportados por SirpPayment para operaciones de pago o registro de cuentas.

Ejemplo de Solicitud:
GET https://api.sirppayments.com/sandbox/bancos-v

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": [
            {
                "cod_bank": "0102",
                "nombre": "Banco de Venezuela, S.A. Banco Universal"
            }
        ]
    }
}

Obtener Saldo

  • URL: https://api.sirppayments.com/sandbox/obtener-saldo
  • Método: GET
  • Descripción: Este endpoint permite consultar el saldo actual disponible en su cuenta registrada en SirpPayment.

Ejemplo de Solicitud:
GET https://api.sirppayments.com/sandbox/obtener-saldo

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": "8056.09"
    }
}

Página De Pago

Crear Orden

  • URL: https://api.sirppayments.com/sandbox/crear-orden
  • Método: POST
  • Descripción: Este endpoint crea una orden de pago y devuelve la URL donde el cliente puede completar el pago.

Parámetros:
  • monto: Monto del pago expresado en formato decimal, con punto como separador decimal.
  • url_s: URL a la que se redirige en caso de pago exitoso.
  • url_e: URL a la que se redirige en caso de error en el pago.
  • url_c: URL del comercio o sitio web que realiza la transacción.
  • tipo: Tipo de pago: pm para Pago Móvil, tb para Transferencia Bancaria.
  • cedula: Número de identificación del usuario. Opcional; si no se envía, se solicitará al usuario en la página de pago.
  • telefono: Número telefónico del usuario. Opcional; si no se envía, se solicitará al usuario en la página de pago.
  • tipo_r: usar valor (CURL) para recibir los datos de la orden por webhook, cualquier valor distinto, enviara los datos por post a la url correspondiente.
  • tx_id: ID único de la transacción en tu sistema para referencia.
  • texto: Texto personalizado para el botón que regresa al comercio. (opcional)
  • version: Acepta v1 y v2 (Cualquier valor distinto usara por defecto v1, La versión "v2" solo es valida para pago móvil (pm), las transferencias (tb) siempre usaran v1.)
  • moneda: Opcional solo acepta valor "USD" cualquier otro sera reemplazado por "VES"

Nota: Los campos cedula y telefono son opcionales. Si no se proporcionan en la solicitud, serán solicitados directamente al usuario en el formulario de la página de pago.

La versión "v2" solo es valida para pago móvil (pm), las transferencias (tb) siempre usaran v1.

Ejemplo de Solicitud:
{
    "monto":"250657.50",
    "url_s":"https://sandbox.sirppayments.com/",
    "url_e":"https://sandbox.sirppayments.com/",
    "url_c":"https://sandbox.sirppayments.com/",
    "tipo":"tb", // tb or pm
    "cedula" : 11102451,
    "telefono" : "04125894512",
    "tipo_r": "curl", //(Opcional only accepts 'curl' as a value)
    "tx_id": "asda-asdas-ads", 
    "texto":"Return to site", //(Opcional) 
    "moneda":"USD" //(Oopcional)The only value available is "USD" any other will be taken as "VES"   
}

Ejemplo de Respuesta exitosa
{
    "success": {
        "code": 200,
        "message": [
            {
                "url": "https://pay.sirppayments.com/hpps/aE1mWFRTZ3VHZFV4a3AwYTlvTFFtNE42WW1zVVJ3UGxJMm1lRWpWM0ZXQT0%3D",
                "codigo": "VXY95Q",
                "monto": "32040.00" // Only for field "moneda" is "USD"
            }
        ]
    }
}

Ejemplo de Respuesta erronea
{
    "error": {
        "code": 400,
        "message": "Es necesario el campo {nombre del campo requerido}" // example "Es necesario el campo url_s"
    }
}

{
    "error": {
        "code": 400,
        "message": "El tipo debe ser 'pm' o 'tb'"
    }
}

{
    "error": {
        "code": 400,
        "message": "Ya existe el ID {your tx id}"
    }
}

Callback Webhook

Respuesta inmediata y manejo de excepciones

Nuestros procesos están diseñados para proporcionar una respuesta inmediata tras la ejecución de una transacción, garantizando rapidez y eficiencia en la mayoría de los casos.

Sin embargo, en situaciones excepcionales, puede ser necesario que una transacción sea modificada o validada manualmente por nuestro equipo para asegurar su correcta gestión.

Además, en el caso del Host Payment Page (HPP), es posible que se requiera recibir un callback webhook para notificar el estado final de la transacción de forma automática y segura.

Esta configuración permite que tu sistema reciba actualizaciones en tiempo real y pueda actuar en consecuencia, facilitando un control más preciso y fiable de las operaciones.

Introducción Webhook

Este documento describe los pasos necesarios para configurar un webhook que permita la comunicación entre el sistema SIRP y tu sistema. Un webhook es un mecanismo que permite que una aplicación envíe datos o notificaciones a otra en tiempo real cuando ocurre un evento específico.

Requisitos Para Configurar

Antes de comenzar la configuración, asegúrate de contar con los siguientes elementos:

  • URL del webhook: Permitirá la comunicación entre SIRP y tu sistema, puede configurarse directamente desde tu perfil en el Panel de Cliente SIRP.
  • Hash: Token de autenticación (hash) proporcionado por SIRP.

Configurar URL Del Webhook En El BO

Pasos para configurar la URL del webhook:

  • 1: Inicia sesión en el Panel de Cliente SIRP con tus credenciales.
  • 2: Dirígete a la sección Configuración de Webhooks dentro de tu perfil.
  • 3: Ingresa la URL de tu sistema en el campo correspondientes .
  • 4: Si desea, recibir notificaciones webhook, a url distintas para depositos y retiros. Marque la casilla y llene los campos a su lado.
  • 5: Guarda los cambios antes de salir, le solicitara su contraseña.

Endpoints

Método POST: Transacción

Este endpoint permite que el sistema SIRP envíe información actualizada sobre una transacción, ya sea por algún cambio o validación manual realizada por nuestra parte.

  • URL: {you_url_webhook?ruta=transaccion}
  • Método: POST

Parámetros
  • usuario: ID único del usuario que realizó o está asociado a la transacción. (opcional))
  • tx_id: Identificador único de la transacción dentro del sistema. (opcional)
  • cedula: Número de identificación personal del usuario (cédula de identidad).
  • monto: Monto del pago expresado en formato decimal, con punto como separador decimal.
  • fecha: Fecha y hora exacta en que se registró la transacción.
  • tipo: Tipo de operación, por ejemplo: Depósito, Retiro.
  • codigo: Código único asociado a la transacción en SIRP
  • estado: Estado actual de la transacción, como Completado, Fallido
  • mensaje: Mensaje descriptivo sobre el estado o resultado de la transacción.
  • accion: Tipo de evento relacionado a la transacción. new o update.

Ejemplo de Solicitud:
Header: hash: Bearer [tu_hash]
Method POST: {you_url_webhook?ruta=transaccion}
Body:
{
  "usuario": "123456789",//(opcional You must indicate this if you wish to receive it.)
  "tx_id": "0197d355-ssdw1-7111-bbdd-8ae9511f2720",//(opcional only if you send it when creating the tx)
  "cedula": "95346565",
  "monto": "200.00",
  "fecha": "2025-07-11 19:52:00",
  "tipo": "Depósito",
  "codigo": "J1hEG9",
  "estado": "Completado",
  "mensaje": "J1hEG9 Transacción encontrada.",
  "accion": "new"
}

Recomendaciones De Seguridad

  • Validación del Hash: Antes de procesar cualquier solicitud, asegúrate de verificar que el token Hashrecibido desde SIRP sea válido. Esta validación es fundamental para evitar accesos no autorizados y garantizar que las peticiones provengan exclusivamente del sistema de SIRP.
  • Uso de HTTPS: Es altamente recomendable que tu webhook esté implementado bajo el protocolo HTTPS. Esto asegura que los datos transmitidos entre SIRP y tu servidor estén cifrados y protegidos contra interceptaciones o manipulaciones.
  • Registro y Monitoreo: Implementa un sistema de registro (log) que almacene tanto las solicitudes recibidas como las respuestas generadas. Esto te permitirá detectar fallos, facilitar la depuración y llevar un control de las transacciones procesadas.