Pular para o conteúdo principal
Nesta página

Os webhooks da DEUNA abrangem dois fluxos diferentes de servidor para servidor: notificações que publicam alterações de estado de pagamento para seu backend e callbacks síncronos que permitem que a DEUNA solicite dados ou lógica específicos do comerciante durante o checkout. Escolha o fluxo de acordo com o que sua integração precisa realizar.

FluxoQuando ele é executadoUse-o para
Notificação de status de pedido e pagamentoApós uma alteração no status de pagamento inscritoAtualize o estado de fulfillment, reconciliação e pedido do cliente sem fazer polling continuamente.
Webhook dinâmico de checkoutEnquanto o checkout aguarda uma resposta do comercianteAplique cupons ou descontos por cartão, calcule gorjetas ou impostos, consulte informações de entrega ou valide dados.

Redirecionamentos de navegador, callbacks do SDK e callbacks de provedor para DEUNA são superfícies de integração separadas. Não os use como prova de pagamento ou como substitutos para esses fluxos de backend.

Notificações de status de pedido e pagamento#

As notificações de status entregam o snapshot mais recente do pedido ao seu backend quando o status de pagamento normalizado corresponde a um evento inscrito para o merchant. Essas notificações são assíncronas: o ciclo de vida do pagamento não aguarda a conclusão da sua lógica de negócio.

01 · state
Alterações de status de pagamento
A DEUNA registra um resultado de pagamento normalizado, como processado, autorizado, capturado, negado, cancelado ou reembolsado.
02 · subscription
O evento é selecionado
O status do pagamento se torna um evento chamado Pagamento <status>, e a DEUNA verifica a assinatura do merchant.
03 · delivery
O snapshot do pedido é enviado
A DEUNA envia a requisição configurada para o destino do merchant.
04 · receiver
Seu backend reconcilia
Seu servidor verifica a assinatura, reconhece a requisição e processa a atualização de forma idempotente.

Configurar entrega de status

Defina o contrato de entrega para cada ambiente:

ConfiguraçãoO que definir
DestinoO endpoint HTTPS que aceita notificações de status.
EventosO payment.<status> eventos exigidos pelo seu ciclo de vida do pedido.
Contrato da requisiçãoQuaisquer headers estáticos, parâmetros de URL e transformação de payload aprovada.
Tratamento de falhasO comportamento de confirmação, retentativa, monitoramento e reconciliação acordado para a integração.

Os eventos disponíveis seguem o ciclo de vida de pagamento documentado em Fluxo e status de pagamento. A cobertura de eventos pode variar por método de pagamento porque nem todo método suporta cada operação ou status de pagamento.

Carga útil padrão

Sem uma transformação personalizada do payload, a DEUNA envia um HTTP POST com Content-Type: application/json e o pedido atual sob a propriedade order :

Notificação de status do pedidoJSON
{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "processed",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "processed",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

O pedido pode conter os dados de cliente, item, valor, pagamento, processador, fraude, metadados e campo personalizado associados a essa transação. Trate order.payment.data.status como o estado de pagamento autoritativo, e use order.token, order.order_ide os identificadores de transação aplicáveis para reconciliação.

Uma configuração específica do lojista pode alterar o método HTTP, headers, parâmetros de URL, status assinados e formato do payload. Se uma configuração personalizada estiver habilitada, implemente o contrato exato certificado para esse lojista em vez de assumir o corpo padrão.

Verifique a assinatura

A entrega atual adiciona um X-Signature cabeçalho. Isso substitui exemplos mais antigos que se referem a X-Deuna-Signature.

  1. Leia o corpo da requisição não modificado antes que um framework o analise ou resserialize.
  2. Aplique o procedimento de verificação HMAC-SHA256 e Base64 certificado para o fluxo e ambiente de entrega.
  3. Compare o valor calculado com X-Signature usando uma comparação de tempo constante.
  4. Rejeite a requisição antes do processamento se os valores não corresponderem.

Notificações de status e webhooks dinâmicos nem sempre assinam a mesma entrada quando a transformação de payload está ativada. Não reutilize um verificador entre esses fluxos até que a entrada assinada e a derivação da chave tenham sido confirmadas durante a certificação.

Mantenha as chaves de API privadas no servidor. Nunca as coloque em código de navegador, aplicativos móveis, logs ou respostas de webhook.

Reconheça e reconcilie

  1. Verifique a assinatura antes de confiar no payload.
  2. Registre uma chave de deduplicação que inclua o token do pedido e o evento ou status de pagamento resultante.
  3. Retorne uma resposta 2xx bem-sucedida assim que a requisição for aceita de forma durável.
  4. Releia ou reconcilie o estado autoritativo do pedido antes de cumprimento, cancelamento, captura, reembolso ou outra ação irreversível.
  5. Ignore uma notificação que moveria seu registro local para trás a partir de um estado mais recente.

Falhas de entrega podem ser repetidas. Não assuma entrega exatamente uma vez, um intervalo de repetição fixo ou chegada na ordem do ciclo de vida.

Webhooks de checkout dinâmico#

Webhooks dinâmicos são callbacks síncronos e específicos do lojista. Quando o checkout dispara um evento configurado, a DEUNA envia uma requisição assinada para seu endpoint, valida a resposta, aplica apenas as atualizações permitidas e retorna o resultado configurado para o checkout.

Webhooks dinâmicos são ativados e configurados como parte da implementação do lojista. Eles não são registrados a partir de código de navegador ou móvel.

Fluxo de configuração e execução

Configure o webhook com a DEUNA como parte da configuração do seu lojista. Combine o nome do evento, destino, formatos de requisição e resposta, regras de validação e campos que o callback pode atualizar. Após a configuração, o checkout pode executar o evento através do mesmo contrato acordado.

Diagrama de sequência
1Merchant team andbackend2DEUNA3Checkout UIConfigure event, endpoint,contract, and allowedupdatesTrigger the configured eventwith order and inputSend the signed requestReturn the agreed JSONresponseValidate the responseand apply permittedupdatesContinue with the configuredresult
Comerciante ou clienteDEUNA

Se o evento não estiver configurado para o lojista e ambiente, a DEUNA não chama seu endpoint. Trate um callback obrigatório que não foi executado como um problema de configuração durante a certificação.

Capacidades de configuração

ConfiguraçãoRequisitoO que controla
event_nameObrigatórioNome de evento específico do comerciante que usa letras, números, hífens ou sublinhados. Configure seu acionamento separadamente.
urlObrigatórioDestino do endpoint do comerciante. Use HTTPS na integração.
http_methodOpcionalMétodo HTTP: GET, POST, PUT, ou PATCH. O padrão é POST.
headersOpcionalArray de pares de key e value para cabeçalhos adicionais da solicitação. Os valores podem usar templates do pedido.
params, query_paramsOpcionalArrays de pares de key e value para marcadores de posição da URL e parâmetros de consulta. Os valores podem usar templates do pedido.
payload_templateOpcionalCria a solicitação JSON ao comerciante a partir do pedido atual e dos dados do evento. Sem esse template, o corpo da solicitação contém apenas os dados do evento.
response_templateOpcionalMapeia o JSON do comerciante para o contrato de resposta do pedido. Omita se seu endpoint já retorna esse contrato.
response_dataObrigatório com response_templateJSON codificado como string, usado para validar o template de resposta durante a configuração. Não é a resposta do comerciante durante a execução.
error_response_templateOpcionalMapeia um formato alternativo de erro do comerciante. Sem esse template, as respostas de erro do comerciante usam code e message.
fields_update.fieldsOpcionalArray de atualizações permitidas no pedido. Inclua cada valor, lista de descontos ou campo de item que o callback deve substituir. Consulte os campos de preços abaixo.
fields_update.custom_fieldsOpcionalArray de nomes de campos personalizados que podem ser alterados. Os campos devem estar declarados e os valores retornados devem atender ao esquema de campos personalizados do pedido.
response_body.fieldsObrigatório ao criar a configuraçãoAceita Order, ShippingRate, e ShippingMethods. A resposta mapeada inclui o pedido; essa lista também seleciona resultados adicionais de frete. Ela não restringe quais propriedades aparecem dentro do pedido.
response_body.custom_fieldsOpcionalArray de nomes de campos personalizados declarados que serão incluídos no resultado do checkout. É independente da permissão para atualizar esses campos.
propagate_responseOpcionalO padrão é false. Mantenha como false para atualizações do pedido; a alternativa inclui o JSON do comerciante em dynamic_response em vez do resultado do pedido mapeado.

Configure as atualizações de preços

Os nomes dos campos de configuração e os caminhos JSON da resposta são diferentes. Selecione apenas as atualizações necessárias para sua promoção:

Valor em fields_update.fieldsDados da resposta do comercianteComportamento da atualização
TotalAmountorder.total_amountSubstitui o total a pagar.
TotalDiscountorder.total_discountSubstitui o valor total de desconto.
Discountsorder.discountsSubstitui todo o array de descontos do pedido.
Items.TotalAmountorder.items[].id, order.items[].total_amountLocaliza os itens existentes pelo ID e atualiza seu valor, valor original e desconto total.
Items.Discountsorder.items[].id, order.items[].discountsLocaliza os itens existentes pelo ID e substitui suas referências de descontos.
Shippingorder.shippingSubstitui o valor original do frete, seu desconto total e as referências de descontos.

O webhook atribui esses valores de forma independente. Ele não recalcula o total a pagar, os descontos acumulados ou a distribuição por item a partir da lista de descontos. Retorne todos os campos permitidos em cada chamada bem-sucedida. Omitir um campo selecionado pode zerar um valor ou limpar uma lista; não é uma instrução de atualização parcial.

O trecho a seguir mostra o núcleo de uma definição de cálculo de gorjeta. São dados de configuração, não uma solicitação que deve ser enviada do navegador:

Trecho de configuração dinâmica de webhookJSON
{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

Durante a execução, o checkout pode fornecer entrada específica do evento:

Entrada do eventoJSON
{
  "data": {
    "tip_amount": 500
  }
}

Sem um modelo de payload, o endpoint do lojista recebe esses dados do evento. Com um modelo de payload, o modelo pode usar tanto o pedido atual quanto a entrada do evento para construir o JSON de saída.

Implemente o endpoint do lojista

PreocupaçãoRequisito do endpoint do lojista
Execução repetidaProcesse dados repetidos de forma idempotente. Recalcule quando os dados da promoção mudarem.
Contrato de respostaRetorne JSON que corresponda ao formato de resposta configurado ou ao modelo de resposta.
Campos obrigatóriosInclua todos os campos de atualização configurados, inclusive valores zero ao remover um desconto.
LatênciaConclua dentro do tempo limite certificado para a integração porque o checkout aguarda a resposta.
ErrosRetorne uma resposta não-2xx para uma falha de negócio ou de processamento, usando o formato de erro configurado.

Chamadas dinâmicas incluem X-Signature e X-Deuna-Operation. Quando um modelo de payload altera o corpo de saída, use a entrada de verificação de assinatura acordada durante a certificação; não assuma que é idêntica ao contrato de notificação de status acima.

Com a propagação de respostas desativada, a resposta do comerciante pode conter order, shipping_rate, e shipping_methods. A DEUNA retorna o pedido mapeado e os resultados adicionais configurados. Com a propagação ativada, a resposta do comerciante deve ser um JSON válido e é exposta em dynamic_response. Use o fluxo mapeado para recalcular o preço do pedido.

Padrões práticos

Descontos por cartão

Use um webhook dinâmico de checkout para aplicar uma promoção com base no cartão informado durante o checkout. Seu backend determina a elegibilidade e calcula o desconto; a DEUNA aplica as atualizações configuradas no pedido antes do pagamento.

Seu backend gerencia os números de identificação bancária (BINs), as bandeiras de cartão e as regras de desconto elegíveis. Seu DEUNA Technical Account Manager (TAM) não precisa dessa lista de elegibilidade. A DEUNA chama o endpoint quando o acionamento configurado é executado; seu endpoint avalia cada solicitação e retorna o pedido com desconto ou o pedido sem essa promoção.

Um callback configurado antes do pagamento é executado antes de cada solicitação de pagamento nesse fluxo configurado, sem filtro de elegibilidade por BIN na DEUNA. Um callback de detecção de BIN pode ser executado antes para atualizar o preço do checkout quando o cliente informa ou altera um cartão. Confirme com a DEUNA o momento de execução do callback e os dados da solicitação.

Conclua o recálculo do preço e atualize o pedido antes de o checkout montar a solicitação de pagamento. Atualizar os totais salvos do pedido dentro de um callback anterior ao pagamento não recria automaticamente os valores já incluídos nessa solicitação de pagamento.

O exemplo abaixo usa a detecção de BIN. A digitação do cartão pode gerar um evento de BIN após os seis primeiros dígitos, antes de o cliente preencher todos os dados do cartão. A detecção do BIN não confirma que o cartão completo seja válido nem que um pagamento tenha sido autorizado.

Diagrama de sequência
1Checkout2DEUNA3Backend da lojaBIN do cartão detectado oualteradoExecuta o evento de descontoconfiguradoSolicitação assinada compedido e dados do cartãoAvalia a elegibilidade ecalcula os totaisCartão elegívelTotais reduzidos e lista dedescontosCartão inelegívelTotais e descontos sem estapromoçãoSalva as atualizaçõespermitidas do pedidoPedido e totais atualizadosExibe o preço e monta asolicitação de pagamentoEnvia o pagamento com ototal atualizado
Comerciante ou clienteDEUNA

Configure e implemente este fluxo em cada ambiente:

  1. Configure o webhook com a DEUNA. Informe ao seu DEUNA Technical Account Manager (TAM) o destino HTTPS e a solicitação e resposta esperadas. Defina em conjunto o nome do evento, o momento de execução do callback, a verificação de assinatura, o tempo limite, o tratamento de erros e os campos do pedido que a resposta pode atualizar. Mantenha a elegibilidade da promoção e o cálculo do desconto no seu backend.
  2. Conecte o acionamento acordado. Para um callback anterior ao pagamento, configure sua execução com a DEUNA para o fluxo de pagamento necessário. Para o exemplo de detecção de BIN abaixo, coordene a integração do checkout para que um BIN detectado ou alterado execute o evento acordado. Apenas registrar um webhook não o conecta à digitação do cartão. No Payment Widget e no Elements do Web SDK, onCardBinDetected disponibiliza cardBin e cardBrand; consulte a referência de callbacks do Web SDK. O callback do cliente e o webhook entre servidores são etapas separadas.
  3. Implemente o endpoint do comerciante. Verifique a solicitação assinada e avalie a promoção no seu servidor usando os dados de pedido e BIN acordados. Mantenha as credenciais privadas no servidor e não solicite o número completo do cartão nem o código de segurança para este fluxo. Trate chamadas repetidas sem acumular o mesmo desconto.
  4. Retorne o pedido recalculado. Retorne o total a pagar revisado, o desconto acumulado e o array completo de descontos na resposta JSON acordada. Configure as três atualizações permitidas mostradas abaixo e retorne o pedido mapeado ao checkout. Defina em conjunto um template de resposta se seu endpoint usar outro formato e desative a propagação de respostas para essa atualização.
  5. Atualize o preço antes do pagamento. Exiba o pedido retornado pela DEUNA e use o total revisado para o pagamento. Defina em conjunto como o checkout remove ou recalcula a promoção quando o cliente altera ou apaga o cartão. Defina se o checkout tenta novamente, bloqueia o pagamento ou continua sem a promoção se o callback falhar.

Por exemplo, uma promoção de 10% em um pedido de USD 100.00 sem outras cobranças gera um desconto de USD 10.00 e um total a pagar de USD 90.00. Seu endpoint deve calcular totais consistentes; retornar apenas um indicador de elegibilidade não altera o valor do pedido.

Exemplo de contrato de solicitação e resposta

O exemplo a seguir considera um pedido sem outros descontos ou cobranças. O nome do evento e o formato da solicitação de saída são um exemplo de acordo com o comerciante, não um evento integrado de desconto por cartão nem um esquema padrão para todos os comerciantes. Confirme o contrato e a integração do checkout com seu TAM antes de usá-lo.

Os valores são inteiros nas unidades mínimas da moeda do pedido: 10000 representa USD 100.00. Mantenha o BIN como uma string para preservar os zeros à esquerda.

O checkout fornece estes dados ao executar o evento acordado:

Dados do checkout para o evento de exemplo card_discountJSON
{
  "data": {
    "cardBin": "411111",
    "cardBrand": "visa"
  }
}

Configure o mapeamento a seguir com a DEUNA. Este é um trecho de configuração, não uma solicitação do navegador. O template do payload combina o pedido atual com os dados do evento; sem ele, o comerciante recebe apenas os dados do evento.

Exemplo de configuração do webhook de desconto por cartãoJSON
{
  "event_name": "card_discount",
  "url": "https://merchant.example.com/checkout/card-discounts",
  "http_method": "POST",
  "payload_template": "{\"order_token\":\"{{ .Order.Token }}\",\"order_id\":\"{{ .Order.OrderID }}\",\"currency\":\"{{ .Order.Currency }}\",\"total_amount\":{{ .Order.TotalAmount }},\"cardBin\":\"{{ .Payload.cardBin }}\",\"cardBrand\":\"{{ .Payload.cardBrand }}\"}",
  "fields_update": {
    "fields": ["TotalAmount", "TotalDiscount", "Discounts"]
  },
  "response_body": {
    "fields": ["Order"]
  },
  "propagate_response": false
}

O endpoint do comerciante recebe uma solicitação equivalente ao cURL a seguir. A DEUNA fornece os valores dos cabeçalhos de assinatura e operação. Confirme a verificação de assinatura para payloads transformados com seu TAM.

curl --request POST 'https://merchant.example.com/checkout/card-discounts' \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: SIGNATURE_FROM_DEUNA' \
  --header 'X-Deuna-Operation: OPERATION_FROM_DEUNA' \
  --data '{
    "order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "currency": "USD",
    "total_amount": 10000,
    "cardBin": "411111",
    "cardBrand": "visa"
  }'

Os campos do pedido identificam o pedido cujo preço está sendo recalculado; os campos do cartão contêm os dados do evento. Valide os dados no seu servidor e use suas regras oficiais de preços e promoções. Recalcule a partir do valor base da promoção do pedido, pois o total recebido pode já incluir um desconto de uma chamada anterior. Defina em conjunto como tratar uma bandeira desconhecida ou um BIN vazio quando o cartão for apagado.

Para um cartão elegível, retorne a resposta a seguir com um status HTTP de sucesso e um corpo JSON:

Resposta do comerciante: cartão elegívelHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 9000,
    "total_discount": 1000,
    "discounts": [
      {
        "amount": 1000,
        "code": "CARD_PROMO",
        "reference": "merchant-promotion-123",
        "description": "Card promotion",
        "type": "order_value",
        "discount_category": "promotion"
      }
    ]
  }
}
Campo da respostaTipo JSONObrigatório neste exemploSignificado
order.total_amountintegerSimTotal final a pagar nas unidades mínimas da moeda, após o desconto.
order.total_discountintegerSimDesconto total nas mesmas unidades, incluindo a promoção por cartão.
order.discountsarray de objetosSimLista completa de descontos a salvar no pedido. Um array vazio limpa essa lista.

Retorne os três campos configurados em cada chamada bem-sucedida, incluindo as que removem a promoção. Para um cartão inelegível neste exemplo, retorne:

Resposta do comerciante: sem desconto por cartãoHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 10000,
    "total_discount": 0,
    "discounts": []
  }
}

A DEUNA atualiza apenas os campos permitidos por fields_update e retorna o pedido salvo em order ao checkout. A resposta do comerciante acima contém os três campos de atualização; a resposta ao checkout contém o pedido com os demais campos preservados. Se outras promoções se aplicarem, preserve-as na lista de descontos retornada e recalcule os totais. Retorne uma lista vazia e desconto acumulado zero apenas quando não houver mais descontos.

Contrato do objeto de desconto

Cada entrada do array de descontos do pedido descreve um desconto aplicado. Use valores inteiros em unidades monetárias mínimas; uma promoção percentual deve retornar seu valor monetário calculado. O contrato de descontos mapeado aceita os seguintes campos:

Campo de descontoTipo JSONSignificado
amountintegerValor monetário aplicado por este desconto.
code, referencestringCódigo de promoção e identificador de referência do comerciante.
description, details_urlstringDescrição e link opcional para os detalhes da promoção.
typestringTipo de desconto: order_value, product, ou free_shipping.
discount_categorystringClassificação do desconto definida pelo comerciante.
target_typestringComponente de destino, quando aplicável: item ou shipping.
free_shippingobjectDetalhes da promoção de frete: is_free_shipping é um booleano; maximum_cost_allowed é um inteiro em unidades monetárias mínimas.

Esses campos descrevem o resultado da sua lógica de promoção; eles não configuram BINs elegíveis nem fazem a DEUNA calcular um desconto. Inclua os campos exigidos pelo contrato acordado. As listas de descontos de itens e frete usam objetos de referência que contêm amount e ref_idx; elas não repetem o objeto completo de desconto do pedido. Mantenha essas referências consistentes com os descontos do pedido retornados.

Em caso de falha de cálculo ou processamento, retorne um status HTTP diferente de 2xx. Sem um mapeamento de erros personalizado, use o corpo de erro mostrado abaixo. O status ilustra uma falha temporária e o código de erro é definido pelo comerciante:

Resposta de erro do comercianteHTTP
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "code": "PROMOTION_UNAVAILABLE",
  "message": "Unable to calculate the card promotion."
}

Defina em conjunto um error_response_template se seu endpoint usar outro formato de erro. Um cartão inelegível é um resultado normal sem desconto, não uma falha de processamento. O checkout deve seguir o comportamento de falha acordado na etapa 5, em vez de presumir que um desconto foi aplicado.

Exemplo de cálculo de gorjeta

Este exemplo mostra o caminho completo do checkout para o lojista para um evento de gorjeta configurado.

Diagrama de sequência
1Shopper + checkoutUI2DEUNA3Backend da lojatip_amount_updated + ordertokenSigned request with order +tip inputRecalculated total + tipfieldValidate response andapply permittedupdatesUpdated order + tip resultDisplay the new total
Comerciante ou clienteDEUNA

Para uma definição de gorjeta, permita apenas o valor e os campos personalizados que se espera que a resposta do lojista altere. O endpoint do lojista permanece responsável por calcular um total de pedido consistente.

Teste no ambiente de sandbox#

Testar notificações de status

Testar um webhook dinâmico

Teste um desconto por cartão

Conclua as verificações do webhook dinâmico e verifique o fluxo de digitação do cartão antes de habilitar a promoção em produção:

Nesta seção