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)

Um pedido não precisa de itens: envie amount em vez de items para cobrar um valor fixo (uma fatura, um depósito, um link de pagamento com valor livre). Envie um ou outro, nunca os dois.

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, a InfraIO Pay 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

Estado	Significa
`PENDING`	Uma CheckoutSession está viva e ainda não resolvida.
`PAID`	Valor total liquidado. O webhook `payment.settled` dispara aqui. Seguro para entregar.
`PARTIAL_PAID`	O dinheiro chegou, mas menos que o total. Veja “Pagamento insuficiente” abaixo.
`CANCELED`	Sessão expirou ou o lojista cancelou. `metadata.canceled_reason` explica o motivo (`payment_timeout`, `merchant_canceled`, …).
`REFUNDED`	Todo o valor pago foi reembolsado.
`PARTIALLY_REFUNDED`	Algum 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 incluem external_ref. Para mapear um webhook payment.* de volta ao seu próprio registro, pegue order_id do payload e busque o pedido.

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:

Aceitar e resolver. Move o pedido para PAID e dispara order.resolved. Isso não está disponível pela API REST, então para um fluxo self-service use a opção 2 (cobrar o restante).
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.
Cancelar e reembolsar. Reembolse o valor parcial e cancele o Order. O comprador é responsável por quaisquer taxas de rede.

Reembolsos

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

Endpoints da API

Método	Path	Notas
`POST`	`/b2b/v1/orders`	Cria um Order sem sessão (raro)
`GET`	`/b2b/v1/orders/:order_id`	Lê o pedido completo com itens + histórico de pagamentos
`PATCH`	`/b2b/v1/orders/:order_id/cancel`	Cancela um pedido não pago
`PATCH`	`/b2b/v1/orders/:order_id/reopen`	Reabre um pedido auto-cancelado (`payment_timeout`)

Próximos passos

Conceitos → Sessões — a casca voltada ao comprador que envelopa um Order.
Conceitos → Reembolsos — estados de reembolso e o passo de envio manual on-chain.
Webhooks → Visão geral — todo evento disparado durante o ciclo de vida de um Order.