Webhooks
Receba notificações assinadas de status de pagamento e integre callbacks configuráveis de checkout.
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.
| Fluxo | Quando ele é executado | Use-o para |
|---|---|---|
| Notificação de status de pedido e pagamento | Após uma alteração no status de pagamento inscrito | Atualize o estado de fulfillment, reconciliação e pedido do cliente sem fazer polling continuamente. |
| Webhook dinâmico de checkout | Enquanto o checkout aguarda uma resposta do comerciante | Aplique 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.
Pagamento <status>, e a DEUNA verifica a assinatura do merchant.Configurar entrega de status
Defina o contrato de entrega para cada ambiente:
| Configuração | O que definir |
|---|---|
| Destino | O endpoint HTTPS que aceita notificações de status. |
| Eventos | O payment.<status> eventos exigidos pelo seu ciclo de vida do pedido. |
| Contrato da requisição | Quaisquer headers estáticos, parâmetros de URL e transformação de payload aprovada. |
| Tratamento de falhas | O 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 :
{
"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.
- Leia o corpo da requisição não modificado antes que um framework o analise ou resserialize.
- Aplique o procedimento de verificação HMAC-SHA256 e Base64 certificado para o fluxo e ambiente de entrega.
- Compare o valor calculado com
X-Signatureusando uma comparação de tempo constante. - 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
- Verifique a assinatura antes de confiar no payload.
- Registre uma chave de deduplicação que inclua o token do pedido e o evento ou status de pagamento resultante.
- Retorne uma resposta
2xxbem-sucedida assim que a requisição for aceita de forma durável. - Releia ou reconcilie o estado autoritativo do pedido antes de cumprimento, cancelamento, captura, reembolso ou outra ação irreversível.
- 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.
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ção | Requisito | O que controla |
|---|---|---|
event_name | Obrigatório | Nome de evento específico do comerciante que usa letras, números, hífens ou sublinhados. Configure seu acionamento separadamente. |
url | Obrigatório | Destino do endpoint do comerciante. Use HTTPS na integração. |
http_method | Opcional | Método HTTP: GET, POST, PUT, ou PATCH. O padrão é POST. |
headers | Opcional | Array de pares de key e value para cabeçalhos adicionais da solicitação. Os valores podem usar templates do pedido. |
params, query_params | Opcional | Arrays 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_template | Opcional | Cria 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_template | Opcional | Mapeia o JSON do comerciante para o contrato de resposta do pedido. Omita se seu endpoint já retorna esse contrato. |
response_data | Obrigatório com response_template | JSON 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_template | Opcional | Mapeia um formato alternativo de erro do comerciante. Sem esse template, as respostas de erro do comerciante usam code e message. |
fields_update.fields | Opcional | Array 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_fields | Opcional | Array 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.fields | Obrigatório ao criar a configuração | Aceita 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_fields | Opcional | Array de nomes de campos personalizados declarados que serão incluídos no resultado do checkout. É independente da permissão para atualizar esses campos. |
propagate_response | Opcional | O 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.fields | Dados da resposta do comerciante | Comportamento da atualização |
|---|---|---|
TotalAmount | order.total_amount | Substitui o total a pagar. |
TotalDiscount | order.total_discount | Substitui o valor total de desconto. |
Discounts | order.discounts | Substitui todo o array de descontos do pedido. |
Items.TotalAmount | order.items[].id, order.items[].total_amount | Localiza os itens existentes pelo ID e atualiza seu valor, valor original e desconto total. |
Items.Discounts | order.items[].id, order.items[].discounts | Localiza os itens existentes pelo ID e substitui suas referências de descontos. |
Shipping | order.shipping | Substitui 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:
{
"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:
{
"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ção | Requisito do endpoint do lojista |
|---|---|
| Execução repetida | Processe dados repetidos de forma idempotente. Recalcule quando os dados da promoção mudarem. |
| Contrato de resposta | Retorne JSON que corresponda ao formato de resposta configurado ou ao modelo de resposta. |
| Campos obrigatórios | Inclua todos os campos de atualização configurados, inclusive valores zero ao remover um desconto. |
| Latência | Conclua dentro do tempo limite certificado para a integração porque o checkout aguarda a resposta. |
| Erros | Retorne 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.
Configure e implemente este fluxo em cada ambiente:
- 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.
- 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,
onCardBinDetecteddisponibilizacardBinecardBrand; consulte a referência de callbacks do Web SDK. O callback do cliente e o webhook entre servidores são etapas separadas. - 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.
- 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.
- 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:
{
"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.
{
"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"
}'const response = await fetch("https://merchant.example.com/checkout/card-discounts", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
body: JSON.stringify({
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
})
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();import requests
response = requests.request(
"POST",
"https://merchant.example.com/checkout/card-discounts",
headers={
"Content-Type": "application/json",
"X-Signature": "SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation": "OPERATION_FROM_DEUNA"
},
json={
"order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id": "merchant-order-123",
"currency": "USD",
"total_amount": 10000,
"cardBin": "411111",
"cardBrand": "visa"
},
)
response.raise_for_status()
data = response.json()<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://merchant.example.com/checkout/card-discounts",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Signature: SIGNATURE_FROM_DEUNA",
"X-Deuna-Operation: OPERATION_FROM_DEUNA"
],
CURLOPT_POSTFIELDS => json_encode([
"order_token" => "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
"order_id" => "merchant-order-123",
"currency" => "USD",
"total_amount" => 10000,
"cardBin" => "411111",
"cardBrand" => "visa"
])
]);
$response = curl_exec($curl);
curl_close($curl);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("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")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
}
}package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
request, err := http.NewRequest("POST", "https://merchant.example.com/checkout/card-discounts", strings.NewReader("{\n \"order_token\": \"21ac49c0-d587-4f25-ae1c-0d60e540c1e8\",\n \"order_id\": \"merchant-order-123\",\n \"currency\": \"USD\",\n \"total_amount\": 10000,\n \"cardBin\": \"411111\",\n \"cardBrand\": \"visa\"\n }"))
if err != nil { panic(err) }
request.Header.Set("Content-Type", "application/json")
request.Header.Set("X-Signature", "SIGNATURE_FROM_DEUNA")
request.Header.Set("X-Deuna-Operation", "OPERATION_FROM_DEUNA")
response, err := http.DefaultClient.Do(request)
if err != nil { panic(err) }
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}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:
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 resposta | Tipo JSON | Obrigatório neste exemplo | Significado |
|---|---|---|---|
order.total_amount | integer | Sim | Total final a pagar nas unidades mínimas da moeda, após o desconto. |
order.total_discount | integer | Sim | Desconto total nas mesmas unidades, incluindo a promoção por cartão. |
order.discounts | array de objetos | Sim | Lista 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:
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 desconto | Tipo JSON | Significado |
|---|---|---|
amount | integer | Valor monetário aplicado por este desconto. |
code, reference | string | Código de promoção e identificador de referência do comerciante. |
description, details_url | string | Descrição e link opcional para os detalhes da promoção. |
type | string | Tipo de desconto: order_value, product, ou free_shipping. |
discount_category | string | Classificação do desconto definida pelo comerciante. |
target_type | string | Componente de destino, quando aplicável: item ou shipping. |
free_shipping | object | Detalhes 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:
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.
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: