> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment

> Pagamento único associado a um pedido

## Campos

| Campo                | Tipo             | Descrição                                              |
| -------------------- | ---------------- | ------------------------------------------------------ |
| `paymentId`          | `UUID`           | Identificador único                                    |
| `orderId`            | `UUID`           | Referência ao pedido (relação 1:1)                     |
| `organizationId`     | `UUID`           | Referência à organização da empresa beneficiária       |
| `companyId`          | `UUID`           | Referência à empresa beneficiária                      |
| `externalProvider`   | `String`         | Nome do provedor externo de pagamento                  |
| `externalProviderId` | `String`         | ID da transação no provedor externo                    |
| `description`        | `String?`        | Descrição do pagamento                                 |
| `method`             | `PaymentMethod`  | Método de pagamento                                    |
| `channel`            | `PaymentChannel` | Canal em que o pagamento foi criado                    |
| `card`               | `Json?`          | Metadados do cartão (quando aplicável)                 |
| `pix`                | `Json?`          | Metadados do PIX (quando aplicável)                    |
| `amount`             | `Int`            | Valor do pagamento em centavos                         |
| `dueDate`            | `DateTime?`      | Data de vencimento                                     |
| `status`             | `PaymentStatus`  | Status do pagamento                                    |
| `issuedAt`           | `DateTime`       | Data de emissão                                        |
| `paidAt`             | `DateTime?`      | Data em que o pagamento foi confirmado                 |
| `overdueAt`          | `DateTime?`      | Data em que o pagamento ficou vencido                  |
| `canceledBy`         | `UUID?`          | Usuário que cancelou o pagamento, quando aplicável     |
| `canceledAt`         | `DateTime?`      | Data de cancelamento                                   |
| `createdBy`          | `UUID?`          | Usuário que criou o registro, quando aplicável         |
| `createdAt`          | `DateTime`       | Data de criação                                        |
| `updatedBy`          | `UUID?`          | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`          | `DateTime`       | Data da última atualização                             |

## Relacionamentos

* Relaciona-se com [Order](/data-modelling/sales/order) (1:1 via `orderId` único)
* Relaciona-se com [Organization](/data-modelling/tenant/organization)
* Relaciona-se com [Company](/data-modelling/tenant/company)
* Relaciona-se com múltiplos [Receivable](/data-modelling/billing/receivable)

## 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

| Valor         | Descrição                     |
| ------------- | ----------------------------- |
| `CASH`        | Dinheiro                      |
| `PIX`         | Pagamento instantâneo via PIX |
| `CREDIT_CARD` | Cartão de crédito             |
| `DEBIT_CARD`  | Cartão de débito              |

### PaymentChannel

| Valor    | Descrição                                      |
| -------- | ---------------------------------------------- |
| `ONLINE` | Pagamento criado no canal digital              |
| `POS`    | Pagamento criado em venda presencial ou guichê |

### PaymentStatus

O status reflete o ciclo de vida da cobrança no provedor de pagamento. Default `PENDING`.

| Valor                | Descrição                                  |
| -------------------- | ------------------------------------------ |
| `PENDING`            | Pagamento criado, aguardando processamento |
| `PROCESSING`         | Em processamento no provedor               |
| `ANTIFRAUD_PENDING`  | Aguardando análise antifraude              |
| `ANTIFRAUD_MANUAL`   | Em análise antifraude manual               |
| `ANTIFRAUD_APPROVED` | Aprovado pela análise antifraude           |
| `ANTIFRAUD_REPROVED` | Reprovado pela análise antifraude          |
| `PAID`               | Pagamento confirmado                       |
| `UNDERPAID`          | Pago a menor que o valor esperado          |
| `OVERPAID`           | Pago a maior que o valor esperado          |
| `PARTIAL_CANCELED`   | Parcialmente cancelado                     |
| `CANCELED`           | Cancelado                                  |
| `PAYMENT_FAILED`     | Pagamento recusado ou falhou               |
| `REFUNDED`           | Estornado após confirmação                 |
| `CHARGEDBACK`        | Sofreu chargeback                          |

## Example

```json theme={null}
{
  "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"
}
```