Activation

Overview

PIX Bacen mode includes two features that need to be activated:

BACEN Endpoints: Access to endpoints compatible with the Central Bank specification
V2 Webhooks: New notification format with the {type, data} envelope

Activating PIX Bacen mode is a breaking change. Webhooks will switch to a completely different format. Make sure to update your integration before requesting activation.

How to Request Activation

1. Contact support

Send an email to suporte@safirapay.com with:

Company name
CNPJ
Application Client ID
Confirmation that you have already implemented V2 Webhook support

2. Wait for configuration

Our team will:

Activate PIX Bacen mode on your account
Enable the endpoints and V2 webhook format
Confirm the activation via email

3. Test the integration

After activation:

Make a test charge via PUT /cob/:txid
Verify that the V2 webhook arrived correctly
Confirm that your application processed the new format

What changes with activation?

Endpoints

You gain access to the BACEN endpoints:

Before	After
`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`

The old endpoints continue to work. You can use both APIs simultaneously.

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 webhook differences

Aspect	V1	V2
Structure	Fields at root	Envelope `{type, data}`
Event type	`event: "CashIn"`	`type: "RECEIVE"`
Success status	`CONFIRMED`	`LIQUIDATED`
Refund status	`CONFIRMED`	`REFUNDED`
Values	`number` (100.00)	`string` ("100.00")
Counterparty	`counterpart`	`debtorAccount` / `creditorAccount`

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

3. Test in the development environment

Before requesting activation in production:

Request activation in the sandbox environment
Run full tests for Cash-In, Cash-Out, and Refund
Validate that all webhooks are processed correctly

Rollback

After activation, it is not possible to revert to V1 automatically. If you need to roll back, contact support.

We recommend maintaining support for 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');
}