Cobrança de taxa por organização via split no gateway

TLDR: cobrar das organizações um percentual sobre cada pagamento aprovado, usando o mecanismo de SPLIT do gateway para depositar a taxa direto na conta da ZeusPay.

Contexto

Precisamos começar a monetizar o serviço. O dinheiro do pagamento é depositado na conta da organização, então a cobrança precisa acontecer no momento da transação — daí o uso de split na conta do gateway de pagamentos.

Objetivos

Cada organização tem uma taxa cobrada sobre todos os seus pagamentos, como percentual por transação aprovada no gateway.
O dinheiro é depositado na conta da organização, com um SPLIT para a conta da ZeusPay cobrando pelo serviço.
A taxa é configurável no modelo de organização.
Na criação do pagamento com o gateway, o split é informado. Como sempre usamos parcelamento, o split vai como totalFixedValue no Asaas — ver split em parcelamentos.
Se o campo de valor cobrado for nulo, não enviar splits na criação dos pagamentos.
O payload do split volta nas requisições de cobrança (webhooks).

Fora de escopo

— (não registrado na spec original)

Mudanças

Modelo `Organization`

Campo	Nome
`fee_total`	Valor do fee cobrado, em %, por cada compra efetuada
`charge_fee`	Booleano que determina se haverá cobrança na organização

Payload de split no webhook do gateway

Trecho relevante do webhook de cobrança do Asaas:

json { "id": "evt_d26e303b238e509335ac9ba210e51b0f&7115913", "event": "PAYMENT_RECEIVED", "dateCreated": "2024-08-15 18:51:30", "payment": { "id": "pay_tyubroyvynvk69l9", "value": 800, "netValue": 798.01, "billingType": "PIX", "status": "RECEIVED", "externalReference": "payment_b96822a56d23caa5f7e5ae1723758659", "split": [ { "id": "cfe7dfc9-9d5b-4c3b-b38e-6a938328cad5", "walletId": "1388ba14-a18c-437d-bc74-027252348ad0", "fixedValue": null, "percentualValue": 10, "totalValue": 79.8, "cancellationReason": null, "status": "DONE", "externalReference": null } ] } }

Roadmap

[x] Adicionar os campos fee_total e charge_fee no modelo Organization
[x] Guardar a walletId da ZeusPay nos credentials
[x] Modificar o Payments::Creation::GatewayCreationFlow para suportar o array de splits
[x] Modificar o CheckoutService para suportar o array de split (fluxo deprecated)
[ ] Salvar as informações de split no Installment quando retornadas pelo gateway

Como verificar