Activación

Descripción GeneralCopy Anchor Link

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 V2Copy Anchor Link

1. Desde el dashboardCopy Anchor Link

En el Dashboard de Gateways, 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ónCopy Anchor Link

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?Copy Anchor Link

EndpointsCopy Anchor Link

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

WebhooksCopy Anchor Link

El formato del webhook cambia completamente:

Principales diferencias en los WebhooksCopy Anchor Link

Preparando su integraciónCopy Anchor Link

1. Actualice el handler de webhooksCopy Anchor Link

// 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/interfacesCopy Anchor Link

// 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 adicionalCopy Anchor Link

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

RollbackCopy Anchor Link

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ónCopy Anchor Link

Preguntas FrecuentesCopy Anchor Link

Próximos PasosCopy Anchor Link