Skip to main content
Por padrão, o Midaz recusa uma transação quando o pagador não consegue cobrir as tarifas. Uma tarifa diferível muda isso. O pagador paga a parte da tarifa que o valor disponível dele cobre. O restante vira uma dívida de tarifa, e a transação é concluída. Os créditos seguintes ao pagador liquidam a dívida. A dívida de tarifa vem desativada por padrão. Ela se aplica apenas às tarifas que você marca como diferíveis.

​
Torne uma tarifa diferível

Defina deferrable: true em uma tarifa ao criar ou atualizar o pacote de tarifas dela.
  • Apenas uma tarifa com isDeductibleFrom: false pode ser diferível. O Midaz recusa uma tarifa dedutível que também seja diferível com o erro 0530.
  • Uma tarifa diferível abre uma dívida apenas em uma transação direta /v2. Em um hold /v2, o Midaz recusa uma tarifa sem cobertura com o erro 0018.
  • Quando um saldo já tem 256 dívidas de tarifa em aberto, o Midaz recusa uma nova tarifa diferível sem cobertura nele com o erro 0018.
Exemplo. Um pagador tem 105 e envia 100 com uma tarifa diferível de 10. A transação movimenta 105: o pagamento de 100 e 5 da tarifa. Os outros 5 viram uma dívida de tarifa. A chave de metadados feeDebtOpenings da transação registra a dívida.

​
Como uma dívida é liquidada

Um crédito no saldo do pagador pela API /v2 liquida as dívidas de tarifa em aberto dele, da mais antiga para a mais nova. Isso inclui transações diretas, commits e estornos. Um crédito menor que uma dívida liquida parte dela. Cada liquidação move o valor do saldo do pagador para a conta de tarifa da dívida. O Midaz registra esses movimentos como operações do tipo FEE_SETTLEMENT, e a chave de metadados feeDebtSettlements da transação registra as dívidas liquidadas. Para liquidar dívidas sem um crédito, use Cobrar dívidas de tarifa em aberto. Envie o accountAlias do pagador e, opcionalmente, um balanceKey e um maxAmount.
  • O Midaz paga as dívidas em aberto desse saldo com o valor disponível dele, da mais antiga para a mais nova, e não cobra tarifa sobre a cobrança.
  • A resposta traz o valor collected e o transactionId da cobrança.
  • Quando nada é cobrado, a resposta traz collected: "0" e o Midaz não cria transação.
  • Você não pode estornar uma cobrança. O Midaz recusa o estorno com o erro 0089.

​
Estornos e dívida de tarifa

Quando você estorna a transação que abriu uma dívida, o pagador recebe a tarifa inteira de volta:
  • O estorno devolve a parte da tarifa que o pagador pagou na transação original.
  • O Midaz cancela a parte da dívida que ainda está em aberto.
  • O Midaz reembolsa a parte que os créditos seguintes liquidaram. A conta de tarifa paga o reembolso, e o Midaz o registra como operações do tipo FEE_REFUND. Na /v2, o reembolso então liquida as outras dívidas em aberto do pagador, da mais antiga para a mais nova.
O estorno de um crédito que liquidou uma dívida pode reabrir essa dívida pelo valor liquidado. Quando o registro de dívida de tarifa de uma transação ainda não está completo, o Midaz recusa o estorno com o erro 0529 (HTTP 409) e não movimenta nada. Tente novamente mais tarde.

​
Consulte as dívidas de tarifa

  • Listar dívidas de tarifa retorna as dívidas de um ledger, da mais antiga para a mais nova. Filtre por account_alias, balance_key e status (open ou settled). Com account_alias, a resposta também traz openTotal, o total que o saldo deve.
  • Consultar uma dívida de tarifa retorna uma dívida com o valor remaining e o histórico de alterações dela.
Listar e consultar dívidas de tarifa exige a permissão midaz/fee-debts com get. Cobrar dívida de tarifa exige post. Cada alteração tem um destes tipos:

​
Contas e saldos com dívida de tarifa

O Midaz se recusa a excluir um saldo, ou a excluir ou encerrar a conta dele, quando:
  • O saldo deve dívida de tarifa (erro 0527). Credite o saldo ou cobre a dívida antes.
  • Outros saldos devem dívida de tarifa ao saldo (erro 0528), por exemplo uma conta de tarifa. Credite antes os saldos que devem a dívida.

​
Antes de ativar a dívida de tarifa

  • Rode o Midaz v4.2.0 ou superior em todas as instâncias do ledger antes de definir deferrable em uma tarifa. Uma versão anterior não consegue concluir uma transação que carrega dívida de tarifa. Depois de defini-lo, não faça rollback do ledger para uma versão anterior.
  • O ledger mantém as dívidas de tarifa em aberto no Valkey. O Valkey deve ser persistente e manter essas chaves. Veja Configuração de dependências.