Skip to main content
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 Cooperative. Cada entidade de billing carrega organizationId e cooperativeId para identificar a cooperativa beneficiária. Cada Cooperative possui sua própria configuração externa de billing em CooperativePaymentSettings. O campo externalApiKey é criptografado e usado apenas para operar em nome da conta externa da cooperativa. A OPS API permite consultar, criar e atualizar essa configuração no escopo da cooperativa autenticada. Requests de escrita aceitam externalApiKey; respostas expõem somente hasExternalApiKey.

​
Regra de integração

O contrato de billing cobre duas superfícies:
  • Criação e cancelamento de pagamentos.
  • Criação de cobrança de crédito corporativo na conta externa da Cooperative escolhida.
  • Cadastro e atualização da conta externa da cooperativa.
  • 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:

​
PaymentMethod

PaymentMethod pertence ao Customer e funciona como proxy local do gateway. Ele não é ownership da Cooperative.
Boleto não faz parte do modelo atual de métodos de pagamento.

​
Compra de crédito corporativo

CompanyCreditPurchase usa a configuração ativa da Cooperative escolhida. O backend envia externalProvider, externalAccountId e externalWalletId somente para o adapter. Credenciais de provider não entram em response, evento, audit log ou metadata. O provider cria uma ordem externa e um pagamento externo. O Payment local guarda ambas as referências e é retornado dentro da compra para acompanhamento de status.

​
Webhooks

Eventos externos são traduzidos para efeitos financeiros quando pertencem ao ciclo de pagamento, pedido, recebíveis ou transferência. O modelo genérico de recebimento e idempotência fica em Webhooks. O mapeamento específico de billing fica em Billing Webhooks.