Skip to main content
O Payment representa a cobrança financeira de um Order ou de uma CompanyCreditPurchase. Cada cobrança pertence à cooperativa beneficiária e o status evolui conforme o processamento avança no provedor ou conforme a confirmação interna de dinheiro.

​
State Machine

​
PaymentStatus

O PaymentStatus espelha o ciclo de vida da cobrança no provedor (default PENDING). Os estados operacionais principais:
O ciclo também contempla estados de antifraude e divergência de valor, como ANTIFRAUD_*, UNDERPAID, OVERPAID, PARTIAL_CANCELED e CANCELED. A lista completa está em data-modelling/Payment.

​
PaymentMethod

Boleto não faz parte dos métodos aceitos no modelo atual.

​
PaymentChannel

​
Criação e confirmação

O Payment pode nascer já confirmado (registro de um pagamento já efetuado) ou pendente (cobrança criada no provedor, confirmada depois). A confirmação assíncrona chega via webhook.
  • A confirmação assíncrona atualiza status, paidAt, canceledAt e overdueAt quando esses dados chegam pelo provider.
  • A integração financeira ocorre via Billing Provider.
  • Em venda POS, o pagamento continua 1:1 com Order. Pagamentos em dinheiro podem nascer confirmados; PIX e cartões seguem confirmação do gateway.
  • Em venda pelo app do motorista, method = CASH e channel = DRIVER_APP podem nascer PAID quando o motorista confirma o recebimento do dinheiro.
  • Orders quitados integralmente por crédito corporativo podem confirmar sem Payment; o uso fica no Credit Ledger por Ticket.
  • CompanyCreditPurchase sempre retorna seu Payment para polling e incorpora o saldo quando recebe payment.paid.
Um Payment com status PAYMENT_FAILED não cancela o Order automaticamente; o status pode ser reprocessado.

​
External Provider Tracking

O par externalProvider + externalProviderId identifica o pagamento externo e evita duplicidade de processamento.

​
Method-Specific Fields

Os campos card e pix armazenam metadados específicos do método:

​
Lifecycle Fields

​
Refund Flow

O estorno interno registra status = REFUNDED, canceledAt e canceledBy. Estornos originados no provedor chegam como atualização de pagamento com status REFUNDED ou CHARGEDBACK.
Não há cancelamento de recebíveis disparado pelo estorno. Os recebíveis refletem o estado reportado pelo provedor na próxima sincronização.

​
Recebíveis

Os recebíveis são sincronizados quando uma cobrança é confirmada e também pela rotina periódica de conciliação. Veja Receivables.

​
Dinheiro em prestação de contas

Pagamentos CASH podem confirmar o Order e emitir Ticket no momento da venda, mas ainda podem exigir prestação de contas posterior.
Cada CheckoutSession CASH cria e envia automaticamente um CashSettlement. O Payment permanece sem cashSettlementId até a OPS confirmar a prestação; nessa confirmação, o vínculo 1:1 é preenchido na mesma transação.

​
Relação com Order

Quando o webhook reporta cobrança paga (PAYMENT_PAID), o DEVMOB atualiza Payment, Order e recebíveis no mesmo fluxo financeiro. Pagamentos internos em dinheiro podem executar a confirmação sem webhook externo.
Crédito corporativo pode reduzir o valor pago pelo cliente, mas o lançamento definitivo do crédito fica em CreditLedgerEntry por ticketId. O Payment representa apenas a parcela externa ou em dinheiro do Order.

​
Relação com CompanyCreditPurchase

O Payment da compra corporativa usa channel = ONLINE, pertence à Cooperative escolhida e fica ligado 1:1 à CompanyCreditPurchase. Quando chega payment.paid, Credit Grant incrementa purchasedAmount e availableAmount da CompanyCreditAccount e preenche creditedAt de forma idempotente.