Documentación

API de Integración BiPe Alerta

Conecta tu sistema con BiPe Alerta mediante nuestra API REST y webhooks. Consulta transacciones, recibe notificaciones en tiempo real, cobra con Yape en tu ecommerce y automatiza tus procesos.

Introducción a Webhooks

Fundamentos

¿Qué son los Webhooks?

Los webhooks son una forma de recibir notificaciones automáticas cuando ocurren eventos en BiPe Alerta. En lugar de consultar constantemente nuestra API para verificar nuevos pagos, puedes configurar un webhook para que nuestro sistema envíe automáticamente la información a tu servidor cuando ocurra un nuevo pago.

Nota importante
Para utilizar webhooks, necesitas contar con un endpoint HTTP accesible públicamente en tu servidor que pueda recibir solicitudes POST.

Implementación de Webhooks

Guía paso a paso

Configuración de tu Webhook

Crea un endpoint

Implementa un endpoint HTTP en tu servidor que acepte solicitudes POST. Este endpoint recibirá los datos del pago en formato JSON.

Configura la URL en BiPe Alerta

Ingresa a tu cuenta de BiPe Alerta, ve a "Configuración" > "Webhooks" y registra la URL de tu endpoint.

Procesa las notificaciones

Programa tu endpoint para procesar las notificaciones recibidas y actualizar tu sistema según sea necesario.

Estructura del Webhook

Referencia técnica

Formato JSON

Cuando ocurre un pago, BiPe Alerta enviará una solicitud POST a tu endpoint con un objeto JSON con la siguiente estructura:

YapeWebHook.json
{
                    "Id": 123,
                    "IdUsuarioNegocio": 456,
                    "Tipo": "Yape",
                    "NombreCliente": "Juan Pérez",
                    "Monto": 25.50,
                    "Estado": "Completado",
                    "FechaHora": "2025-03-18T15:30:45",
                    "IdBilletera": 789,
                    "PackageName": "com.yape.app",
                    "CodigoSeguridad": "992",
                    "IntencionPago": {
                        "IdIntencion": 9,
                        "Referencia": "PED-1002",
                        "Estado": "PAGADO",
                        "MontoSolicitado": 25.00,
                        "MontoAPagar": 24.99,
                        "FechaPago": "2025-03-18T15:30:47"
                    }
}

Parámetros del Webhook

Parámetro Tipo Descripción
Id integer Identificador único de la notificación
IdUsuarioNegocio integer ID del usuario del negocio en BiPe
Tipo string Tipo de transacción (Yape, Plin, etc.)
NombreCliente string Nombre del cliente que realizó el pago
Monto decimal Monto de la transacción
Estado string Estado de la transacción
FechaHora DateTime Fecha y hora de la transacción
IdBilletera integer ID de la billetera asociada
PackageName string? Nombre del paquete de la aplicación (opcional)
CodigoSeguridad string? Código de seguridad de la notificación (ej. Yape: "El cód. de seguridad es: 992"). Es null si la billetera o el pago no lo traen.
IntencionPago object? Pedido que pagó este Yape (ver Intención de pago). Es null si el Yape no corresponde a ninguna intención.

API REST de Integración

Nuevo

Endpoints disponibles

Método Endpoint Descripción Autenticación
GET /api/integration/yapes Obtener transacciones por rango de fechas Token API
POST /api/integration/intenciones Crear una intención de pago para un pedido (cobro automático) Token API
GET /api/integration/intenciones/{referencia} Consultar si el pedido ya fue pagado Token API
POST /api/integration/intenciones/{referencia}/cancelar Cancelar una intención pendiente Token API
GET /api/integration/health Verificar estado del servicio Público
POST Webhook configurado Notificación de nueva transacción Configuración

Autenticación con Tokens de API

Seguridad

Tokens de API

Los endpoints de integración requieren un token de API asociado a tu negocio. Cada token identifica al negocio y permite consultar sus transacciones.

Plan Enterprise
La API de integración (consultas, intenciones de pago) y el WebHook están disponibles solo en el plan Enterprise. Si el negocio del token tiene otro plan, la API responde 403. Un cambio de plan se refleja en la API en unos minutos.

Genera un token

Desde tu Dashboard en Tokens API → Nuevo Token, crea un token con una descripción que identifique su uso (ej: "Token para integración con Bipe").

Copia el token

El token se muestra una sola vez al crearlo. Guárdalo en un lugar seguro inmediatamente. No volverá a mostrarse.

Usa el token en tus solicitudes

Incluye el token en el header de tus solicitudes HTTP.

Formato del token:

Ejemplo de token
ya_bp_Ev6v1NplEWBd2rAIsKBSA4927c2NsVO4MN1ey4whowk

Cómo enviar el token

Usa el header Authorization con el esquema Bearer:

Header HTTP
Authorization: Bearer ***

O alternativamente, usando el header X-API-Key:

Header alternativo
X-API-Key: ***
Seguridad de tokens
Los tokens se almacenan con hash SHA-256. Si un token se ve comprometido, revócalo inmediatamente desde el Dashboard. Los tokens revocados no se pueden reactivar.

Consultar Transacciones

GET

Obtener Yapes por fecha

Consulta las transacciones registradas en tu negocio filtradas por rango de fechas.

Request
GET /api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07
Host: apialert.c-centralizador.com
Authorization: Bearer ***

Parámetros

Parámetro Tipo Requerido Descripción
fechaInicial string Sí Fecha de inicio (YYYY-MM-DD)
fechaFinal string Sí Fecha de fin (YYYY-MM-DD)

Ejemplo cURL

Terminal
curl -H "Authorization: Bearer ***" \
  "https://apialert.c-centralizador.com/api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07"

Respuesta

200 OK
{
                    "status": true,
                    "message": "Yapes obtenidos correctamente",
                    "response": [
                        {
                        "idYape": 12345,
                        "nombreUsuarioNegocio": "Juan Perez",
                        "nombreCliente": "Maria Lopez",
                        "monto": 150.00,
                        "fechaHora": "2026-07-05T14:30:00",
                        "repetido": false,
                        "tipo": "Yape",
                        "nombreLocal": "Local Principal",
                        "nombreTrabajador": "Carlos",
                        "codigoSeguridad": "992"
                    }
                    ]
}

Códigos de error

Código Significado
200 Operación exitosa
400 Solicitud inválida (parámetros incorrectos)
401 Token no proporcionado, inválido o revocado
403 El negocio del token no tiene el plan Enterprise
500 Error interno del servidor

Cobrar con Yape en tu ecommerce

Recomendado

¿Cómo funciona la intención de pago?

Antes de que tu cliente yapee, le avisas a BiPe qué monto esperas para el pedido. Cuando llega el Yape al celular del negocio, BiPe lo empareja solo con el pedido y te avisa. Tu cliente no tiene que escribir ni subir nada.

Crea la intención

Cuando el cliente elige "Pagar con Yape", tu backend llama a POST /api/integration/intenciones con el id del pedido y el monto.

Muestra el monto exacto

BiPe te responde el montoAPagar (ej. S/ 24.99). Muéstralo destacado junto a tu número o QR de Yape y el tiempo restante.

El cliente yapea

El cliente paga exactamente ese monto antes de que expire la intención (15 minutos por defecto).

BiPe confirma el pago

La intención pasa a PAGADO en segundos. Te enteras por tu webhook (campo IntencionPago) o consultando GET /api/integration/intenciones/{referencia}.

¿Qué es el monto único?
Si dos clientes pagan S/ 25.00 al mismo tiempo, no se podría saber cuál pago es de cada pedido. Por eso, con montoUnico: true (por defecto) BiPe resta unos céntimos para que no haya dos pedidos pendientes con el mismo monto: el primero paga S/ 25.00, el siguiente S/ 24.99, luego S/ 24.98... El cliente nunca paga de más; como máximo el negocio deja de cobrar unos céntimos. Si lo desactivas (montoUnico: false) el cliente paga el monto exacto del pedido, pero si hay varios pedidos pendientes con el mismo monto, BiPe asigna el pago al más antiguo.
POST

Crear intención de pago

Terminal
curl -X POST "https://apialert.c-centralizador.com/api/integration/intenciones" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{ "referencia": "PED-1002", "monto": 25.00, "expiraEnMinutos": 15, "montoUnico": true, "descripcion": "Polo negro talla M" }'

Parámetros

ParámetroTipoRequeridoDescripción
referencia string Sí Id del pedido en tu sistema (máx. 100 caracteres). Solo puede haber una intención pendiente o pagada por referencia.
monto decimal Sí Monto del pedido en soles, mayor a 0 y con máximo 2 decimales.
expiraEnMinutos integer No Minutos que se espera el pago, de 1 a 60. Por defecto 15.
montoUnico boolean No Por defecto true. Ajusta los céntimos para que el monto identifique al pedido.
descripcion string No Texto libre para tu control (máx. 200 caracteres).

Respuesta

Devuelve 201 al crearla. Si repites la llamada con la misma referencia, devuelve 200 con la misma intención (puedes reintentar sin miedo a duplicar).

201 Created
{
    "status": true,
    "message": "Intención de pago creada",
    "response": {
        "idIntencion": 9,
        "referencia": "PED-1002",
        "estado": "PENDIENTE",
        "montoSolicitado": 25.00,
        "montoAPagar": 24.99,
        "montoUnico": true,
        "descripcion": "Polo negro talla M",
        "fechaCreacion": "2026-11-09T15:00:00",
        "fechaExpiracion": "2026-11-09T15:15:00",
        "segundosRestantes": 900,
        "fechaPago": null,
        "pago": null
    }
}
Importante
Muestra al cliente montoAPagar, no el monto del pedido. Si el cliente paga otro monto (por ejemplo redondea a S/ 25.00), el pago no se emparejará. Las fechas están en hora de Perú (UTC-5).
GET

Consultar el estado del pedido

Úsalo si no tienes webhook, o para confirmar antes de despachar. Desde la pantalla de pago puedes consultarlo cada 3 a 5 segundos hasta que deje de estar PENDIENTE.

Terminal
curl -H "Authorization: Bearer ***" \
  "https://apialert.c-centralizador.com/api/integration/intenciones/PED-1002"
200 OK (pagado)
{
    "status": true,
    "message": "Intención de pago obtenida",
    "response": {
        "idIntencion": 9,
        "referencia": "PED-1002",
        "estado": "PAGADO",
        "montoSolicitado": 25.00,
        "montoAPagar": 24.99,
        "segundosRestantes": 0,
        "fechaPago": "2026-11-09T15:03:12",
        "pago": {
            "idYape": 12345,
            "monto": 24.99,
            "fechaHora": "2026-11-09T15:03:05",
            "nombreCliente": "Juan Perez",
            "codigoSeguridad": "992"
        }
    }
}

Estados

EstadoSignificadoQué hacer
PENDIENTE Esperando el Yape del cliente. Seguir mostrando el monto y el tiempo restante.
PAGADO Llegó un Yape por el monto exacto y quedó amarrado a este pedido. Un mismo Yape nunca paga dos pedidos. Confirmar el pedido.
EXPIRADO Pasó el tiempo sin recibir el pago. Se aceptan Yapes que llegan hasta 2 minutos tarde; después el estado es definitivo. Puedes crear una nueva intención con la misma referencia.
CANCELADO Cancelaste la intención. Puedes crear una nueva intención con la misma referencia.
POST

Cancelar una intención

Si el cliente abandona el checkout o cambia el carrito, cancela la intención para liberar el monto. Si ya fue pagada, responde 409.

Terminal
curl -X POST -H "Authorization: Bearer ***" \
  "https://apialert.c-centralizador.com/api/integration/intenciones/PED-1002/cancelar"
Código ejemplo

Pantalla de pago

Flujo típico: tu backend crea la intención (el token nunca debe ir en el navegador) y la página consulta el estado a través de tu backend.

Backend (Node.js)
Página de pago (JS)
server.js
const BIPE = 'https://apialert.c-centralizador.com/api/integration';
const headers = {
  'Authorization': `Bearer ${process.env.BIPE_TOKEN}`,
  'Content-Type': 'application/json'
};

// 1. El cliente eligió "Pagar con Yape"
app.post('/checkout/:pedidoId/yape', async (req, res) => {
  const pedido = await Pedidos.buscar(req.params.pedidoId);
  const r = await fetch(`${BIPE}/intenciones`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ referencia: pedido.id, monto: pedido.total, expiraEnMinutos: 15 })
  });
  const { response } = await r.json();
  res.json({
    montoAPagar: response.montoAPagar,
    segundosRestantes: response.segundosRestantes
  });
});

// 2. La página pregunta si ya se pagó
app.get('/checkout/:pedidoId/yape/estado', async (req, res) => {
  const r = await fetch(`${BIPE}/intenciones/${encodeURIComponent(req.params.pedidoId)}`, { headers });
  const { response } = await r.json();
  if (response.estado === 'PAGADO') await Pedidos.marcarPagado(req.params.pedidoId, response.pago.idYape);
  res.json({ estado: response.estado, segundosRestantes: response.segundosRestantes });
});

// 3. (Opcional) Webhook: BiPe avisa apenas llega el Yape
app.post('/webhook/bipe', async (req, res) => {
  const { IntencionPago } = req.body;
  if (IntencionPago?.Estado === 'PAGADO') {
    await Pedidos.marcarPagado(IntencionPago.Referencia, req.body.Id);
  }
  res.sendStatus(200);
});
pago-yape.js
async function pagarConYape(pedidoId) {
  const r = await fetch(`/checkout/${pedidoId}/yape`, { method: 'POST' });
  const { montoAPagar } = await r.json();

  document.querySelector('#monto').textContent = `Yapea exactamente S/ ${montoAPagar.toFixed(2)}`;

  const timer = setInterval(async () => {
    const e = await (await fetch(`/checkout/${pedidoId}/yape/estado`)).json();
    if (e.estado === 'PAGADO') {
      clearInterval(timer);
      location.href = `/pedido/${pedidoId}/gracias`;
    } else if (e.estado !== 'PENDIENTE') {
      clearInterval(timer);
      mostrarMensaje('El tiempo para pagar terminó. Vuelve a intentarlo.');
    }
  }, 4000);
}
Errores

Códigos de respuesta

CódigoSignificado
200Consulta correcta, o la intención ya existía para esa referencia.
201Intención creada.
400Datos inválidos (monto, referencia, descripción).
401Token no enviado, inválido o revocado.
403El negocio del token no tiene el plan Enterprise.
404No existe una intención con esa referencia.
409Ya hay una intención pendiente para esa referencia con otro monto, la intención ya fue pagada (al cancelar) o hay demasiados pedidos pendientes con montos parecidos.
429Superaste 300 solicitudes por minuto. Espera y reintenta.

Health Check

GET

Estado del servicio

Endpoint público para verificar que la API de integración está operativa. No requiere autenticación.

Terminal
curl https://apialert.c-centralizador.com/api/integration/health

Respuesta:

200 OK
{
                    "status": "ok",
                    "timestamp": "2026-07-07T07:30:00Z",
                    "service": "yapealerta-integration"
}

Ejemplos de Implementación

Código ejemplo

Receptor de Webhook

C# / .NET
Node.js
Python
YapeWebhookController.cs
// Controlador ASP.NET para recibir webhooks
[ApiController]
[Route("api/webhooks")]
public class YapeWebhookController : ControllerBase
{
                        private readonly ILogger _logger;
    
                        public YapeWebhookController(ILogger logger)
                        {
        _logger = logger;
                        }
    
                        [HttpPost("yape")]
                        public async Task ReceiveYapeWebhook([FromBody] YapeWebHook webhook)
                        {
                        // Registra la notificación recibida
        _logger.LogInformation($"Webhook recibido: Pago {webhook.Tipo} de {webhook.NombreCliente} por S/{webhook.Monto}");
        
                        // Procesa la notificación según tus necesidades
                        await ProcessPaymentNotification(webhook);
        
                        // Responde con éxito
                        return Ok(new { success = true });
                        }
    
                        private async Task ProcessPaymentNotification(YapeWebHook webhook)
                        {
                        // Implementa tu lógica para procesar el pago
        // Por ejemplo: actualizar base de datos, enviar notificaciones, etc.
                        }
}
yapeWebhookHandler.js
// Servidor Express para recibir webhooks de BiPe Alerta
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const PORT = process.env.PORT || 3000;

// Middleware para analizar JSON
app.use(bodyParser.json());

// Endpoint para recibir webhooks de Yape
app.post('/api/webhooks/yape', async (req, res) => {
                        try {
                        const webhook = req.body;
    
                        // Registra la recepción del webhook
    console.log(`Webhook recibido: Pago ${webhook.Tipo} de ${webhook.NombreCliente} por S/${webhook.Monto}`);
    
                        // Procesa la notificación
                        await processPaymentNotification(webhook);
    
                        // Responde con éxito
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Error al procesar el webhook:', error);
    res.status(500).json({ 
      success: false, 
      error: 'Error al procesar la notificación' 
    });
  }
});

// Función para procesar las notificaciones de pago
async function processPaymentNotification(webhook) {
                        // Aquí va tu lógica para procesar el pago
  // Por ejemplo:
  // - Actualizar el estado de un pedido en la base de datos
  // - Enviar una notificación al cliente o vendedor
  // - Generar un comprobante o factura
  // - etc.
  
                        // Ejemplo: Verificar estado del pago
                        if (webhook.Estado === "Completado") {
                        // Actualiza el estado del pedido o inventario
  }
}

// Iniciar el servidor
app.listen(PORT, () => {
  console.log(`Servidor de webhooks escuchando en el puerto ${PORT}`);
});
yape_webhook_handler.py
# Servidor Flask para recibir webhooks de BiPe Alerta
from flask import Flask, request, jsonify
import logging
from datetime import datetime

# Configuración de logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger('bipe-webhook')

app = Flask(__name__)

# Endpoint para recibir webhooks de Yape
@app.route('/api/webhooks/yape', methods=['POST'])
def yape_webhook():
                        # Obtener el JSON recibido
    webhook_data = request.json
    
                        # Registrar la notificación recibida
    logger.info(
                        f"Webhook recibido: Pago {webhook_data.get('Tipo')} de"
                        f" {webhook_data.get('NombreCliente')} por S/{webhook_data.get('Monto')}"
    )
    
                        # Procesar la notificación
    process_payment_notification(webhook_data)
    
                        # Responder con éxito
                        return jsonify({"success": True})

def process_payment_notification(webhook_data):
                        # Extraer información relevante
    payment_id = webhook_data.get('Id')
    client_name = webhook_data.get('NombreCliente')
    amount = webhook_data.get('Monto')
    payment_type = webhook_data.get('Tipo')
    payment_status = webhook_data.get('Estado')
    
                        # Convertir la fecha y hora
                        try:
        payment_datetime = datetime.fromisoformat(webhook_data.get('FechaHora').replace('Z', '+00:00'))
                        except ValueError:
        payment_datetime = datetime.now()  # Valor predeterminado si hay error de formato
    
                        # Implementa tu lógica de negocio aquí
    # Por ejemplo:
    # - Actualizar estado de pedidos en la base de datos
    # - Enviar confirmaciones por correo electrónico
    # - Actualizar inventario
    # - etc.
    
                        # Ejemplo de lógica básica
                        if payment_status == "Completado":
        logger.info(f"Procesando pago completado #{payment_id} de {client_name}")
                        # Aquí actualizarías tu base de datos o sistema

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

Consideraciones de Seguridad

Seguridad

Protección de tu Endpoint

Para asegurar que solo BiPe Alerta pueda enviar notificaciones a tu webhook, te recomendamos implementar las siguientes medidas de seguridad:

  • Usa HTTPS para tu endpoint
  • Verifica la autenticidad de las solicitudes mediante headers de autenticación
  • Implementa validación de IPs conocidas
  • Registra todas las solicitudes para detectar posibles abusos
Consejo de seguridad
Puedes utilizar los tokens de API para autenticar llamadas entrantes a tu webhook verificando que provienen de fuentes autorizadas.