Skip to main content

​
Campos

CampoTipoDescrição
paymentIdUUIDIdentificador único
orderIdUUIDReferência ao pedido (relação 1:1)
organizationIdUUIDReferência à organização da empresa beneficiária
companyIdUUIDReferência à empresa beneficiária
externalProviderStringNome do provedor externo de pagamento
externalProviderIdStringID da transação no provedor externo
descriptionString?Descrição do pagamento
methodPaymentMethodMétodo de pagamento
channelPaymentChannelCanal em que o pagamento foi criado
cardJson?Metadados do cartão (quando aplicável)
pixJson?Metadados do PIX (quando aplicável)
amountIntValor do pagamento em centavos
dueDateDateTime?Data de vencimento
statusPaymentStatusStatus do pagamento
issuedAtDateTimeData de emissão
paidAtDateTime?Data em que o pagamento foi confirmado
overdueAtDateTime?Data em que o pagamento ficou vencido
canceledByUUID?Usuário que cancelou o pagamento, quando aplicável
canceledAtDateTime?Data de cancelamento
createdByUUID?Usuário que criou o registro, quando aplicável
createdAtDateTimeData de criação
updatedByUUID?Usuário que fez a última atualização, quando aplicável
updatedAtDateTimeData da última atualização

​
Relacionamentos

​
Regras de Negócio

  • Relação 1:1 com Order — cada pedido possui exatamente um pagamento.
  • 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) de pagamentos presenciais (POS).
  • 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.
  • O valor (amount) é armazenado em centavos.
  • status tem default PENDING.
  • organizationId e companyId identificam a empresa beneficiária do pagamento.

​
Enums

​
PaymentMethod

ValorDescrição
CASHDinheiro
PIXPagamento instantâneo via PIX
CREDIT_CARDCartão de crédito
DEBIT_CARDCartão de débito

​
PaymentChannel

ValorDescrição
ONLINEPagamento criado no canal digital
POSPagamento criado em venda presencial ou guichê

​
PaymentStatus

O status reflete o ciclo de vida da cobrança no provedor de pagamento. Default PENDING.
ValorDescrição
PENDINGPagamento criado, aguardando processamento
PROCESSINGEm processamento no provedor
ANTIFRAUD_PENDINGAguardando análise antifraude
ANTIFRAUD_MANUALEm análise antifraude manual
ANTIFRAUD_APPROVEDAprovado pela análise antifraude
ANTIFRAUD_REPROVEDReprovado pela análise antifraude
PAIDPagamento confirmado
UNDERPAIDPago a menor que o valor esperado
OVERPAIDPago a maior que o valor esperado
PARTIAL_CANCELEDParcialmente cancelado
CANCELEDCancelado
PAYMENT_FAILEDPagamento recusado ou falhou
REFUNDEDEstornado após confirmação
CHARGEDBACKSofreu chargeback

​
Example

{
  "paymentId": "0197a816-281b-72e7-8f50-286fbfc5c08d",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "organizationId": "0197a801-1690-7590-b3cf-19599b9be3e4",
  "companyId": "0197a801-6a42-79aa-9e56-d3c85148c0fa",
  "externalProvider": "billing_interface",
  "externalProviderId": "pay_4a817c90",
  "description": "Pedido OAB-20260703-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"
}