Payment

​

Campos

​

Relacionamentos

• Relaciona-se com Order (1:1 via orderId único).
• Pode ser referenciado 1:1 por CompanyCreditPurchase.
• Relaciona-se com Organization.
• Relaciona-se com Cooperative.
• Relaciona-se opcionalmente 1:1 com CashSettlement por cashSettlementId único.
• Relaciona-se com múltiplos Receivable.

​

Regras de Negócio

• Payment representa uma cobrança de Order ou de CompanyCreditPurchase.
• Relação 1:1 opcional com Order — cada pedido possui no máximo um pagamento.
• Relação 1:1 com CompanyCreditPurchase — cada compra corporativa possui exatamente um Payment no fluxo novo.
• Orders com paidAmount = 0, quitados integralmente por crédito corporativo, podem não gerar Payment.
• organizationId e cooperativeId identificam a cooperativa beneficiária do pagamento.
• Para CompanyCreditPurchase, a Company pagadora permanece na compra e a Cooperative beneficiária permanece no Payment.
• O par externalProvider + externalProviderId evita duplicidade de transações externas.
• Os campos card e pix armazenam metadados específicos do método de pagamento em formato JSON.
• channel diferencia pagamentos criados no canal digital (ONLINE), presenciais (POS) ou pelo app do motorista (DRIVER_APP).
• Quando channel = POS e method = CASH, o pagamento pode nascer já confirmado.
• Quando channel = POS e method usa gateway (PIX, CREDIT_CARD, DEBIT_CARD), a confirmação continua seguindo o ciclo do provedor.
• Quando channel = DRIVER_APP e method = CASH, o pagamento nasce PAID quando o recebimento do dinheiro é confirmado.
• O CashSettlement é criado e enviado automaticamente quando uma CheckoutSession CASH é confirmada.
• cashSettlementId fica null enquanto o CashSettlement está PENDING ou REJECTED.
• A confirmação pela OPS preenche cashSettlementId e altera o CashSettlement para CONFIRMED na mesma transação.
• Cada Payment pode reconciliar no máximo um CashSettlement, e cada CashSettlement confirmado referencia exatamente um Payment.
• Crédito corporativo não é PaymentMethod; o uso é capturado em CreditLedgerEntry. O Payment só representa a parcela externa ou em dinheiro do Order.
• O valor (amount) é armazenado em centavos.
• status tem default PENDING.

​

Enums

​

PaymentMethod

​

PaymentChannel

​

PaymentStatus

​

Example

{
  "paymentId": "0197a816-281b-72e7-8f50-286fbfc5c08d",
  "orderId": null,
  "organizationId": "0197a7f7-7291-7a43-96db-2c8580b80c5d",
  "cooperativeId": "0197a800-24e6-76a2-90ed-ff0f6fba7b0c",
  "cashSettlementId": null,
  "externalProvider": "billing_interface",
  "externalProviderId": "pay_4a817c90",
  "externalOrderId": "order_4a817c90",
  "description": "Compra de créditos CCP-20260704-0001",
  "method": "PIX",
  "channel": "ONLINE",
  "card": null,
  "pix": {
    "qrCode": "00020101021226860014br.gov.bcb.pix2564pix.example.com/charge/pay_4a817c90",
    "expiresAt": "2026-07-03T16:30:00.000Z"
  },
  "amount": 11400,
  "dueDate": "2026-07-03T16:30:00.000Z",
  "status": "PAID",
  "issuedAt": "2026-07-03T16:00:30.000Z",
  "paidAt": "2026-07-03T16:02:00.000Z",
  "overdueAt": null,
  "canceledBy": null,
  "canceledAt": null,
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-03T16:00:30.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-03T16:02:00.000Z"
}