Activation

Overview

PIX Bacen mode has two independent parts:

1. BACEN Endpoints: endpoints compatible with the Central Bank specification. They are available to any authenticated account, with no activation: just use the same Bearer token as the standard API.
2. V2 Webhooks: notification format with the {type, data} envelope. It is chosen per webhook (per registered URL), by the client.

How to Enable V2 Webhooks

1. Via the dashboard

In the FyPay Dashboard, go to Settings → Webhooks, register (or re-register) the URL for the desired event and, under Payload version, select PIX BACEN (V2). The version is configured only in the dashboard.

2. Test the integration

After switching the version:

1. Create a test charge via PUT /api/cob/:txid
2. Check that the V2 webhook arrived correctly
3. Confirm that your application processed the new format

What changes?

Endpoints

The BACEN endpoints are equivalent to the following standard API operations:

Webhooks

The webhook format changes completely:

{
  "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": {...}
  }
}

Key differences in Webhooks

Preparing your integration

1. Update the webhook handler

// BEFORE (V1)
function handleWebhookV1(payload: any) {
  if (payload.event === 'CashIn' && payload.status === 'CONFIRMED') {
    processPayment(payload.transactionId, payload.finalAmount);
  }
}

// AFTER (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. Update the types/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, not number!
    currency: string;
  };
  creditDebitType: 'CREDIT' | 'DEBIT';
  debtorAccount: AccountInfo;
  creditorAccount: AccountInfo;
  endToEndId: string | null;
  refunds: RefundInfo[];
  // ... other fields
}

3. Test with an additional URL

Before switching the version of the URLs already in use:

1. Register an additional test URL on the same event with the PIX BACEN version (each event accepts up to 3 URLs and each URL has its own version)
2. Run full Cash-In, Cash-Out, and Refund tests
3. Validate that all webhooks are processed correctly

Rollback

The version can be switched back to V1 at any time, in the dashboard (Settings → Webhooks), by selecting the Standard version (V1) on the URL.

We recommend supporting both versions during the transition:

function handleWebhook(payload: any) {
  // Detect version by format
  if (payload.type && payload.data) {
    return handleWebhookV2(payload);
  } else if (payload.event) {
    return handleWebhookV1(payload);
  }
  throw new Error('Unknown webhook format');
}

Activation Checklist

FAQ

Next Steps