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. 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:
- 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. |
Boleto não faz parte do modelo atual de métodos de pagamento.
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. O mapeamento específico de billing fica em Billing Webhooks. 
