Esta página descreve o formato do webhook enviado pela plataforma sempre que houver uma atualização no status de um pagamento.
O webhook de pagamento é enviado automaticamente sempre que o status do pagamento for alterado, permitindo que o sistema do integrador mantenha suas informações sincronizadas em tempo real.
As notificações são enviadas via requisições HTTP no método POST, utilizando o formato JSON.
Todos os campos de data e hora enviados nos webhooks utilizam o padrão ISO 8601 no timezone UTC (UTC+00:00), garantindo consistência independentemente do fuso horário do integrador. Para evitar divergências causadas por horários locais ou horário de verão, recomenda-se manter os valores em UTC para armazenamento e processamento, realizando a conversão para o fuso horário local apenas no nível de apresentação ao usuário final.
Para aumentar a segurança, os webhooks cadastrados diretamente no painel podem incluir uma assinatura enviada no header X-Signature: <assinatura-em-base64>, permitindo validar a autenticidade da notificação recebida. Essa assinatura é gerada pela plataforma utilizando HMAC com SHA-256 sobre o corpo do webhook, em formato JSON, usando um segredo compartilhado WEBHOOK_SECRET e codificada em Base64. O integrador pode reproduzir o mesmo cálculo em seu sistema utilizando o mesmo segredo e o payload recebido. Se a assinatura gerada for igual à enviada no header, o webhook é considerado legítimo e íntegro. Caso sejam diferentes, a requisição pode ter sido alterada ou não ter sido enviada pela plataforma.
Essa validação está disponível apenas para webhooks cadastrados no painel. Webhooks enviados para uma URL informada dinamicamente via notificationUrl não incluem a assinatura X-Signature.
A validação por assinatura é opcional, porém fortemente recomendada sempre que o webhook for configurado pelo painel, para garantir maior segurança na comunicação.
A URL de notificação deve ser informada no momento da criação do pagamento, através do campo <code>notificationUrl</code>.
O endpoint deve estar acessível publicamente e responder com HTTP 200 para confirmar o recebimento do webhook.
Além disso, as notificações de pagamento também podem ocorrer via webhook in-bound, configurado diretamente no painel do gateway. Nesse modelo, o endpoint é previamente cadastrado e será acionado automaticamente a cada mudança de status do pagamento.
Os possíveis valores para o campo status são:
Abaixo estão exemplos de payload enviados no webhook de acordo com o meio de pagamento.
{
"id": "pay_01HXYZ123ABC456DEF789",
"amount": 10000,
"method": "PIX",
"currency": "BRL",
"status": "PAID",
"description": "Pagamento de teste via PIX",
"installments": 1,
"payer": {
"name": "John Doe",
"taxId": "12345678900",
"email": "john.doe@example.com",
"phone": "11999990000"
},
"externalRef": "order_123456",
"notificationUrl": "https://example-webhook.test/notifications",
"metadata": null,
"paidAt": "2026-01-15T16:51:42.782Z",
"refundedAt": null,
"createdAt": "2026-01-15T13:44:25.838Z",
"updatedAt": "2026-01-15T16:51:42.782Z",
"orderId": null,
"data": {
"method": "PIX",
"copypaste": "00020101021226850014br.gov.bcb.pix2563api.gateway.test/pix/123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5920GATEWAY TESTE6009SaoPaulo61080540900062070503***6304ABCD",
"e2e": "E1234567890123456789012345678901"
},
"splits": [
{
"amount": 10000,
"currency": "BRL",
"percent": 100,
"storeId": "store_test_001",
"splitId": null
}
],
"items": [
{
"quantity": 1,
"name": "Produto Teste",
"price": 1000,
"type": "PHYSICAL"
}
],
"delivery": {
"fee": 1500,
"address": {
"country": "BR",
"state": "SP",
"city": "São Paulo",
"district": "Centro",
"street": "Rua Exemplo",
"number": "123",
"complement": "Apto 45",
"zipCode": "01001-000",
}
},
}