Webhooks

A DEUNA utiliza webhooks para enviar um snapshot atualizado do pedido ao seu backend sempre que um estado de pagamento ou pedido é alterado. O corpo padrão, voltado para o comerciante, contém o pedido em si. Não é um envelope de evento no estilo Stripe.

Como funciona#

Configure o destino#

Para a Purchase V2, forneça a URL de recebimento HTTPS no campo de notificação de pedido assíncrono mostrado abaixo:

{
  "order": {
    "order_id": "merchant-order-123",
    "webhook_urls": {
      "notify_order": "https://merchant.example.com/webhooks/deuna/orders"
    }
  }
}

A DEUNA armazena uma URL no nível do pedido e pode preencher um valor ausente com base na configuração do comerciante estabelecida durante o onboarding. O fluxo atual de notificações assinadas usa o destino e a assinatura de status no nível do comerciante; confirme com seu TAM a URL efetiva de cada ambiente. Os campos de URL de webhook assíncrono e síncrono são mutuamente exclusivos para um pedido.

As notificações de status do pedido não usam um recurso genérico de registro de endpoints de webhook. Configure o campo do pedido acima ou use a configuração no nível do comerciante acordada com seu Technical Account Manager (TAM) da DEUNA. Os callbacks dinâmicos do checkout usam a API separada descrita abaixo.

Fluxos de entrega suportados#

Use a entrega assíncrona, a menos que a DEUNA tenha explicitamente habilitado e certificado outro modo para sua integração.

A DEUNA cria candidatos de notificação quando os valores compatíveis de status do pedido ou do pagamento mudam, quando o processador selecionado muda e para decisões compatíveis de fraude ou 3DS. A assinatura configurada determina quais status de pagamento são entregues. Nem toda transição de status gera um webhook.

Este mecanismo cobre atualizações de compra e os resultados finais das operações assíncronas de captura, reembolso e anulação suportadas. Consulte Fluxo e status de pagamento para os status públicos e Captura, reembolso e anulação assíncronas para os fluxos dessas operações.

Webhooks de checkout dinâmico#

Os webhooks dinâmicos do checkout são um fluxo síncrono separado. Eles permitem que uma ação do checkout chame um endpoint do comerciante pelo nome do evento, valide ou transforme a resposta, atualize campos selecionados no pedido tokenizado e retorne valores selecionados ou a resposta do comerciante ao solicitante.

Utilize este fluxo para ações de checkout específicas do comerciante, como gorjetas, pontos de fidelidade, doações e comportamento de cupons personalizados. Não o utilize como substituto para a entrega assíncrona do status de pagamento.

A API Gateway ativa expõe estas operações de webhook dinâmico:

A solicitação de execução pode passar entradas específicas do evento em data:

{
  "data": {
    "tip_amount": 500
  }
}

A DEUNA carrega a configuração ativa do comerciante e do nome do evento e, em seguida, chama a URL configurada do comerciante. A configuração pode selecionar o método HTTP, os cabeçalhos, os parâmetros de URL e de consulta, os modelos de payload e resposta, as validações, os campos do pedido a serem atualizados, os campos de resposta a serem retornados e se a resposta do comerciante será propagada.

A solicitação do comerciante de saída inclui X-Signature e X-Deuna-Operation. A execução é síncrona: timeouts do comerciante, respostas inválidas, falhas de validação e respostas HTTP malsucedidas são retornados ao solicitante. Se o comerciante não tiver uma configuração para o nome do evento, a DEUNA retorna uma resposta de sucesso vazia sem chamar um endpoint do comerciante.

A configuração do webhook dinâmico é específica do comerciante e pode modificar um pedido. Confirme com seu TAM o nome do evento, a autenticação, os campos permitidos, os modelos, as validações, o timeout e a resposta propagada antes de habilitá-la. Consulte catálogo de endpoints para o inventário da gateway.

Payload padrão de status do pedido#

A solicitação padrão é uma solicitação HTTP POST com Content-Type: application/json e tem a seguinte estrutura:

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "refunded",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "refunded",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

O objeto completo do pedido pode conter os mesmos campos de pedido, cliente, item, valor, pagamento, processador, fraude e metadados retornados em uma resposta de pedido.

• Estado de pagamento autoritativo: order.payment.data.status
• Identificadores de negócios estáveis: order.token, order.order_ide os identificadores de transação aplicáveis

Configurações personalizadas do comerciante podem transformar este corpo. Se seu receptor não utilizar a forma padrão mostrada acima, confirme o payload exato com seu TAM.

Autenticar o status de entrega do pedido#

O fluxo de entrega atual envia este cabeçalho de solicitação:

X-Signature: <signature>

A assinatura é derivada por HMAC-SHA256 e codificação Base64 do payload JSON e das credenciais do comerciante.

Valide o payload de solicitação exato com as credenciais e o procedimento de verificação fornecidos durante o onboarding antes de confiar no payload. Não dependa de nomes de cabeçalho alternativos ou de auxiliares SDK não documentados.

Confirme e processe#

Retorne o status HTTP 200 ou outra resposta 2xx assim que a solicitação for validada e enfileirada de forma durável. Você pode retornar um corpo vazio. Se retornar JSON, a DEUNA aceita esta forma de resposta:

{
  "status": "success",
  "data": {
    "order_id": "merchant-order-123"
  }
}

Retorne apenas um identificador de pedido diferente e não vazio nesta resposta somente quando você pretende que a DEUNA substitua o identificador de pedido do comerciante.

Erros de rede, timeouts e respostas de falha podem causar uma nova tentativa de entrega. Não dependa de um intervalo de repetição fixo e não assuma a ordem de entrega. Torne o processamento idempotente e reconcilie cada snapshot com o estado de pagamento mais recente conhecido.

Teste no ambiente de sandbox#

1. Exponha um receptor HTTPS que registra os cabeçalhos da solicitação e o corpo não modificado.
2. Defina a URL de notificação de pedido assíncrona em uma solicitação sandbox Purchase V2, a menos que uma URL de nível de comerciante já esteja configurada.
3. Conclua um pagamento ou uma captura, reembolso ou anulação assíncrona que altere o status do pagamento.
4. Confirme a forma do payload, a cobertura de status configurada, o comportamento do cabeçalho assinado, a confirmação e o tratamento de duplicatas.

O fluxo de status do pedido não fornece a API genérica /webhook_endpoints ou o comando CLI local de encaminhamento. Teste-o produzindo alterações reais no estado de sandbox. Teste os webhooks de checkout dinâmico através das suas rotas de configuração e execução verificadas.