Webhooks

A OriPay envia um POST JSON para a sua URL a cada evento.

Configurar

A URL e o secret ficam no OriPay Web (app.oripaysolutions.com.br), em Conta → API → Webhook, com confirmação por PIN. Não dá para alterá-los pela API: se uma chave vazar, ninguém consegue desviar os seus eventos.

Regra da URL	Valor
Protocolo	Só `https://`, certificado válido, TLS 1.2 ou maior
Porta	443 (sem porta explícita ou `:443`)
Host	Nome de domínio. IP literal na URL é recusado
Destino	Domínio público. IPs privados, loopback e link-local são recusados, conferidos a cada entrega
Redirect	Não é seguido. Um `3xx` conta como falha

Ao salvar a URL pela primeira vez, o OriPay Web mostra o secret (whsec_...) uma vez. Guarde em cofre. Trocar a URL depois mantém o mesmo secret. Confira a configuração atual com GET /v1/webhook-endpoint (sem o secret).

Eventos

Evento	Quando
`charge.paid`	Cobrança paga e creditada
`charge.expired`	Cobrança venceu sem pagamento
`pix.received`	Qualquer PIX creditado (de cobrança ou direto na chave)
`transfer.completed`	Transferência liquidada
`transfer.failed`	Transferência recusada; o valor voltou ao saldo. Sai até 2 horas depois da recusa, porque a conciliação ainda pode achar a transferência liquidada (aí chega `transfer.completed`)
`transfer.returned`	O banco do recebedor devolveu uma transferência já liquidada
`refund.completed`	Devolução liquidada
`refund.failed`	Devolução recusada
`webhook.test`	Evento de teste que você mesmo dispara. Ver Testar e reenviar

Formato

POST /webhooks/oripay HTTP/1.1
content-type: application/json
user-agent: OriPay-Webhooks/1.0
oripay-event-id: evt_9f8e7d6c-5b4a-4321-8fed-cba987654321
oripay-event-type: charge.paid
oripay-delivery-id: dlv_1a2b3c4d-...
oripay-delivery-attempt: 1
oripay-signature: t=1761656713,v1=5d41402abc4b2a76b9719d911017c592...

{
  "id": "evt_9f8e7d6c-5b4a-4321-8fed-cba987654321",
  "type": "charge.paid",
  "created_at": "2026-10-28T13:05:13Z",
  "data": {
    "id": "6a0e1f8c-0b7c-4f0e-9a51-2c3d4e5f6a7b",
    "external_id": "pedido-8812",
    "status": "paid",
    "amount": 15000,
    "description": "Pedido 8812",
    "qr_code": "00020101021226...6304ABCD",
    "qr_code_image": "data:image/png;base64,iVBORw0...",
    "expires_at": "2026-10-28T14:00:00Z",
    "paid_at": "2026-10-28T13:05:12Z",
    "received_id": "c41b7a2e-8e1d-4a3f-b0c2-9d8e7f6a5b4c",
    "end_to_end_id": "E30507541202610281300abcdef123456",
    "payer": { "name": "Maria Souza", "document": "***.456.789-**", "bank": "Banco Exemplo S.A." },
    "metadata": { "customer_id": "cli_4471" },
    "created_at": "2026-10-28T13:00:00Z"
  }
}

Os nomes de header são enviados em minúsculas; trate-os sem diferenciar maiúsculas. oripay-delivery-attempt é o número da tentativa daquele evento. data é o recurso completo, no mesmo formato do GET, como estava quando o evento foi gerado. Ele traz o seu metadata e o payer (quem pagou), para você identificar o cliente. Para o estado mais recente, faça GET do recurso.

Quando o evento é gerado

Os eventos saem do livro-razão da conta, não da notificação do banco: a cada cerca de 10 segundos a OriPay confere o que mudou e gera os eventos novos, um por recurso e tipo. Conte com alguns segundos (em geral até uns 20 s) entre o dinheiro se mover e o webhook sair. Se o webhook estiver desligado, os eventos continuam registrados como pending, podem ser consultados em GET /v1/events e são entregues quando você religar.

Responda rápido

Responda 2xx em até 10 segundos e processe depois, em fila.
O corpo da sua resposta é ignorado.
Qualquer outra resposta, timeout ou redirect conta como falha.

Reenvio automático

Se a entrega falhar, tentamos de novo após 1 min, 5 min, 30 min, 2 h, 6 h e 12 h: até 7 tentativas em cerca de 21 h. Depois disso o evento fica com status failed. Ele continua em GET /v1/events por 30 dias e pode ser reenviado manualmente. Depois de 30 dias o evento é apagado.

Garanta três coisas

Valide a assinatura de todo evento. Ver Assinatura.
Evite duplicidade: o mesmo evento pode chegar mais de uma vez. Guarde o oripay-event-id e ignore os repetidos.
Não dependa da ordem: eventos podem chegar fora de ordem. Use data.status ou faça GET do recurso.

Começando

Fundamentos

Fluxos PIX

Webhooks

Configurar

Eventos

Formato

Quando o evento é gerado

Responda rápido

Reenvio automático

Garanta três coisas

​Configurar

​Eventos

​Formato

​Quando o evento é gerado

​Responda rápido

​Reenvio automático

​Garanta três coisas

Configurar

Eventos

Formato

Quando o evento é gerado

Responda rápido

Reenvio automático

Garanta três coisas