Skip to main content
O resgate tem duas pontas: o débito, que a DeliveryVip pede enquanto cria o pedido e que decide se o pedido nasce, e o estorno, que devolve o saldo quando o pedido termina cancelado, rejeitado ou sem pagamento.
O resgate é debitado dentro da transação do pedido; recusa faz rollback; se o pedido for cancelado, a DeliveryVip chama o estornoO resgate é debitado dentro da transação do pedido; recusa faz rollback; se o pedido for cancelado, a DeliveryVip chama o estorno

Resgate dentro da criação do pedido e estorno depois

​
Débito síncrono (redemptions)

Este é o débito autoritativo do saldo, chamado como última etapa dentro da transação de criação do pedido. Se você responder qualquer coisa diferente de 201, ou estourar o timeout, o pedido inteiro sofre rollback: o pedido não nasce, o cliente vê um aviso e o checkout continua sem o desconto.

​
Corpo da requisição

​
string
obrigatório
A conta do cliente, o id que você devolveu no link.
​
string
obrigatório
O UUID do pedido na DeliveryVip. É a chave de idempotência: um débito por pedido.
​
string
obrigatório
Sempre balance na v1.
​
number
obrigatório
Valor a debitar do saldo, como número JSON (até 2 casas; 25.0 e 25.00 são o mesmo número). É sempre o valor efetivamente descontado no pedido: pode ser menor do que o cliente reservou, se o carrinho encolheu. Já respeita os limites de resgate que você declarou.
​
object
obrigatório
Resumo do pedido para o seu extrato.
Exemplo

​
Limites já aplicados

Se você declarou redemptionLimits no programa, ou na conta, o amount que chega aqui já os respeita: nunca abaixo do mínimo, nunca acima do máximo. A aplicação acontece no checkout da DeliveryVip, antes desta chamada. Tetos percentuais são calculados sobre os itens do pedido (subtotal menos os demais descontos de carrinho), nunca sobre o total: frete e taxas não são resgatáveis. Se a sua própria regra incide sobre o total, o valor que chega aqui pode ser menor que o seu teto, nunca maior.
Isso não dispensa a sua validação: continue rejeitando com 422 e um code (ex.: below_minimum_order) o que as suas regras recusarem. Os limites declarados reduzem a chance de rejeição no checkout, mas a autoridade sobre o saldo e as regras é sempre sua.

​
Respostas do débito

Resposta (201)

​
Idempotência

  • O mesmo relatedOrderId com o mesmo amount deve responder 201 de novo, com o mesmo redemptionId.
  • O mesmo relatedOrderId com amount diferente deve ser rejeitado com 422 e code: "idempotency_conflict". Reserve o 409 para saldo insuficiente.
Timeout pós-débito: se você debitar mas a resposta se perder (timeout), o pedido não nasce do lado da DeliveryVip, e uma nova tentativa de checkout usa um order id novo, que a idempotência de relatedOrderId não cobre. A reconciliação desses casos é manual, pelo seu extrato: um débito cujo relatedOrderId não corresponde a nenhum pedido existente é candidato a estorno manual. Minimize a janela respondendo rápido (a chamada tem timeout de leitura de 5 s).

​
Estorno (reversal)

Devolve ao cliente o saldo do débito, por inteiro. A requisição não tem corpo: a assinatura é o HMAC da string vazia.
​
string
obrigatório
O redemptionId que você devolveu no 201 do débito.
A DeliveryVip dispara o estorno quando o pedido termina sem ser pago:
  • Cancelamento e rejeição do pedido;
  • Não-pagamento: pedidos que seguem aguardando pagamento 30 minutos depois de criados passam a não pagos, e o resgate é estornado. Falhas de cobrança que ainda podem ser tentadas de novo não disparam estorno, só a desistência definitiva.

​
O que o seu lado deve garantir

Não responda 404 para um resgate que você conhece mas já estornou: isso transforma um estorno concluído em caso de reconciliação manual. O 404 é só para “nunca vi este id”.
No acúmulo, um resgate estornado aparece no bloco loyalty do pedido com redemption.status: "REVERSED". Os totais do pedido continuam mostrando o desconto que ele custeava.