VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Mini-loja WhatsApp: pedidos

Pagamento do pedido

Troca a forma de pagamento de um pedido que ainda não foi pago e consulta se o pagamento já foi confirmado.

Depois do checkout, o cliente pode precisar mexer no pagamento: o Pix venceu, o cartão foi recusado, ele prefere pagar de outro jeito. Estas duas rotas cobrem isso. Para tentar um cartão de novo, veja Pagar com cartão.

Trocar a forma de pagamento

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/paymentPública

Troca a forma de pagamento de um pedido não pago

Só pedidos aguardando pagamento ou com pagamento recusado podem trocar. Um pedido pago, enviado, entregue, cancelado ou de pagamento na entrega não troca (o campo can_change_payment do detalhe do pedido já diz). Entrega rápida só aceita forma online.

O total do pedido pode mudar com a nova forma: o servidor refaz a base do pedido (subtotal, frete, desconto e imposto) e aplica a taxa ou o desconto do método novo. Quando isso mudar o valor, a resposta traz total_cents e previous_total_cents. Trocando para Pix, a resposta já traz o código para pagar.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.
orderIDuuidobrigatório
Id do pedido.

Corpo da requisição

payment_methodstringobrigatório
code, slug ou id de uma forma de pagamento ativa da loja (veja as formas disponíveis). Até 128 caracteres.
invoiced_plan_idstring
Plano do boleto faturado. Obrigatório quando a nova forma é faturada.

O corpo recusa campos desconhecidos: qualquer chave além das duas acima responde 400 invalid_body.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33/payment" \
  -H "Content-Type: application/json" \
  -d '{"payment_method":"pix"}'

Resposta

200Pagamento trocado para Pix
json
{
  "ok": true,
  "payment_code": "pix",
  "payment_name": "PIX",
  "total_cents": 16387,
  "previous_total_cents": 17250,
  "auto_approved": false,
  "processor_type": "online",
  "can_change_payment": true,
  "pix": {
    "brcode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5913Loja Exemplo6009Sao Paulo62070503***6304ABCD",
    "qr_png_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

Campos da resposta

okboolean
true quando a troca foi gravada.
payment_codestring
Código da forma de pagamento agora gravada no pedido. payment_name é o nome.
total_centsinteger
Total do pedido depois da troca, em centavos.
previous_total_centsinteger
Total antes da troca.
auto_approvedboolean
true quando a nova forma é faturada com aprovação automática e o pedido já avançou de status.
processor_typestring
Tipo do processador da forma: online, offline, invoiced.
can_change_paymentboolean
O pedido ainda pode trocar de forma de pagamento.
pixobject
Presente quando a nova forma é Pix: brcode e qr_png_base64.

Erros

StatusQuandoCorpo
400Corpo ilegível, maior que 4 KB ou com campo desconhecido.{"error":"invalid_body"}
400payment_method vazio, inexistente, inativo ou de ponto de venda (PDV).{"error":"invalid_payment_method"}
400Boleto faturado sem plano.{"ok":false,"error":"invoiced_plan_required"}
400Entrega rápida com forma offline.{"ok":false,"error":"online_payment_required","message":"Entrega Rápida exige pagamento online"}
404O pedido não existe ou não é deste cliente.{"error":"order_not_found"}
409O pedido não pode mais trocar (pago, enviado, entregue, cancelado...).{"ok":false,"error":"payment_locked","stage":"out"}
409O cliente pediu cancelamento do pedido.{"ok":false,"error":"cancel_requested"}
409Já existe um Pix ou boleto gerado por outro valor, e a troca mudaria o total.{"ok":false,"error":"active_charge_exists","total_cents":17250,"message":"Já existe um Pix/boleto gerado para este pedido com outro valor. Fale com a loja para trocar a forma de pagamento."}
409O novo total não pôde ser recalculado com certeza. Nada foi gravado.{"ok":false,"error":"reprice_unavailable","total_cents":17250,"message":"Não foi possível recalcular o valor do pedido para essa forma de pagamento. Fale com a loja."}
412A forma usa o limite de crédito e o limite não cobre o novo total.{"ok":false,"error":"credit_limit_exceeded","limit_cents":50000,"available_cents":12000,"total_cents":16387,"message":"Limite de crédito insuficiente para este pedido."}
503Falha ao gravar.{"error":"post_sale_unavailable"}
Trocar de Pix para outra forma com valor diferente pode ser recusado

Se já existe um Pix ou boleto ainda válido, gerado com outro valor, a troca que mudaria o total é recusada (active_charge_exists): senão o código antigo continuaria podendo quitar o pedido pelo valor errado. Nesse caso o cliente fala com a loja.

Consultar se o pagamento caiu

GET/api/v1/storefront/wa-coex/pay/{token}/status/{orderID}Pública

Estado do pagamento de um pedido, para consulta repetida (polling)

Rota leve para consultar de poucos em poucos segundos enquanto o cliente paga: o Pix foi pago? O cartão em análise foi aprovado ou recusado? Só responde para pedido do próprio telefone.

Parâmetros de caminho

tokenstringobrigatório
Token da mini-loja.
orderIDuuidobrigatório
Id do pedido.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/wa-coex/pay/$TOKEN/status/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33"

Resposta

200Pagamento confirmado
json
{
  "payment_status": "C",
  "status": "A",
  "status_name": "Pago",
  "status_color": "#16a34a",
  "payment": { "state": "paid", "kind": "pix", "paid_at_unix": 1791745200 }
}

Campos da resposta

payment_statusstring
Status do pagamento em letra (P pendente, C pago, F recusado...).
statusstring
Letra do status do pedido. status_name e status_color são o nome e a cor na loja.
paymentobject
Estado do pagamento, no mesmo formato de payment do detalhe do pedido: state (paid, pending, analysis, refused, refunded, invoiced, on_delivery), kind e, conforme o caso, paid_at_unix, due_at_unix e card.

Erros

StatusQuandoCorpo
204O pedido não existe, não é deste telefone, ou o banco está fora.Sem corpo
Pare de consultar quando o estado for final

Consulte a cada poucos segundos e pare em paid, refused ou refunded. 204 não diz se o pedido existe: trate como "sem informação" e, passado um tempo, abra o detalhe do pedido.

Veja também

  • Pagar com cartão
  • Ver o pedido
  • Anexos do pedido
Anterior
Cancelar um pedido
Próxima
Anexos do pedido
Nesta página
  • Trocar a forma de pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar se o pagamento caiu
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também