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 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 (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 é opcional, porém fortemente recomendada 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",
}
},
}