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.
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.
Implementa un endpoint HTTP en tu servidor que acepte solicitudes POST. Este endpoint recibirá los datos del pago en formato JSON.
Ingresa a tu cuenta de BiPe Alerta, ve a "Configuración" > "Webhooks" y registra la URL de tu endpoint.
Programa tu endpoint para procesar las notificaciones recibidas y actualizar tu sistema según sea necesario.
Cuando ocurre un pago, BiPe Alerta enviará una solicitud POST a tu endpoint con un objeto JSON con la siguiente estructura:
{ "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á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. |
| 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 |
Los endpoints de integración requieren un token de API asociado a tu negocio. Cada token identifica al negocio y permite consultar sus transacciones.
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").
El token se muestra una sola vez al crearlo. Guárdalo en un lugar seguro inmediatamente. No volverá a mostrarse.
Incluye el token en el header de tus solicitudes HTTP.
Formato del token:
ya_bp_Ev6v1NplEWBd2rAIsKBSA4927c2NsVO4MN1ey4whowk
Usa el header Authorization con el esquema Bearer:
Authorization: Bearer ***
O alternativamente, usando el header X-API-Key:
X-API-Key: ***
Consulta las transacciones registradas en tu negocio filtradas por rango de fechas.
GET /api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07 Host: apialert.c-centralizador.com Authorization: Bearer ***
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| fechaInicial | string | Sí | Fecha de inicio (YYYY-MM-DD) |
| fechaFinal | string | Sí | Fecha de fin (YYYY-MM-DD) |
curl -H "Authorization: Bearer ***" \ "https://apialert.c-centralizador.com/api/integration/yapes?fechaInicial=2026-07-01&fechaFinal=2026-07-07"
{ "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ó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 |
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.
Cuando el cliente elige "Pagar con Yape", tu backend llama a POST /api/integration/intenciones con el id del pedido y el monto.
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 paga exactamente ese monto antes de que expire la intención (15 minutos por defecto).
La intención pasa a PAGADO en segundos. Te enteras por tu webhook (campo IntencionPago) o consultando GET /api/integration/intenciones/{referencia}.
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.
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ámetro | Tipo | Requerido | Descripció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). |
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).
{ "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 } }
Ú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.
curl -H "Authorization: Bearer ***" \ "https://apialert.c-centralizador.com/api/integration/intenciones/PED-1002"
{ "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" } } }
| Estado | Significado | Qué 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. |
Si el cliente abandona el checkout o cambia el carrito, cancela la intención para liberar el monto. Si ya fue pagada, responde 409.
curl -X POST -H "Authorization: Bearer ***" \ "https://apialert.c-centralizador.com/api/integration/intenciones/PED-1002/cancelar"
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.
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);
});
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);
}
| Código | Significado |
|---|---|
| 200 | Consulta correcta, o la intención ya existía para esa referencia. |
| 201 | Intención creada. |
| 400 | Datos inválidos (monto, referencia, descripción). |
| 401 | Token no enviado, inválido o revocado. |
| 403 | El negocio del token no tiene el plan Enterprise. |
| 404 | No existe una intención con esa referencia. |
| 409 | Ya 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. |
| 429 | Superaste 300 solicitudes por minuto. Espera y reintenta. |
Endpoint público para verificar que la API de integración está operativa. No requiere autenticación.
curl https://apialert.c-centralizador.com/api/integration/health
Respuesta:
{ "status": "ok", "timestamp": "2026-07-07T07:30:00Z", "service": "yapealerta-integration" }
// 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. } }
// 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}`); });
# 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)
Para asegurar que solo BiPe Alerta pueda enviar notificaciones a tu webhook, te recomendamos implementar las siguientes medidas de seguridad: