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

> Payment: métodos, status e confirmação via webhook do provedor.

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

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING

    PENDING --> PROCESSING : Em processamento
    PENDING --> PAID : Cobrança paga
    PROCESSING --> PAID : Cobrança paga
    PENDING --> PAYMENT_FAILED : Recusado
    PROCESSING --> PAYMENT_FAILED : Recusado

    PAID --> REFUNDED : Estorno
    PAID --> CHARGEDBACK : Chargeback

    PAYMENT_FAILED --> [*]
    REFUNDED --> [*]
    CHARGEDBACK --> [*]
```

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

<Info>
  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](/data-modelling/billing/payment).
</Info>

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

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

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

```mermaid theme={null}
sequenceDiagram
    participant C as Order/Checkout
    participant P as Payment
    participant GW as Provedor de pagamento

    C->>P: Payment com status inicial

    Note over GW: Cobrança assíncrona (PIX, cartão)
    GW->>P: Webhook de atualização
    Note over P: Status financeiro atualizado
```

* 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](/domain/billing/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.

<Warning>
  Um Payment com status `PAYMENT_FAILED` **não cancela** o Order automaticamente; o status pode ser reprocessado.
</Warning>

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

O par `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`.

```mermaid theme={null}
sequenceDiagram
    participant S as Operador / Provedor
    participant P as Payment

    alt Registro interno
        S->>P: Registra estorno
        Note over P: Status REFUNDED e data de cancelamento preenchidos
    else Estorno do provedor
        S->>P: Webhook de estorno
        Note over P: Status REFUNDED ou CHARGEDBACK
    end
```

<Info>
  Não há cancelamento de recebíveis disparado pelo estorno. Os recebíveis refletem o estado reportado pelo provedor na próxima sincronização.
</Info>

## 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](/domain/billing/receivables).

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