Ativação

Visão Geral

O modo PIX Bacen tem duas partes independentes:

1. Endpoints BACEN: endpoints compatíveis com a especificação do Banco Central. Estão disponíveis para qualquer conta autenticada, sem ativação: basta usar o mesmo token Bearer da API padrão.
2. Webhooks V2: formato de notificação com envelope {type, data}. É escolhido por webhook (por URL cadastrada), pelo próprio cliente.

Como Ativar os Webhooks V2

1. Pelo painel

No Painel FyPay, acesse Configurações → Webhooks, cadastre (ou recadastre) a URL do evento desejado e em Versão do payload, selecione PIX BACEN (V2). A versão é configurada somente pelo painel.

2. Teste a integração

Depois de trocar a versão:

1. Faça uma cobrança de teste via PUT /api/cob/:txid
2. Verifique se o webhook V2 chegou corretamente
3. Confirme que sua aplicação processou o novo formato

O que muda?

Endpoints

Os endpoints BACEN equivalem às seguintes operações da API padrão:

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

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 | null;
  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 com uma URL adicional

Antes de trocar a versão das URLs que já estão em uso:

1. Cadastre no mesmo evento uma URL de teste adicional com a versão PIX BACEN (cada evento aceita até 3 URLs e cada URL tem sua própria versão)
2. Execute testes completos de Cash-In, Cash-Out e Refund
3. Valide que todos os webhooks são processados corretamente

Rollback

A versão pode ser trocada de volta para V1 a qualquer momento, pelo painel (Configurações → Webhooks), selecionando a versão Padrão (V1) na URL.

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

Dúvidas Frequentes

Próximos Passos