Ativação
Visão Geral
O modo PIX Bacen inclui duas funcionalidades que precisam ser ativadas:
- Endpoints BACEN: Acesso aos endpoints compatíveis com a especificação do Banco Central
- Webhooks V2: Novo formato de notificações com envelope
{type, data}
A ativação do modo PIX Bacen é uma breaking change. Os webhooks passam a usar um formato completamente diferente. Certifique-se de atualizar sua integração antes de solicitar a ativação.
Como Solicitar Ativação
1. Entre em contato com o suporte
Envie um email para suporte@firebanking.com.br com:
- Nome da empresa
- CNPJ
- Client ID da aplicação
- Confirmação de que já implementou suporte ao Webhook V2
2. Aguarde a configuração
Nossa equipe irá:
- Ativar o modo PIX Bacen na sua conta
- Habilitar os endpoints e o formato de webhook V2
- Confirmar a ativação por email
3. Teste a integração
Após a ativação:
- Faca uma cobrança teste via
PUT /cob/:txid - Verifique se o webhook V2 chegou corretamente
- Confirme que sua aplicação processou o novo formato
O que muda com a ativação?
Endpoints
Você passa a ter acesso aos endpoints BACEN:
| Antes | Depois |
|---|---|
POST /pix/cash-in | PUT /cob/:txid |
POST /pix/cash-out | POST /dict/pix |
POST /pix/:id/refund | PUT /pix/:e2eid/devolucao/:id |
GET /balance | GET /accounts/balances |
Os endpoints antigos continuam funcionando. Você pode usar ambas as APIs simultaneamente.
Webhooks
O formato de webhook muda completamente:
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionId": "12345",
"movementType": "CREDIT",
"originalAmount": 100.00,
"finalAmount": 100.00,
"counterpart": {
"name": "João Silva",
"document": "123.xxx.xxx-xx"
}
}{
"type": "RECEIVE",
"data": {
"id": 123,
"txId": "abc123",
"status": "LIQUIDATED",
"payment": {
"amount": "100.00",
"currency": "BRL"
},
"creditDebitType": "CREDIT",
"debtorAccount": {
"name": "João Silva",
"document": "123.xxx.xxx-xx"
},
"creditorAccount": {...}
}
}Principais diferenças nos Webhooks
| Aspecto | V1 | V2 |
|---|---|---|
| Estrutura | Campos na raiz | Envelope {type, data} |
| Tipo de evento | event: "CashIn" | type: "RECEIVE" |
| Status sucesso | CONFIRMED | LIQUIDATED |
| Status refund | CONFIRMED | REFUNDED |
| Valores | number (100.00) | string ("100.00") |
| Contraparte | counterpart | debtorAccount / creditorAccount |
Preparando sua integração
1. Atualize o handler de webhooks
// ANTES (V1)
function handleWebhookV1(payload: any) {
if (payload.event === 'CashIn' && payload.status === 'CONFIRMED') {
processPayment(payload.transactionId, payload.finalAmount);
}
}
// DEPOIS (V2)
function handleWebhookV2(payload: any) {
if (payload.type === 'RECEIVE' && payload.data.status === 'LIQUIDATED') {
const amount = parseFloat(payload.data.payment.amount);
processPayment(payload.data.id, amount);
}
}2. Atualize os tipos/interfaces
// V2 Types
interface WebhookV2Payload {
type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
data: WebhookV2Data;
}
interface WebhookV2Data {
id: number;
txId: string | null;
status: 'PENDING' | 'LIQUIDATED' | 'REFUNDED' | 'ERROR';
payment: {
amount: string; // Note: string, não number!
currency: string;
};
creditDebitType: 'CREDIT' | 'DEBIT';
debtorAccount: AccountInfo;
creditorAccount: AccountInfo;
endToEndId: string | null;
refunds: RefundInfo[];
// ... outros campos
}3. Teste em ambiente de desenvolvimento
Antes de solicitar a ativação em produção:
- Solicite ativação no ambiente de sandbox
- Execute testes completos de Cash-In, Cash-Out e Refund
- Valide que todos os webhooks são processados corretamente
Rollback
Após a ativação, não é possível voltar para V1 automaticamente. Se precisar reverter, entre em contato com o suporte.
Recomendamos manter suporte a ambas as versoes durante a transição:
function handleWebhook(payload: any) {
// Detecta versão pelo formato
if (payload.type && payload.data) {
return handleWebhookV2(payload);
} else if (payload.event) {
return handleWebhookV1(payload);
}
throw new Error('Formato de webhook desconhecido');
}Checklist de Ativação
Atualize seu código para processar o formato envelope {type, data}
Solicite ativação em sandbox e execute testes completos
Teste: RECEIVE, TRANSFER, REFUND com status LIQUIDATED, REFUNDED e ERROR
Envie email para suporte@firebanking.com.br com as informações necessárias
Acompanhe as primeiras transações após a ativação para garantir funcionamento