Pay Alert para Desarrolladores

Node.js

const crypto = require('crypto')

function verifySignature(secret, body, signature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// Express / Fastify — leer el body como string crudo
app.post('/webhook/pay-alert', (req, res) => {
  const sig = req.headers['x-pay-alert-signature']
  const rawBody = req.rawBody // bodyParser con { verify } o similar

  if (!verifySignature(process.env.WEBHOOK_SECRET, rawBody, sig)) {
    return res.status(401).send('Firma inválida')
  }

  const event = JSON.parse(rawBody)
  console.log('Evento recibido:', event.event, event.data)

  res.sendStatus(200)
})

Python

import hmac
import hashlib

def verify_signature(secret: str, body: bytes, signature: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook/pay-alert', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Pay-Alert-Signature', '')
    raw_body = request.get_data()

    if not verify_signature(os.environ['WEBHOOK_SECRET'], raw_body, sig):
        return 'Firma inválida', 401

    event = request.get_json()
    print('Evento:', event['event'], event['data'])

    return '', 200

PHP

<?php
function verifySignature(string $secret, string $body, string $signature): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
    return hash_equals($expected, $signature);
}

$secret = getenv('WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAY_ALERT_SIGNATURE'] ?? '';

if (!verifySignature($secret, $rawBody, $signature)) {
    http_response_code(401);
    exit('Firma inválida');
}

$event = json_decode($rawBody, true);
error_log('Evento: ' . $event['event']);

http_response_code(200);

Crea un webhook. Devuelve el secret solo en la creación — guardalo de forma segura.

curl -X POST https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/webhooks \
  -H "Authorization: Bearer <tu-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhook/pay-alert",
    "events": ["payment.approved", "payment.refunded"],
    "isActive": true
  }'

Lista todos los webhooks del comercio (sin el secret).

curl https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/webhooks \
  -H "Authorization: Bearer <tu-access-token>"

Envía un evento de prueba payment.approved a la URL configurada. Útil para verificar que tu endpoint responde correctamente.

curl -X POST https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/webhooks/{webhookId}/test \
  -H "Authorization: Bearer <tu-access-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Actualiza url, events, isActive. Con regenerateSecret: true rota el secret y devuelve el nuevo valor.

curl -X PUT https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/webhooks/{webhookId} \
  -H "Authorization: Bearer <tu-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "regenerateSecret": true }'

Crea una API key. Devuelve key (formato pa_live_...) solo en este response.

curl -X POST https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/api-keys \
  -H "Authorization: Bearer <tu-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integración ERP",
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

Lista las keys activas del comercio (sin el valor crudo).

curl https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/api-keys \
  -H "Authorization: Bearer <tu-access-token>"

Revoca una key de forma inmediata para nuevos requests. Por caché, una key ya revocada puede seguir aceptándose hasta 5 minutos.

curl -X DELETE https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/api-keys/{keyId} \
  -H "Authorization: Bearer <tu-access-token>"

Crea un pago esperado. externalReference es tu propio identificador (ej: número de factura) y es de un solo uso por comercio — no se puede reutilizar aunque el pago original haya expirado o se haya cancelado. expiresAt es opcional.

curl -X POST https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/expected-payments \
  -H "Authorization: Bearer pa_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "factura-4521",
    "amount": 15000,
    "expiresAt": "2026-07-25T00:00:00.000Z"
  }'

Consulta el estado. Si pasó expiresAt sin match, el estado se resuelve a EXPIRED automáticamente. Cuando el estado es MATCHED, incluye el pago vinculado en data.payment.

curl https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/expected-payments/factura-4521 \
  -H "Authorization: Bearer pa_live_..."

{
  "data": {
    "id": "cmpz1a2b30001y5abcd12345",
    "externalReference": "factura-4521",
    "amount": "15000.00",
    "status": "MATCHED",
    "expiresAt": "2026-07-25T00:00:00.000Z",
    "createdAt": "2026-07-20T18:04:11.000Z",
    "payment": {
      "id": "cmpx9k2ab0001y5wnabc12345",
      "mpPaymentId": "123456789",
      "amount": "15000.00",
      "currency": "ARS",
      "status": "APPROVED",
      "description": "Producto XYZ",
      "payerEmail": null,
      "payerName": "Juan García",
      "paymentMethod": "account_money",
      "paidAt": "2026-07-20T18:05:02.000Z",
      "receivedAt": "2026-07-20T18:05:03.000Z"
    }
  }
}

Cancela un pago esperado. Solo funciona mientras sigue PENDING — si ya fue matcheado, expiró, o ya está cancelado, devuelve error.

curl -X DELETE https://pay-alert-api.onrender.com/api/v1/businesses/{businessId}/expected-payments/factura-4521 \
  -H "Authorization: Bearer pa_live_..."