Activación

Descripción General

El modo PIX Bacen tiene dos partes independientes:

1. Endpoints BACEN: endpoints compatibles con la especificación del Banco Central. Están disponibles para cualquier cuenta autenticada, sin activación: basta con usar el mismo token Bearer de la API estándar.
2. Webhooks V2: formato de notificación con envelope {type, data}. Se elige por webhook (por URL registrada), por el propio cliente.

Cómo Activar los Webhooks V2

1. Desde el dashboard

En el Dashboard de FyPay, acceda a Configuración → Webhooks, registre (o vuelva a registrar) la URL del evento deseado y, en Versión del payload, seleccione PIX BACEN (V2). La versión se configura solo desde el dashboard.

2. Pruebe la integración

Después de cambiar la versión:

1. Haga un cobro de prueba vía PUT /api/cob/:txid
2. Verifique que el webhook V2 llegó correctamente
3. Confirme que su aplicación procesó el nuevo formato

¿Qué cambia?

Endpoints

Los endpoints BACEN equivalen a las siguientes operaciones de la API estándar:

Webhooks

El formato del webhook cambia 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": {...}
  }
}

Principales diferencias en los Webhooks

Preparando su integración

1. Actualice el handler de webhooks

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

// DESPUÉS (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. Actualice los 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;  // Nota: string, no number!
    currency: string;
  };
  creditDebitType: 'CREDIT' | 'DEBIT';
  debtorAccount: AccountInfo;
  creditorAccount: AccountInfo;
  endToEndId: string | null;
  refunds: RefundInfo[];
  // ... otros campos
}

3. Pruebe con una URL adicional

Antes de cambiar la versión de las URLs que ya están en uso:

1. Registre en el mismo evento una URL de prueba adicional con la versión PIX BACEN (cada evento acepta hasta 3 URLs y cada URL tiene su propia versión)
2. Ejecute pruebas completas de Cash-In, Cash-Out y Refund
3. Valide que todos los webhooks se procesan correctamente

Rollback

La versión puede volver a V1 en cualquier momento, desde el dashboard (Configuración → Webhooks), seleccionando la versión Estándar (V1) en la URL.

Recomendamos mantener soporte para ambas versiones durante la transición:

function handleWebhook(payload: any) {
  // Detectar versión por formato
  if (payload.type && payload.data) {
    return handleWebhookV2(payload);
  } else if (payload.event) {
    return handleWebhookV1(payload);
  }
  throw new Error('Formato de webhook desconocido');
}

Checklist de Activación

Preguntas Frecuentes

Próximos Pasos