Saltar para o conteúdo principal
POST
Fecha o ciclo do pagamento diferido: o pedido nasceu aberto, a cozinha já trabalhou, e a cobrança chega aqui. O pedido passa a COMPLETED e o faturamento começa quando o valor aprovado atinge exatamente o total do pedido.
Uma cobrança com várias peças, numa única chamada. Se você dividir a conta entre dinheiro e cartão, envie as duas peças na mesma chamada: as peças aprovadas devem somar exatamente o total do pedido. Uma cobrança que não fecha a conta é rejeitada por inteiro e nada é registrado — consolide os seus parciais antes de enviá-los.Repetir é seguro e esperado: reenvie o envio inteiro e a idempotência por transaction_id cuida do resto.
Precisa corrigir o pedido antes de cobrá-lo —dados de faturamento do cliente, localizador—? Isso vai pelo Corrigir pedido, não por este endpoint. Este só registra o dinheiro; a diferença entre os dois está explicada lá.

​
Autenticação

​
string
obrigatório
Sua API key do Fire com scope orders:write. A key deve ser vendor-scoped — keys sem vendorId são rejeitadas com 403.

​
Path params

​
string
obrigatório
Qualquer uma das três referências públicas do pedido:É o mesmo conjunto aceito por Obter pedido e Cancelar pedido.

​
Corpo

​
object[]
obrigatório
Os meios com os quais você cobrou o pedido. Entre 1 e 20 peças. Cada objeto é guardado exatamente como você enviou; abaixo estão apenas os campos que o Fire lê.
​
string
obrigatório
Resultado da tentativa. Contam como cobrado: APPROVED, AUTHORIZED, CAPTURED, PAID, SUCCESS, SUCCEEDED (sem diferenciar maiúsculas).Qualquer outro valor é tratado como recusa, mesmo um que não reconheçamos. É deliberado: faturar uma cobrança que não aconteceu não tem volta, enquanto deixar de liquidar uma que aconteceu se resolve enviando de novo.
​
string
obrigatório
Identificador da transação. É a chave de idempotência: reenviar o mesmo não cobra nem fatura duas vezes. Se o seu meio não gerar um, o Fire usa payments[].uid.
​
number
obrigatório
Valor desta peça, decimal. Deve ser maior que zero. Se não vier, o Fire usa o payments[].total do nível superior.
​
string
obrigatório
Moeda da peça. Todas as peças aprovadas devem compartilhar a mesma — incluindo as de chamadas anteriores do mesmo pedido. Se não vier, o Fire usa o payments[].currency_code do nível superior.
​
string
Motivo da recusa, com um código de Motivos de recusa. Só se aplica quando transaction_status não é aprovado.O código do seu adquirente (51, do_not_honor) precisa ser traduzido do seu lado para o do catálogo: o Fire não guarda os códigos de cada provedor. Se você enviar um que não existe, ele é aceito e guardado, mas volta com resolvedTo: null e fica fora das suas métricas agrupadas.
​
string
Meio de pagamento (CASH, CREDIT, DEBIT, PIX…). Usado para o faturamento e as métricas.

​
Requisição

​
O que o Fire faz com isso

Só as peças aprovadas somam e liquidam. As recusadas são registradas para suas métricas; nunca somam e nunca bloqueiam a cobrança.
Tudo ou nada. Uma cobrança cujas peças aprovadas não somam o total do pedido é rejeitada por inteiro — nem sequer uma recusa que viajava no mesmo envio é guardada.O motivo não é contábil, é operacional: dinheiro aceito num pedido que não liquida deixa o pedido com dinheiro dentro e sem saída. O Fire não processa devoluções e não existe forma de você nos avisar que devolveu. Consolidar as cobranças parciais é tarefa sua — e você é o único que pode devolver, então esse estado é seu de qualquer jeito.Cobrar mais que o total é rejeitado por outro motivo: faturaria um valor que não foi o cobrado, e uma nota emitida não se desfaz. As duas mensagens trazem os dois valores para você corrigir e reenviar.As recusas são a exceção: um envio sem nenhuma peça aprovada é registrado e o pedido continua aberto. Sem dinheiro não há estado a resolver, e é ali que vivem as suas métricas de recusa.

​
O que aconteceu com cada recusa

Cada peça recusada volta em declines[], com o que você enviou e se encontramos no catálogo.
exceedsOrderTotal: true significa que o valor que você tentou cobrar supera o total do pedido. Não exigimos que cada peça seja igual ao total —numa cobrança dividida, $20 sobre $35,90 é legítimo— mas superá-lo nunca é: quase sempre significa que se está cobrando outro pedido. A recusa é o seu aviso de graça, porque se a próxima tentativa for aprovada liquidaria um valor que não corresponde. resolvedTo: null significa que aquele código não existe no catálogo — no exemplo, foi enviado o código cru do adquirente em vez do do Fire. A recusa foi registrada mesmo assim e o valor ficou guardado, mas não aparece em nada agrupado por motivo.
Confira este bloco na primeira integração. Um código mal traduzido não quebra nada: a cobrança funciona, a resposta é 200, e as suas recusas entram sem classificação. Você descobriria meses depois com o painel de motivos vazio.

​
Um pedido fechado não aceita mais nada

Um pedido recebe cobranças enquanto está aberto. Uma vez fechado está fechado, não importa como chegou lá. Uma peça que ele nunca viu é rejeitada e nada é registrado — aprovada ou recusada, dá no mesmo. O código de erro informa por que está fechado, e os dois pedem ações diferentes: O que separa uma rejeição de uma repetição é o transaction_id, não o estado do pedido:
Uma repetição nunca é rejeitada, de propósito. Você cobrou uma vez e a nossa resposta não chegou até você; responder com um erro ali empurraria o operador a passar o cartão de novo — a cobrança dupla que estamos tentando evitar. Envie o mesmo transaction_id e você recebe de volta o resultado original.

​
Quando a cobrança quita

Quitar é o que completa o pedido, então é aí que o Fire emite order.completed — o pedido nasceu OPEN e só agora terminou. A resposta informa isso como flowsTriggered. flowsTriggered: 0 não é um erro de cobrança. Significa uma de três coisas: Essa última linha é deliberada. Se o Fire respondesse com erro porque não conseguiu enfileirar um evento, você tentaria de novo uma cobrança que já entrou. O dinheiro manda sobre o aviso.
Um pedido com pagamento diferido já emitiu seu documento fiscal ao abrir, e passa de novo pela etapa fiscal em order.completed. O Fire detecta o documento existente e pula a segunda emissão — você não recebe duas notas.

​
Idempotência

Cada peça é identificada pelo seu transaction_id dentro do pedido. Pode repetir sem medo:
  • Reenviar a cobrança completa → duplicate. Nada é liquidado nem faturado de novo.
  • Reenviar após um timeout → reenvie o envio inteiro. Uma cobrança incompleta nunca foi registrada, e qualquer peça que tenha entrado é ignorada pelo seu transaction_id.

​
Validações

Todas retornam 400, salvo indicação em contrário. Cada rejeição traz um code além da mensagem: ramifique pelo código, não pelo texto — a mensagem é escrita para ser lida e pode ser reescrita, o código é contrato. Campos que o Fire não conhece são aceitos e guardados: você pode enviar seu objeto de pagamento completo sem recortar. A moeda de uma peça recusada nunca invalida o envio, porque não soma.

​
Respostas

​
Relacionado

Motivos de recusa

Catálogo agrupado para classificar as tentativas recusadas.

Obter pedido

Consulte o status e o total antes de cobrar.