Skip to main content

​
Visão Geral

O modo PIX Bacen inclui duas funcionalidades que precisam ser ativadas:
  1. Endpoints BACEN: Acesso aos endpoints compatíveis com a especificação do Banco Central
  2. 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 [email protected] 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á:
  1. Ativar o modo PIX Bacen na sua conta
  2. Habilitar os endpoints e o formato de webhook V2
  3. Confirmar a ativação por email

​
3. Teste a integração

Após a ativação:
  1. Faça uma cobrança teste via PUT /cob/:txid
  2. Verifique se o webhook V2 chegou corretamente
  3. 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:
AntesDepois
POST /pix/cash-inPUT /cob/:txid
POST /pix/cash-outPOST /dict/pix
POST /pix/:id/refundPUT /pix/:e2eid/devolucao/:id
GET /balanceGET /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": "uuid-123",
  "movementType": "CREDIT",
  "originalAmount": 100.00,
  "finalAmount": 100.00,
  "counterpart": {
    "name": "João Silva",
    "document": "123.xxx.xxx-xx"
  }
}

​
Principais diferenças nos Webhooks

AspectoV1V2
EstruturaCampos na raizEnvelope {type, data}
Tipo de eventoevent: "CashIn"type: "RECEIVE"
Status sucessoCONFIRMEDLIQUIDATED
Status refundCONFIRMEDREFUNDED
Valoresnumber (100.00)string (“100.00”)
ContrapartecounterpartdebtorAccount / 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:
  1. Solicite ativação no ambiente de sandbox
  2. Execute testes completos de Cash-In, Cash-Out e Refund
  3. 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 versões 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

1

Implementar handler V2

Atualize seu código para processar o formato envelope {type, data}
2

Testar em sandbox

Solicite ativação em sandbox e execute testes completos
3

Validar todos os eventos

Teste: RECEIVE, TRANSFER, REFUND com status LIQUIDATED, REFUNDED e ERROR
4

Solicitar ativação em produção

Envie email para [email protected] com as informações necessárias
5

Monitorar primeiras transações

Acompanhe as primeiras transações após a ativação para garantir funcionamento

​
Dúvidas Frequentes

Os endpoints podem ser usados simultaneamente (ex: POST /pix/cash-in e PUT /cob/:txid).Os webhooks são sempre na versão configurada na conta. Não é possível receber V1 e V2 ao mesmo tempo.
Transações criadas antes da ativação continuarão enviando webhooks no formato antigo até serem concluídas. Novas transações usarão o formato V2.
Não. A URL permanece a mesma. Apenas o formato do payload muda.

​
Próximos Passos

Webhooks V2

Entenda o novo formato de webhooks

Criar Cobrança

Use o endpoint BACEN para criar cobranças