Webhook de pagamentos

Quando configura uma URL HTTPS no painel (ou via API), o pixeway envia notificações em JSON para o seu servidor sempre que uma cobrança da conta é criada ou atualizada.

Ambiente sandbox: para testes com a instância pública de sandbox, utilize o host https://sandbox.pixeway.com (painel, API e webhooks seguem o mesmo domínio que em produção, isolados da produção).

Como é enviado

Método: POST
Corpo: JSON UTF-8 (o mesmo byte-a-byte usado no cálculo da assinatura).
Content-Type: application/json
Timeouts: ligação até 5 s, resposta total até 15 s. Responda com código HTTP 2xx para confirmar receção; outros códigos são tratados como falha e registados.
Fila: o envio é assíncrono (fila), normalmente poucos instantes após o evento na plataforma.

Cabeçalhos HTTP

Cabeçalho	Descrição
X-Donapix-Event	Igual ao campo `event` do JSON (`payment.created` ou `payment.updated`).
X-Donapix-Signature	Presente quando existe segredo HMAC configurado. Formato: `sha256=` seguido do HMAC-SHA256 em hexadecimal minúsculo do corpo bruto (string JSON exatamente como enviada), usando o segredo da conta.

Eventos

payment.created — nova cobrança criada.
payment.updated — cobrança alterada (estado, reembolso, dados sincronizados com o adquirente, etc.).

Estrutura do JSON

O objeto raiz contém event (string) e payment (objeto com o estado atual da cobrança).

Campos em payment (nomes em snake_case): correlation_id, status, method, amount (centavos), br_code, comment, customer (objeto ou null), metadata (objeto ou null), customer_ip, expires_at, paid_at, refunded_at, created_at, updated_at (datas em ISO 8601 quando aplicável).

Valores típicos de status: pending, paid, expired, canceled, refunded. Valores de method incluem pix, credit_card, boleto.

Exemplo de payload

{
  "event": "payment.updated",
  "payment": {
    "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "paid",
    "method": "pix",
    "amount": 1500,
    "br_code": "00020126580014br.gov.bcb.pix...",
    "comment": "Pedido #1234",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "phone": "5511999999999",
      "document": "12345678909"
    },
    "metadata": { "order_id": "1234" },
    "customer_ip": "203.0.113.10",
    "expires_at": "2026-04-19T18:00:00+00:00",
    "paid_at": "2026-04-19T17:05:22+00:00",
    "refunded_at": null,
    "created_at": "2026-04-19T16:00:00+00:00",
    "updated_at": "2026-04-19T17:05:30+00:00"
  }
}

Validar a assinatura (HMAC)

Leia o corpo da requisição como texto bruto (não re-serializar o JSON parseado). Calcule hash_hmac('sha256', $rawBody, $secret) em PHP ou equivalente na sua stack, prefixe com sha256= e compare em tempo constante com o valor de X-Donapix-Signature.

Configuração via API

Com token Bearer da API (permissão de webhooks de pagamentos):

GET /api/v1/account/payment-webhook — URL atual e se existe segredo.
PATCH /api/v1/account/payment-webhook — corpo JSON com webhook_url (HTTPS ou null para remover), opcionalmente rotate_secret (boolean).