Webhooks (Brasil)
Cuando un cobro o pago cambia de estado, Rivopay envía un POST a tu webhookUrl de Brasil. La URL se configura en el panel por país: la de Brasil es independiente de la de Colombia.
Headers
Sección titulada «Headers»| Header | Descripción |
|---|---|
Content-Type | application/json |
X-Webhook-Event | Nombre del evento |
User-Agent | PaymentGateway-Webhook/1.0 |
X-Webhook-Timestamp | ISO 8601 — solo si configuraste una Clave |
X-Webhook-Signature | sha256=<hex> sobre {timestamp}\n{body} — solo si configuraste una Clave |
La firma HMAC es opcional y se verifica igual que en Colombia. Ver Verificación de firma.
Reintentos: 3 intentos (inmediato, +1 s, +5 s). Responde 2xx rápido y procesa en segundo plano.
Eventos
Sección titulada «Eventos»| Evento | Cuándo |
|---|---|
payin.completed | Cobro pagado |
payin.failed | Cobro rechazado |
payin.expired | Cobro vencido sin pago (status: "FAILED", con failureReason y expiredAt) |
payout.completed | Pago acreditado |
payout.failed | Pago rechazado (failureReason, p. ej. llave inexistente); el saldo retenido vuelve |
payin.reversed / payout.reversed | Un reverso (total o parcial) de un cobro o un payout devuelto. Uno por reverso. Ver Reversos |
Payload payin.completed / payin.failed
Sección titulada «Payload payin.completed / payin.failed»{ "txId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "reference": "ORD-20261005-0000000000001", "type": "PAYIN", "status": "COMPLETED", "amount": 10000, "currency": "BRL", "feeCharged": 300, "netAmount": 9700, "e2eId": "E12345678202610051400000000001", "updatedAt": "2026-10-05T15:02:30.000Z", "debtor": { "…": "datos del pagador según la red" }, "creditor": { "…": "…" }}| Campo | Descripción |
|---|---|
reference | Tu txIdSource (cobro) o reference (pago), o null |
feeCharged / netAmount | En centavos; valen 0 si FAILED |
e2eId | Identificador end-to-end de la red Pix |
debtor / creditor | Opcionales. Solo vienen cuando el cierre llega por notificación de la red |
Payload payout.completed / payout.failed
Sección titulada «Payload payout.completed / payout.failed»Misma estructura con type: "PAYOUT": txId, reference, status, amount, currency, feeCharged, failureReason (solo en failed), e2eId, updatedAt y opcionalmente debtor / creditor.
Payload payin.reversed / payout.reversed
Sección titulada «Payload payin.reversed / payout.reversed»Se envía uno por cada reverso. txId es el de la transacción de reverso; la original va en originalTxId y sigue COMPLETED.
{ "txId": "3b6f0d2a9c8e4f1a7b5d2c9e8f1a4b6d", "type": "REVERSAL", "status": "COMPLETED", "direction": "OUT", "origin": "API", "reference": "DEV-77-1", "originalTxId": "50580a1772734a7fa094638bf7b724ce", "originalType": "PAYIN", "originalReference": "pedido-77", "originalStatus": "COMPLETED", "amount": 100, "requestedAmount": 100, "currency": "BRL", "originalAmount": 300, "totalReversedAmount": 100, "remainingAmount": 200, "partial": true, "reversalState": "PARTIAL", "reason": "customerRequest", "description": "Devolución parcial pedido 77", "failureReason": null, "e2eId": "D17028875202610061753012739ec30b", "originalE2eId": "E22896431202610061749ZQB81fe6828", "occurredAt": "2026-10-06T17:53:02.393Z", "createdAt": "2026-10-06T17:53:00.000Z", "updatedAt": "2026-10-06T17:53:03.120Z", "debtor": { "…": "…" }, "creditor": { "…": "…" }}| Campo | Descripción |
|---|---|
status | COMPLETED o FAILED (solo para reversos que pediste tú) |
direction | OUT = devolución de un cobro (sale dinero) · IN = payout devuelto (entra dinero) |
origin | API (tú), ADMIN (Rivopay) o PROVIDER (banco / red) |
reference | Tu reference del reverso, o la de la transacción original |
amount | Monto efectivamente devuelto, en centavos (lo que informa la red) |
totalReversedAmount / remainingAmount | Acumulado de reversos sobre la original y lo que queda |
partial | true si la original aún no se devolvió completa |
e2eId / originalE2eId | End-to-end del reverso (D…) y del Pix original (E…) |
occurredAt | Momento del movimiento en la red |