Pagamentos na entrega

O objeto intended_payments concentra o que foi combinado para o pagamento da comanda. Ele é retornado mesmo quando ainda não existe um pagamento em payments. Uma integração pode usar essa informação para preparar a cobrança do entregador.

A intenção não registra recebimento. O array payments continua representando os pagamentos lançados, com valores líquidos, troco devolvido e, quando configuradas, previsões de repasse.

Onde consultar

Rota	Resposta
`GET /v1/table-sessions`	Array de comandas, com o limite legado de três dias inteiros.
`GET /v2/table-sessions`	Comandas em `data`, com cursor e intervalo sem o limite de três dias.
`GET /v1/table-sessions/:sessionId`	Detalhe de uma comanda pelo ID interno, sem exigir datas.

As três rotas usam table-sessions:read para integrações. Obtenha um access token por API key ou OAuth, e envie-o como Bearer. Informe o restaurante autorizado em restaurant_id, conforme o escopo do token. Os mesmos guards de restaurante e marca continuam valendo. Veja também paginação.

Campos do objeto

intended_payments é um objeto sempre presente na versão que implementa esta adição. Os nomes abaixo ficam dentro dele, sem cópias na raiz da comanda.

Campo	Tipo	Significado
`payment_method`	Objeto ou `null`	Forma selecionada para o pedido, independente dos métodos dos pagamentos já registrados.
`payment_method.id`	Inteiro	ID da forma selecionada.
`payment_method.name`	String	Nome de exibição da forma. Não use o nome para concluir que o pedido está pago.
`payment_method.keyword`	String	Identificador da forma, como `dinheiro`, `pix`, `visa_credito` ou `credit_card_auto`.
`payment_method.method`	String ou `null`	Instrumento, quando cadastrado: por exemplo, `CASH`, `CREDIT`, `DEBIT`, `PIX` ou `VOUCHER`.
`payment_method.brand`	String ou `null`	Bandeira cadastrada, quando aplicável.
`change_for`	String monetária ou `null`	Projeção do campo legado `user_change`. No checkout nativo, representa o valor que o cliente informou que entregará: troco para.
`is_prepaid`	Booleano	Sinalizador original de pré-pagamento da sessão, sem recálculo ou inferência por nome da forma.
`ifood_paid`	Booleano	Sinalizador legado de pagamento informado pela integração. O nome é histórico: outros canais também podem utilizá-lo.

Valores monetários usam strings com duas casas decimais. change_for preserva null, "0.00" e o valor informado; a API não substitui valores ausentes por zero. A forma é null quando ausente ou quando seu vínculo está contraditório. Não há fallback para o primeiro método encontrado em payments.

Exemplo: dinheiro ainda não recebido

Trecho sintético da resposta de uma comanda:

{
  "is_delivery": true,
  "with_withdrawal": false,
  "status": "open",
  "sales_channel": "TAKEAT",
  "total_delivery_price": "87.80",
  "intended_payments": {
    "payment_method": {
      "id": 161,
      "name": "Dinheiro",
      "keyword": "dinheiro",
      "method": "CASH",
      "brand": null
    },
    "change_for": "100.00",
    "is_prepaid": false,
    "ifood_paid": false
  },
  "payments": []
}

No checkout nativo, esse pedido pede cobrança de R$ 87,80, com troco para R$ 100,00. Sem pagamentos anteriores, o troco a preparar é R$ 12,20. change_for não é o troco já devolvido. Esse último fica em payments[].change.

Exemplo: cartão previsto

O objeto pode conter uma forma de cartão, mesmo antes de qualquer pagamento:

{
  "payment_method": {
    "id": 162,
    "name": "Visa Crédito",
    "keyword": "visa_credito",
    "method": "CREDIT",
    "brand": "VISA"
  },
  "change_for": null,
  "is_prepaid": false,
  "ifood_paid": false
}

Para um delivery com saldo positivo, essa forma permite orientar sobre uma maquininha compatível. A mesma forma pode permanecer no histórico depois do pagamento; sua presença isolada não comprova que ainda existe cobrança.

Regras usadas pelo Comandas

As orientações Maquininha e Troco a preparar são calculadas pelo app. Elas não são campos adicionais retornados pela API nem substituem a confirmação do recebimento.

Pedidos cancelados e retirada no balcão não geram preparação de cobrança do entregador.
Se is_prepaid ou ifood_paid for verdadeiro, o app informa o pré-pagamento declarado pela origem e evita orientar uma nova cobrança na entrega. Os pagamentos registrados e os totais financeiros continuam separados.
Se os pagamentos líquidos registrados já cobrirem o total, o app não prepara maquininha ou troco para uma nova cobrança.
Formas online conhecidas (pix_auto, credit_card_auto, online_ifood e online_takeat) não exigem maquininha de entrega. Sem confirmação de recebimento, o texto é Pagamento online previsto, não uma confirmação de pago.
Com saldo positivo e uma forma reconhecida de cartão, o app orienta levar maquininha. Para Pix ou dinheiro, informa que a maquininha não é necessária. Formas desconhecidas e indícios de um fluxo online não reconhecido exigem confirmação.
Na falta de intenção de pagamento ou de total de delivery, o app mostra Confirmar. Uma resposta de implantação anterior, sem intended_payments, continua legível e não ganha uma intenção inventada.

O saldo de referência é o total_delivery_price menos a soma dos payments[].payment_value. Esses valores já são líquidos do troco devolvido; não desconte payments[].change uma segunda vez. Use aritmética exata em centavos.

Para dinheiro do checkout nativo (sales_channel: "TAKEAT"), com saldo positivo:

change_for positivo e maior ou igual ao saldo: troco a preparar = change_for menos o saldo.
Com pagamentos parciais, use o saldo restante. Para total de R$ 87,80, R$ 20,00 já registrados e troco para R$ 100,00, o troco previsto é R$ 32,20.
change_for: "0.00": o checkout não registrou solicitação de troco.
change_for: null, negativo ou menor que o saldo: confirme o valor; não apresente troco negativo.

Integrações e limites

Integrações históricas podem gravar user_change com outra convenção, inclusive como valor do troco em vez do dinheiro entregue. A API preserva o dado original em change_for; não faz normalização retroativa por canal. O Comandas mostra Confirmar para o troco desses canais, incluindo origens não identificadas, e mantém o valor original visível nos detalhes. Confirme a convenção antes de calcular troco para outro canal.

Os exemplos são sintéticos. A publicação desta documentação não comprova que a mesma revisão da API já foi implantada no ambiente consultado. Esta adição é somente de leitura, não cria pagamentos e não exige novos escopos.