Activación
Descripción general
El modo PIX Bacen incluye dos funcionalidades que necesitan ser activadas:
- Endpoints BACEN: Acceso a endpoints compatibles con la especificacion del Banco Central
- Webhooks V2: Nuevo formato de notificación con el envelope
{type, data}
Activar el modo PIX Bacen es un cambio incompatible. Los webhooks cambiaran a un formato completamente diferente. Asegurese de actualizar su integración antes de solicitar la activación.
Como Solicitar la Activación
1. Contactar soporte
Envie un correo electrónico a suporte@ntxpay.com con:
- Nombre de la empresa
- CNPJ
- Client ID de la aplicación
- Confirmación de que ya implemento el soporte para Webhooks V2
2. Esperar la configuración
Nuestro equipo:
- Activara el modo PIX Bacen en su cuenta
- Habilitara los endpoints y el formato de webhook V2
- Confirmara la activación por correo electrónico
3. Probar la integración
Después de la activación:
- Realice un cobro de prueba via
PUT /cob/:txid - Verifique que el webhook V2 llego correctamente
- Confirme que su aplicación proceso el nuevo formato
Que cambia con la activación?
Endpoints
Obtiene acceso a los endpoints BACEN:
| Antes | Después |
|---|---|
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 |
Los endpoints antiguos siguen funcionando. Puede usar ambas APIs simultaneamente.
Webhooks
El formato de webhook cambia completamente:
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionId": "12345",
"movementType": "CREDIT",
"originalAmount": 100.00,
"finalAmount": 100.00,
"counterpart": {
"name": "Joao 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": "Joao Silva",
"document": "123.xxx.xxx-xx"
},
"creditorAccount": {...}
}
}Diferencias clave de webhooks
| Aspecto | V1 | V2 |
|---|---|---|
| Estructura | Campos en la raiz | Envelope {type, data} |
| Tipo de evento | event: "CashIn" | type: "RECEIVE" |
| Estado de exito | CONFIRMED | LIQUIDATED |
| Estado de devolución | CONFIRMED | REFUNDED |
| Valores | number (100.00) | string ("100.00") |
| Contraparte | counterpart | debtorAccount / creditorAccount |
Preparando su integración
1. Actualizar el handler de webhooks
// ANTES (V1)
function handleWebhookV1(payload: any) {
if (payload.event === 'CashIn' && payload.status === 'CONFIRMED') {
processPayment(payload.transactionId, payload.finalAmount);
}
}
// DESPUES (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. Actualizar tipos/interfaces
// Tipos V2
interface WebhookV2Payload {
type: 'RECEIVE' | 'TRANSFER' | 'REFUND';
data: WebhookV2Data;
}
interface WebhookV2Data {
id: number;
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. Probar en el entorno de desarrollo
Antes de solicitar la activación en producción:
- Solicite la activación en el entorno sandbox
- Ejecute pruebas completas de Cash-In, Cash-Out y Devolución
- Valide que todos los webhooks se procesen correctamente
Reversion
Después de la activación, no es posible revertir a V1 automáticamente. Si necesita revertir, contacte a soporte.
Recomendamos mantener soporte para ambas versiones durante la transicion:
function handleWebhook(payload: any) {
// Detectar version por formato
if (payload.type && payload.data) {
return handleWebhookV2(payload);
} else if (payload.event) {
return handleWebhookV1(payload);
}
throw new Error('Formato de webhook desconocido');
}Lista de verificación para la activación
Actualice su código para procesar el formato de envelope {type, data}
Solicite la activación en sandbox y ejecute pruebas completas
Pruebe: RECEIVE, TRANSFER, REFUND con los estados LIQUIDATED, REFUNDED y ERROR
Envie un correo electrónico a suporte@ntxpay.com con la información requerida
Monitoree las primeras transacciones después de la activación para asegurar que todo funcione