API atual/Referência completa/Webhooks e eventos

Pagamentos e antifraude

Rotas que gateways de pagamento, o Pix e o antifraude chamam para confirmar pagamentos e devolver a análise de risco de um pedido.

Aqui estão as rotas que os parceiros financeiros chamam: o gateway que avisa que um pagamento foi aprovado, recusado ou estornado, o provedor de Pix que confirma a liquidação e o serviço antifraude que devolve o resultado da análise. Em todas, a chamada vem do parceiro (não do seu código), e a loja precisa ter o módulo do parceiro ativo e o segredo cadastrado. Leia antes a visão geral da entrada.

Notificação genérica de gateway

Rota para gateways que enviam um JSON próprio. A loja confere o HMAC-SHA256 do corpo com o segredo de webhook (webhook_secret) da forma de pagamento e entrega o JSON ao módulo do provedor para atualizar o pagamento e o pedido. O {provider} é o código do provedor: pix, pagarme, braspag, a27, getnet, pagseguro, erede.

POST/api/v1/webhooks/payments/{provider}Pública

Receber notificação de um gateway de pagamento

Parâmetros de caminho

providerstringobrigatório

Código do provedor de pagamento.

Cabeçalhos

X-Webhook-Signaturestringobrigatório

HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, com o segredo de webhook da forma de pagamento. O prefixo sha256= é aceito. Também vale X-Signature no lugar deste.

Content-Typestring

application/json.

Corpo da requisição

(JSON)objectobrigatório

Um documento JSON não vazio, no formato do provedor. {} e [] são aceitos e ignorados.

Exemplo de requisição

bash

BODY='{"id":"evt_9f31","type":"charge.paid"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed 's/^.* //')

curl -X POST "$BASE_URL/api/v1/webhooks/payments/getnet" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$BODY"

Resposta

200Processado

json

{ "message": "webhook processed" }

Outras respostas 200: {"message":"module disabled"} (módulo do provedor desligado) e {"message":"ignored: empty payload"} (corpo {} ou []).

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook body"}`
400	Corpo que não é JSON	`{"error":"invalid webhook body","detail":"expected a JSON document"}`
401	Sem segredo de webhook configurado na forma de pagamento	`{"error":"webhook signature verification not configured"}`
401	Falta o cabeçalho de assinatura	`{"error":"missing webhook signature"}`
403	Assinatura não confere	`{"error":"invalid webhook signature"}`
500	Falha ao processar	`{"error":"failed to process webhook"}`

Pix

Confirmação de liquidação de um Pix no formato de notificação do Banco Central. A loja localiza a cobrança pelo txid e marca o pagamento como pago. A autenticação é um segredo compartilhado, comparado literalmente, e não um HMAC.

POST/api/v1/webhooks/pixPública

Confirmar liquidação de Pix

Cabeçalhos

X-Webhook-Secretstringobrigatório

Segredo de webhook cadastrado na configuração de Pix da loja.

Corpo da requisição

pixarrayobrigatório

Lista de liquidações.

txidstringobrigatório

Identificador da cobrança gerada pela loja.

endToEndIdstring

Identificador ponta a ponta (E2EID) do Banco Central.

valorstring

Valor pago, em reais, como texto decimal ("49.90").

horariostring

Momento da liquidação, RFC 3339.

pagadorobject

Opcional. Quem pagou: cpf ou cnpj, e nome.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/pix" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $PIX_WEBHOOK_SECRET" \
  -d '{"pix":[{"endToEndId":"E00038166202610112015A1B2C3D4E5F6","txid":"PIX3f73310dbfdd4713a664305c08eda58b","valor":"225.00","horario":"2026-10-11T20:16:40Z"}]}'

Resposta

200Confirmado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON no formato esperado	`{"error":"invalid webhook payload"}`
401	Segredo ausente ou errado, sem segredo na loja, ou qualquer falha ao processar a liquidação	`{"error":"webhook processing failed"}`
403	Módulo `pix-payments` desligado	`{"error":"module_disabled","module":"pix-payments"}`

Pagar.me

Eventos do Pagar.me sobre cobranças. A loja guarda cada evento, ignora repetições de um evento já processado e converte o tipo do evento em um novo status de pedido. O pedido é encontrado pelo campo data.code, que a loja envia ao Pagar.me no formato ORDER_<id do pedido>.

POST/api/v1/webhooks/pagarmePública

Receber evento do Pagar.me

Cabeçalhos

X-Hub-Signaturestringobrigatório

HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, usando a chave secreta da conta Pagar.me cadastrada na loja. O prefixo sha256= é aceito.

Corpo da requisição

typestringobrigatório

Tipo do evento. Tratados: charge.paid, charge.canceled, charge.refunded, charge.failed e os equivalentes de recusado, chargeback, pendente, autorizado e processando. Tipos desconhecidos são aceitos e não alteram o pedido.

dataobjectobrigatório

Dados da cobrança.

idstring

Id da cobrança no Pagar.me.

codestring

ORDER_ seguido do id (UUID) do pedido.

Exemplo de requisição

bash

BODY='{"type":"charge.paid","data":{"id":"ch_Ab12Cd34","code":"ORDER_3f73310d-bfdd-4713-a664-305c08eda58b"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$PAGARME_SECRET_KEY" | sed 's/^.* //')

curl -X POST "$BASE_URL/api/v1/webhooks/pagarme" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature: $SIG" \
  -d "$BODY"

Resposta

200Processado

json

{ "message": "webhook processed" }

200Evento repetido

json

{ "message": "duplicate event ignored" }

Mapeamento padrão de evento para pedido: pago leva o pedido a processing; cancelado a cancelled; estornado a refunded; falha ou recusa a failed; chargeback a chargeback. A loja pode personalizar esse mapa. Uma falha tardia (pagamento falhou ou foi cancelado) nunca é aplicada sobre um pedido cujo pagamento já foi capturado.

Erros

Status	Quando	Corpo
403	Módulo `pagarme` desligado	`{"error":"module_disabled","module":"pagarme"}`
500	Assinatura inválida ou ausente (a plataforma devolve `500`, não `401`)	`{"error":"failed to process webhook","detail":"pagarme: webhook signature invalid: signature mismatch"}`
500	Outra falha ao gravar o evento	`{"error":"failed to process webhook","detail":"..."}`

Braspag

A Braspag manda uma notificação mínima com o id do pagamento. A loja não confia no conteúdo: consulta a Braspag para saber o status verdadeiro e só então atualiza o pagamento. Por isso não há assinatura. A resposta é sempre 200 para a Braspag não repetir sem fim.

POST/api/v1/webhooks/braspagPública

Receber notificação da Braspag

Corpo da requisição

PaymentIdstringobrigatório

GUID do pagamento na Braspag.

ChangeTypeintegerobrigatório

13

Natureza da mudança. 1 é mudança de status do pagamento e 3 é mudança de antifraude; os demais valores são aceitos e ignorados.

RecurrentPaymentIdstring

Opcional. Presente em eventos de recorrência.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/braspag" \
  -H "Content-Type: application/json" \
  -d '{"PaymentId":"2e1b6d3a-7f48-4c09-b5a2-8d0e3f1c9a67","ChangeType":1}'

Resposta

200Aceito

json

{ "status": "ok", "payment_id": "2e1b6d3a-7f48-4c09-b5a2-8d0e3f1c9a67" }

Quando o processamento interno falha a resposta continua 200, com {"status":"error_logged"}.

Erros

Status	Quando	Corpo
400	Não foi possível ler o corpo	`{"error":"failed to read body"}`
403	Módulo `braspag` desligado	`{"error":"module_disabled","module":"braspag"}`

ClearSale (antifraude)

A ClearSale devolve o resultado da análise de risco de um pedido. A loja atualiza a análise do pedido com nota, status e motivo, convertendo o status conforme a configuração do módulo.

POST/api/v1/webhooks/clearsalePública

Receber resultado da análise antifraude

Cabeçalhos

X-Webhook-Secretstringobrigatório

Segredo de webhook cadastrado no módulo ClearSale da loja.

Corpo da requisição

orderIdstringobrigatório

Número ou id do pedido analisado.

scorenumber

Nota de risco da análise.

statusstring

APARPDAMA

APA aprovado, RPD reprovado, AMA análise manual.

reasonstring

Motivo, quando houver.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/clearsale" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $CLEARSALE_WEBHOOK_SECRET" \
  -d '{"orderId":"100245","score":12.5,"status":"APA"}'

Resposta

200Aceito

json

{ "status": "ok" }

Se a gravação falhar a resposta é 200 com {"status":"error_logged"}, para a ClearSale não repetir.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"Invalid webhook payload"}`
400	`orderId` ausente	`{"error":"orderId is required"}`
401	Segredo ausente ou errado	`{"error":"invalid webhook secret"}`
403	Segredo não cadastrado na loja	`{"error":"webhook secret not configured"}`
403	Módulo `clearsale` desligado	`{"error":"module_disabled","module":"clearsale"}`

Veja também

API atual/Referência completa/Webhooks e eventos

Pagamentos e antifraude

Rotas que gateways de pagamento, o Pix e o antifraude chamam para confirmar pagamentos e devolver a análise de risco de um pedido.

Notificação genérica de gateway

POST/api/v1/webhooks/payments/{provider}Pública

Receber notificação de um gateway de pagamento

Parâmetros de caminho

providerstringobrigatório

Código do provedor de pagamento.

Cabeçalhos

X-Webhook-Signaturestringobrigatório

HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, com o segredo de webhook da forma de pagamento. O prefixo sha256= é aceito. Também vale X-Signature no lugar deste.

Content-Typestring

application/json.

Corpo da requisição

(JSON)objectobrigatório

Um documento JSON não vazio, no formato do provedor. {} e [] são aceitos e ignorados.

Exemplo de requisição

bash

BODY='{"id":"evt_9f31","type":"charge.paid"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed 's/^.* //')

curl -X POST "$BASE_URL/api/v1/webhooks/payments/getnet" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$BODY"

Resposta

200Processado

json

{ "message": "webhook processed" }

Outras respostas 200: {"message":"module disabled"} (módulo do provedor desligado) e {"message":"ignored: empty payload"} (corpo {} ou []).

Erros

Status	Quando	Corpo
400	Corpo vazio	`{"error":"empty webhook body"}`
400	Corpo que não é JSON	`{"error":"invalid webhook body","detail":"expected a JSON document"}`
401	Sem segredo de webhook configurado na forma de pagamento	`{"error":"webhook signature verification not configured"}`
401	Falta o cabeçalho de assinatura	`{"error":"missing webhook signature"}`
403	Assinatura não confere	`{"error":"invalid webhook signature"}`
500	Falha ao processar	`{"error":"failed to process webhook"}`

Pix

POST/api/v1/webhooks/pixPública

Confirmar liquidação de Pix

Cabeçalhos

X-Webhook-Secretstringobrigatório

Segredo de webhook cadastrado na configuração de Pix da loja.

Corpo da requisição

pixarrayobrigatório

Lista de liquidações.

txidstringobrigatório

Identificador da cobrança gerada pela loja.

endToEndIdstring

Identificador ponta a ponta (E2EID) do Banco Central.

valorstring

Valor pago, em reais, como texto decimal ("49.90").

horariostring

Momento da liquidação, RFC 3339.

pagadorobject

Opcional. Quem pagou: cpf ou cnpj, e nome.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/pix" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $PIX_WEBHOOK_SECRET" \
  -d '{"pix":[{"endToEndId":"E00038166202610112015A1B2C3D4E5F6","txid":"PIX3f73310dbfdd4713a664305c08eda58b","valor":"225.00","horario":"2026-10-11T20:16:40Z"}]}'

Resposta

200Confirmado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON no formato esperado	`{"error":"invalid webhook payload"}`
401	Segredo ausente ou errado, sem segredo na loja, ou qualquer falha ao processar a liquidação	`{"error":"webhook processing failed"}`
403	Módulo `pix-payments` desligado	`{"error":"module_disabled","module":"pix-payments"}`

Pagar.me

POST/api/v1/webhooks/pagarmePública

Receber evento do Pagar.me

Cabeçalhos

X-Hub-Signaturestringobrigatório

HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, usando a chave secreta da conta Pagar.me cadastrada na loja. O prefixo sha256= é aceito.

Corpo da requisição

typestringobrigatório

dataobjectobrigatório

Dados da cobrança.

idstring

Id da cobrança no Pagar.me.

codestring

ORDER_ seguido do id (UUID) do pedido.

Exemplo de requisição

bash

BODY='{"type":"charge.paid","data":{"id":"ch_Ab12Cd34","code":"ORDER_3f73310d-bfdd-4713-a664-305c08eda58b"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$PAGARME_SECRET_KEY" | sed 's/^.* //')

curl -X POST "$BASE_URL/api/v1/webhooks/pagarme" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature: $SIG" \
  -d "$BODY"

Resposta

200Processado

json

{ "message": "webhook processed" }

200Evento repetido

json

{ "message": "duplicate event ignored" }

Erros

Status	Quando	Corpo
403	Módulo `pagarme` desligado	`{"error":"module_disabled","module":"pagarme"}`
500	Assinatura inválida ou ausente (a plataforma devolve `500`, não `401`)	`{"error":"failed to process webhook","detail":"pagarme: webhook signature invalid: signature mismatch"}`
500	Outra falha ao gravar o evento	`{"error":"failed to process webhook","detail":"..."}`

Braspag

POST/api/v1/webhooks/braspagPública

Receber notificação da Braspag

Corpo da requisição

PaymentIdstringobrigatório

GUID do pagamento na Braspag.

ChangeTypeintegerobrigatório

13

Natureza da mudança. 1 é mudança de status do pagamento e 3 é mudança de antifraude; os demais valores são aceitos e ignorados.

RecurrentPaymentIdstring

Opcional. Presente em eventos de recorrência.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/braspag" \
  -H "Content-Type: application/json" \
  -d '{"PaymentId":"2e1b6d3a-7f48-4c09-b5a2-8d0e3f1c9a67","ChangeType":1}'

Resposta

200Aceito

json

{ "status": "ok", "payment_id": "2e1b6d3a-7f48-4c09-b5a2-8d0e3f1c9a67" }

Quando o processamento interno falha a resposta continua 200, com {"status":"error_logged"}.

Erros

Status	Quando	Corpo
400	Não foi possível ler o corpo	`{"error":"failed to read body"}`
403	Módulo `braspag` desligado	`{"error":"module_disabled","module":"braspag"}`

ClearSale (antifraude)

A ClearSale devolve o resultado da análise de risco de um pedido. A loja atualiza a análise do pedido com nota, status e motivo, convertendo o status conforme a configuração do módulo.

POST/api/v1/webhooks/clearsalePública

Receber resultado da análise antifraude

Cabeçalhos

X-Webhook-Secretstringobrigatório

Segredo de webhook cadastrado no módulo ClearSale da loja.

Corpo da requisição

orderIdstringobrigatório

Número ou id do pedido analisado.

scorenumber

Nota de risco da análise.

statusstring

APARPDAMA

APA aprovado, RPD reprovado, AMA análise manual.

reasonstring

Motivo, quando houver.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/clearsale" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: $CLEARSALE_WEBHOOK_SECRET" \
  -d '{"orderId":"100245","score":12.5,"status":"APA"}'

Resposta

200Aceito

json

{ "status": "ok" }

Se a gravação falhar a resposta é 200 com {"status":"error_logged"}, para a ClearSale não repetir.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"Invalid webhook payload"}`
400	`orderId` ausente	`{"error":"orderId is required"}`
401	Segredo ausente ou errado	`{"error":"invalid webhook secret"}`
403	Segredo não cadastrado na loja	`{"error":"webhook secret not configured"}`
403	Módulo `clearsale` desligado	`{"error":"module_disabled","module":"clearsale"}`