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

# Billing Provider

> Contrato genérico usado para integrar providers de billing.

O DEVMOB integra pagamentos através de um contrato genérico de billing. O domínio Billing não depende de um provider específico: as regras de negócio são descritas pelo comportamento esperado da integração.

O contrato de billing opera no escopo de Company. Cada entidade de billing carrega `organizationId` e `companyId` para identificar a empresa beneficiária. Cooperative não participa de billing.

Cada Company possui sua própria configuração externa de billing em [CompanyPaymentSettings](/data-modelling/billing/company-payment-settings). O campo `externalApiKey` é criptografado e usado apenas para operar em nome da conta externa da empresa.

## Regra de integração

O contrato de billing cobre duas superfícies:

```mermaid theme={null}
flowchart TD
    CHECKOUT["Checkout"] --> BILLING["Contrato de billing"]
    FINANCE["Billing"] --> BILLING
    EVENTS["Eventos externos"] --> ACTION["Ações financeiras"]
    ACTION --> FINANCE
```

* Criação e cancelamento de pagamentos.
* Cadastro e atualização da conta externa da empresa.
* Consulta de saldo e recebíveis.
* Solicitação de transferências.
* Gestão de métodos de pagamento salvos e opções de pagamento disponíveis.
* Tradução de eventos externos para ações financeiras.

## Operações

O contrato cobre todo o ciclo financeiro:

| Grupo                | Operações                                            |
| -------------------- | ---------------------------------------------------- |
| Pagamentos           | Criar cobrança e solicitar estorno                   |
| Saldo e recebíveis   | Consultar saldo disponível e listar recebíveis       |
| Transferências       | Solicitar saque para conta bancária                  |
| Conta externa        | Criar e atualizar configuração externa da Company    |
| Clientes             | Criar e atualizar customer externo                   |
| Métodos de pagamento | Listar, obter e criar métodos associados ao Customer |

## PaymentMethod

PaymentMethod pertence ao Customer e funciona como proxy local do gateway. Ele não é ownership da Company.

| Método        | Regra                                                                           |
| ------------- | ------------------------------------------------------------------------------- |
| `CASH`        | Opção presencial; pode confirmar Payment no POS sem referência externa.         |
| `PIX`         | Opção via gateway; pode carregar metadados do provider quando existir cobrança. |
| `CREDIT_CARD` | Cartão tokenizado no gateway.                                                   |
| `DEBIT_CARD`  | Cartão tokenizado no gateway.                                                   |

<Info>
  Boleto não faz parte do modelo atual de métodos de pagamento.
</Info>

## Webhooks

Eventos externos são traduzidos para efeitos financeiros quando pertencem ao ciclo de pagamento, pedido, recebíveis, transferência ou conta bancária.

O modelo genérico de recebimento e idempotência fica em [Webhooks](/webhooks/overview). O mapeamento específico de billing fica em [Billing Webhooks](/webhooks/billing/overview).