Webhooks

Os webhooks de saída são as notificações que a PagFinance envia ao seu backend quando ocorre um evento de cash-out, cash-in, saque ou KYC. Você registra um destino e recebe todos os seus eventos ali.

Este é o sentido de saída (API para você). Os webhooks de entrada que a plataforma expõe para receber callbacks dos provedores bancário e de KYC (por exemplo /webhooks/bank) não fazem parte da sua integração; você não os consome.

Registrar um destino

POST /api/v1/partners/me/webhook-config (API key do parceiro ou HMAC) Registre uma vez a URL de destino, os eventos que você quer e quaisquer cabeçalhos customizados. Leia com GET e remova com DELETE no mesmo path.

string

obrigatório

O único destino HTTPS que recebe todas as suas notificações.

string[]

Filtro de assinatura. Ausente ou vazio recebe todos os eventos. Veja o catálogo abaixo para os valores válidos.

object

Cabeçalhos HTTP extras enviados em cada entrega (por exemplo um token de autorização para o seu endpoint). Os cabeçalhos de assinatura e de evento da plataforma têm precedência e nunca são sobrescritos.

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" }
  }'

Sem um destino registrado, os eventos são apenas persistidos, não enviados.

Envelope do payload

Toda entrega compartilha um envelope comum. O id de correlação varia por família de evento: intentId (cash-out e cash-in), withdrawId (saque BRLP) ou sessionId (KYC).

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

Catálogo de eventos

Cash-out (offramp), chave de correlação `intentId`

Evento	`status`	Quando	`data`
`INTENT_CONFIRMED`	`PROCESSING`	Cripto recebida on-chain	`sender, amount, currency, confirmedAt, bankTxId?`
`INTENT_COMPLETED`	`COMPLETED`	PIX ou boleto pago ao beneficiário	`baasTransactionId, invoiceValue, invoiceCurrency, completedAt, receiptUrl?`
`INTENT_FAILED`	`FAILED`	Pagamento falhou após esgotar os retries	`reason, attempts, failedAt`

Cash-in (onramp), chave de correlação `intentId`

Evento	`status`	Quando	`data`
`CASHIN_COMPLETED`	`COMPLETED`	PIX de onramp recebido e confirmado	Veja as duas variantes abaixo
`CASHIN_FAILED`	`FAILED`	PIX pago, mas a entrega de cripto on-chain falhou de forma terminal	`correlationID, reason, failedAt, deliveryId?, asset?, chain?, tokenAmount?, destination?`

CASHIN_COMPLETED tem duas variantes, discriminadas por data.deliveryId:

Sem deliveryId (legado): creditar a cripto na carteira do usuário é responsabilidade do seu backend. data: correlationID, walletAddress, valueCents, transactionID, splitApplied, splitValueCents, completedAt.
Com deliveryId: a plataforma já entregou a cripto on-chain em data.destination, nada a creditar. data: correlationID, deliveryId, onChainTxId, asset, chain, tokenAmount, destination, completedAt.

CASHIN_FAILED significa que o fiduciário foi capturado mas nenhuma cripto foi entregue. Trate como um incidente e encaminhe ao suporte. A expiração de uma cobrança de cash-in atualmente não produz webhook; consulte o status com GET se necessário.

Saque BRLP (Modo B), chave de correlação `withdrawId`

Evento	`status`	Quando	`data`
`WITHDRAW_COMPLETED`	`COMPLETED`	Saque BRLP concluído	`baasTransactionId, amount, fee, netAmount, completedAt`
`WITHDRAW_FAILED`	`FAILED`	Saque BRLP falhou	`reason, failedAt`

KYC, chave de correlação `sessionId`

Evento	Quando
`KYC_PENDING`	Sessão criada, aguardando documentoscopia
`KYC_IN_PROGRESS`	Documentoscopia em análise
`KYC_APPROVED`	KYC aprovado
`KYC_REJECTED`	KYC rejeitado (motivo em `data.rejectionReason`)
`KYC_EXPIRED`	Sessão expirada

O data do KYC carrega externalUserId, type ('PF' | 'PJ'), provider, status, previousStatus, documentMasked, rejectionReason?, completedAt?.

Verificação de assinatura

Toda entrega é assinada. Verifique a assinatura antes de confiar no payload.

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

A assinatura é HMAC-SHA256 sobre o corpo JSON cru, assinada com o seu webhookSecret de parceiro (entregue no onboarding e rotacionável via POST /api/v1/partners/me/rotate-webhook-secret). Calcule o valor esperado e compare com um 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));

O prefixo do cabeçalho de assinatura tem App como padrão (X-App-Signature, X-App-Event); o prefixo exato da sua instância é confirmado no onboarding. Parceiros legados sem segredo próprio recorrem a um segredo de assinatura global.

Garantias de entrega

Retry

3 tentativas, backoff 2s / 4s / 8s, timeout de 10s por tentativa. Falha após os retries é apenas registrada; não bloqueia o fluxo de negócio.

Confirmação

Responda 2xx. Qualquer não-2xx ou timeout conta como falha e dispara um retry.

Idempotência

A ordem não é garantida. Deduplique por intentId, correlationID, withdrawId ou sessionId.

Somente HTTPS

Registre apenas um destino HTTPS.

Comece Aqui

Usuários

Parceiros e API Keys

Taxas e repasse

KYC

Preços

Cash-out (offramp)

Cash-in (onramp)

Recibos

Links

BRLP

Webhooks

Registrar um destino

Envelope do payload

Catálogo de eventos

Cash-out (offramp), chave de correlação `intentId`

Cash-in (onramp), chave de correlação `intentId`

Saque BRLP (Modo B), chave de correlação `withdrawId`

KYC, chave de correlação `sessionId`

Verificação de assinatura

Garantias de entrega

Retry

Confirmação

Idempotência

Somente HTTPS

​Registrar um destino

​Envelope do payload

​Catálogo de eventos

​Cash-out (offramp), chave de correlação intentId

​Cash-in (onramp), chave de correlação intentId

​Saque BRLP (Modo B), chave de correlação withdrawId

​KYC, chave de correlação sessionId

​Verificação de assinatura

​Garantias de entrega

Retry

Confirmação

Idempotência

Somente HTTPS

Registrar um destino

Envelope do payload

Catálogo de eventos

Cash-out (offramp), chave de correlação `intentId`

Cash-in (onramp), chave de correlação `intentId`

Saque BRLP (Modo B), chave de correlação `withdrawId`

KYC, chave de correlação `sessionId`

Verificação de assinatura

Garantias de entrega