O Payment representa o pagamento de um Order. Cada Order pertence a uma única empresa e possui exatamente um Payment. O status evolui conforme o processamento avança no provedor de pagamento.
State Machine
PaymentStatus
O PaymentStatus espelha o ciclo de vida da cobrança no provedor (default PENDING). Os estados operacionais principais:
| Status | Descrição |
|---|
PENDING | Pagamento criado, aguardando processamento |
PROCESSING | Em processamento no provedor |
PAID | Pagamento confirmado |
PAYMENT_FAILED | Recusado ou falhou |
REFUNDED | Estornado após confirmação |
CHARGEDBACK | Sofreu chargeback |
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
| Método | Descrição |
|---|
CASH | Dinheiro |
PIX | Transferência instantânea via PIX |
CREDIT_CARD | Cartão de crédito |
DEBIT_CARD | Cartão de débito |
PaymentChannel
| Canal | Descrição |
|---|
ONLINE | Pagamento criado no canal digital |
POS | Pagamento criado em venda presencial ou guichê |
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.
Um Payment com status PAYMENT_FAILED não cancela o Order automaticamente; o status pode ser reprocessado.
External Provider Tracking
| Campo | Descrição |
|---|
organizationId | Organização da empresa beneficiária |
companyId | Empresa beneficiária |
externalProvider | Identificador do provider externo |
externalProviderId | ID da transação no provedor |
channel | Canal do pagamento: ONLINE ou POS |
externalProvider + externalProviderId identifica a transação externa e evita duplicidade de processamento.
Method-Specific Fields
Os campos card e pix armazenam metadados específicos do método:
| Campo | Quando usado |
|---|
card | Dados do cartão (bandeira, últimos 4 dígitos, parcelas) |
pix | Dados do PIX (QR code, txid) |
Lifecycle Fields
| Campo | Quando preenchido |
|---|
issuedAt | Momento da criação do pagamento |
dueDate | Data limite para pagamento (ex: PIX) |
paidAt | Momento da confirmação |
overdueAt | Quando venceu sem confirmação |
canceledAt | Momento do cancelamento/estorno |
canceledBy | Usuário que executou o cancelamento/estorno interno, quando aplicável |
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.
Quando o webhook reporta cobrança paga (PAYMENT_PAID), o DEVMOB atualiza Payment, Order e recebíveis no mesmo fluxo financeiro. 
