Webhooks

Outbound webhooks are the notifications PagFinance sends to your backend when a cash-out, cash-in, withdraw, or KYC event happens. You register one destination and receive all your events there.

This is the outbound direction (API to you). The inbound webhooks the platform exposes to receive callbacks from the banking and KYC providers (for example /webhooks/bank) are not part of your integration; you do not consume them.

Register a destination

POST /api/v1/partners/me/webhook-config (partner API key or HMAC) Register once the destination URL, the events you want, and any custom headers. Read it with GET and remove it with DELETE on the same path.

string

required

The single HTTPS destination that receives all of your notifications.

string[]

Subscription filter. Absent or empty receives all events. See the catalog below for valid values.

object

Extra HTTP headers sent on every delivery (for example an authorization token for your endpoint). The platform’s signature and event headers take precedence and are never overwritten.

curl -X POST https://sandbox.brlp.io/api/v1/partners/me/webhook-config \
  -H "Authorization: Bearer sk_live_<hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-backend.com/webhooks/pagfinance",
    "events": ["INTENT_COMPLETED", "CASHIN_COMPLETED", "KYC_APPROVED"],
    "headers": { "Authorization": "Bearer your-token" }
  }'

Without a registered destination, events are only persisted, not sent.

Payload envelope

Every delivery shares a common envelope. The correlation id varies by event family: intentId (cash-out and cash-in), withdrawId (BRLP withdraw), or sessionId (KYC).

{
  "event": "INTENT_COMPLETED",
  "intentId": "<cid>",
  "status": "COMPLETED",
  "timestamp": "2026-08-03T12:00:00.000Z",
  "data": { }
}

Event catalog

Cash-out (offramp), correlation key `intentId`

Event	`status`	When	`data`
`INTENT_CONFIRMED`	`PROCESSING`	Crypto received on-chain	`sender, amount, currency, confirmedAt, bankTxId?`
`INTENT_COMPLETED`	`COMPLETED`	PIX or boleto paid to the payee	`baasTransactionId, invoiceValue, invoiceCurrency, completedAt, receiptUrl?`
`INTENT_FAILED`	`FAILED`	Payout failed after exhausting retries	`reason, attempts, failedAt`

Cash-in (onramp), correlation key `intentId`

Event	`status`	When	`data`
`CASHIN_COMPLETED`	`COMPLETED`	Onramp PIX received and confirmed	See the two variants below
`CASHIN_FAILED`	`FAILED`	PIX paid, but the on-chain crypto delivery failed terminally	`correlationID, reason, failedAt, deliveryId?, asset?, chain?, tokenAmount?, destination?`

CASHIN_COMPLETED has two variants, discriminated by data.deliveryId:

Without deliveryId (legacy): crediting the crypto to the user’s wallet is your backend’s responsibility. data: correlationID, walletAddress, valueCents, transactionID, splitApplied, splitValueCents, completedAt.
With deliveryId: the platform already delivered the crypto on-chain to data.destination, nothing to credit. data: correlationID, deliveryId, onChainTxId, asset, chain, tokenAmount, destination, completedAt.

CASHIN_FAILED means the fiat was captured but no crypto was delivered. Treat it as an incident and route it to support. The expiry of a cash-in charge does not currently produce a webhook; check status with GET if needed.

BRLP withdraw (Mode B), correlation key `withdrawId`

Event	`status`	When	`data`
`WITHDRAW_COMPLETED`	`COMPLETED`	BRLP withdraw completed	`baasTransactionId, amount, fee, netAmount, completedAt`
`WITHDRAW_FAILED`	`FAILED`	BRLP withdraw failed	`reason, failedAt`

KYC, correlation key `sessionId`

Event	When
`KYC_PENDING`	Session created, awaiting documentoscopy
`KYC_IN_PROGRESS`	Documentoscopy under review
`KYC_APPROVED`	KYC approved
`KYC_REJECTED`	KYC rejected (reason in `data.rejectionReason`)
`KYC_EXPIRED`	Session expired

The KYC data carries externalUserId, type ('PF' | 'PJ'), provider, status, previousStatus, documentMasked, rejectionReason?, completedAt?.

Signature verification

Every delivery is signed. Verify the signature before trusting the payload.

X-App-Signature: sha256=<hex>
X-App-Event: INTENT_COMPLETED

The signature is HMAC-SHA256 over the raw JSON body, signed with your partner webhookSecret (delivered at onboarding and rotatable via POST /api/v1/partners/me/rotate-webhook-secret). Compute the expected value and compare with a timing-safe equal.

import { createHmac } from 'node:crypto';

const expected = 'sha256=' + createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

The signature header prefix defaults to App (X-App-Signature, X-App-Event); your instance’s exact prefix is confirmed at onboarding. Legacy partners without their own secret fall back to a global signing secret.

Delivery guarantees

Retry

3 attempts, backoff 2s / 4s / 8s, 10s timeout per attempt. Failure after retries is only logged; it does not block the business flow.

Acknowledge

Respond 2xx. Any non-2xx or timeout counts as a failure and triggers a retry.

Idempotency

Order is not guaranteed. Deduplicate by intentId, correlationID, withdrawId, or sessionId.

Get Started

Users

Partners and API Keys

Fees and revenue share

KYC

Prices

Cash-out (offramp)

Cash-in (onramp)

Receipts

Links

BRLP

Webhooks

Register a destination

Payload envelope

Event catalog

Cash-out (offramp), correlation key `intentId`

Cash-in (onramp), correlation key `intentId`

BRLP withdraw (Mode B), correlation key `withdrawId`

KYC, correlation key `sessionId`

Signature verification

Delivery guarantees

Retry

Acknowledge

Idempotency

HTTPS only

​Register a destination

​Payload envelope

​Event catalog

​Cash-out (offramp), correlation key intentId

​Cash-in (onramp), correlation key intentId

​BRLP withdraw (Mode B), correlation key withdrawId

​KYC, correlation key sessionId

​Signature verification

​Delivery guarantees

Retry

Acknowledge

Idempotency

HTTPS only

Register a destination

Payload envelope

Event catalog

Cash-out (offramp), correlation key `intentId`

Cash-in (onramp), correlation key `intentId`

BRLP withdraw (Mode B), correlation key `withdrawId`

KYC, correlation key `sessionId`

Signature verification

Delivery guarantees