Skip to Content
ConceitosPedidos

Pedidos

Se a CheckoutSession é o que o comprador vê, o Order é o que você se importa. É o registro permanente de:

  • O que estava sendo comprado (itens)
  • Quanto foi devido e quanto já foi pago
  • Reembolsos pendentes e aplicados
  • A sua referência externa (external_ref) — tipicamente o ID do pedido do seu próprio sistema, armazenado no Order e retornado em GET /b2b/v1/orders/{id} (não ecoado nos payloads de webhook — veja abaixo)

Uma CheckoutSession morre depois que um dos seus PaymentIntents liquida ou o TTL expira. O Order vive para sempre.

Quando um Order é criado

Quando você chama POST /b2b/v1/checkout-sessions/quick, o payment-service cria ao mesmo tempo um Order novo e uma CheckoutSession nova em uma única transação. Se você já tem um Order e quer tentar o checkout de novo (por exemplo, depois que o comprador abandonou), use POST /b2b/v1/checkout-sessions no lugar para anexar uma sessão nova ao pedido existente — preservando a trilha de auditoria.

Ciclo de vida

EstadoSignifica
DRAFTReservado para um futuro fluxo de rascunhos. Nenhum caminho de código cria pedidos DRAFT hoje — todo pedido é criado PENDING, então você não vai observar esse estado.
PENDINGUma CheckoutSession está viva e ainda não resolvida.
PAIDValor total liquidado. O webhook payment.settled dispara aqui. Seguro para entregar.
PARTIAL_PAIDO dinheiro chegou, mas menos que o total. Veja “Pagamento insuficiente” abaixo.
CANCELEDSessão expirou ou o lojista cancelou. metadata.canceled_reason explica o motivo (payment_timeout, merchant_canceled, …).
REFUNDEDTodo o valor pago foi reembolsado.
PARTIALLY_REFUNDEDAlgum reembolso executado mas o saldo permanece pago.

O estado para acionar a sua lógica de entrega é PAID — não o COMPLETED da CheckoutSession. O webhook payment.settled é o sinal oficial.

O campo external_ref

Ao criar uma sessão você pode incluir external_ref (qualquer string de até 255 caracteres — tipicamente o ID do pedido do seu próprio sistema). Ele percorre toda a pipeline:

  • Armazenado no Order
  • Visível no dashboard do lojista para buscas de suporte
  • Retornado em GET /b2b/v1/orders/{id} para que um handler de webhook possa buscá-lo depois de receber payment.settled

Os payloads de webhook não ecoam external_ref diretamente hoje — rascunhos anteriores destes docs afirmavam que data.external_ref fluía para todo evento, e isso estava errado. Para mapear um webhook payment.* de volta ao registro no seu banco, pegue order_id do payload e busque o pedido. O campo nativo external_ref nos payloads de webhook está no roadmap.

Pagamento insuficiente

Se a transferência on-chain do comprador é confirmada por menos do que o total do pedido, o Order vai para PARTIAL_PAID. Você tem três opções:

  1. Aceitar e resolver. Move o pedido para PAID e dispara order.resolved. Isso não é um endpoint REST público — a resolução é uma ação interna/operacional hoje, então para um fluxo self-service prefira a opção 2 (cobrar o restante).
  2. Esperar o restante. Crie uma nova CheckoutSession contra o mesmo Order com amount_due = residual. O comprador paga a diferença; quando isso liquida, o Order vai para PAID.
  3. Cancelar e reembolsar. Reembolse o valor parcial e cancele o Order. O comprador é responsável por quaisquer taxas de rede.

O produto não fez uma recomendação aqui — lojistas diferentes querem políticas diferentes. Escolha uma e incorpore no seu admin.

Reembolsos

Reembolsos são uma superfície de API separada e uma página de conceitos separada. Veja Conceitos → Reembolsos.

Endpoints da API

MétodoPathNotas
POST/b2b/v1/ordersCria um Order sem sessão (raro)
GET/b2b/v1/orders/:order_idLê o pedido completo com itens + histórico de pagamentos
PATCH/b2b/v1/orders/:order_id/cancelCancela um pedido não pago
PATCH/b2b/v1/orders/:order_id/reopenReabre um pedido auto-cancelado (payment_timeout)

Próximos passos

SessõesReembolsos