Liquidar a dívida de tarifa (API) - Lerian

Deixe um pagamento passar quando o pagador não pode pagar a tarifa inteira e liquide o restante da tarifa depois.

Participantes

Sua instituição. O seu sistema. Ele lança os pagamentos e os créditos e pode cobrar a dívida de tarifa.
Midaz. O ledger. Ele abre a dívida de tarifa e a liquida, da dívida mais antiga para a mais nova.

Antes de começar

A tarifa é diferível: o pacote de tarifas define deferrable como true nela. Apenas uma tarifa com isDeductibleFrom em false pode ser diferível.

Diagrama

Liquidar a dívida de tarifa

Passo a passo pela API

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Midaz	Chamada de API	`POST /v2/transactions/direct`	Lance um pagamento. O pagador tem o suficiente para o pagamento, mas não para a tarifa inteira.
2	Midaz	Midaz	Etapa interna		O Midaz move o pagamento e a parte da tarifa que o pagador pode pagar. O restante da tarifa vira dívida de tarifa.
3	Midaz	Sua instituição	Resposta da API		O Midaz responde `201`. O metadado `feeDebtOpenings` lista a dívida de tarifa que a transação abriu.
4	Sua instituição	Midaz	Chamada de API	`POST /v2/transactions/direct`	Depois, lance uma transação que credita o pagador.
5	Midaz	Midaz	Etapa interna		O Midaz usa o crédito para liquidar a dívida de tarifa aberta daquele saldo, da dívida mais antiga para a mais nova. Ele paga a conta de tarifa de cada dívida.
6	Midaz	Sua instituição	Resposta da API		O Midaz responde `201`. O metadado `feeDebtSettlements` lista as dívidas que o crédito liquidou.
7	Sua instituição	Midaz	Chamada de API	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/collect`	Ou cobre a dívida de tarifa aberta sem um crédito. Envie o `accountAlias` do pagador e, se quiser, um `balanceKey` e um `maxAmount`. Envie o header `X-Idempotency`.
8	Midaz	Sua instituição	Resposta da API		O Midaz responde com o valor `collected` e o `transactionId` da cobrança.
9	Sua instituição	Midaz	Chamada de API	`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts`	Leia as dívidas de tarifa do pagador com `account_alias`.
10	Midaz	Sua instituição	Resposta da API		O Midaz lista as dívidas, da mais antiga para a mais nova. `openTotal` é o total que o saldo ainda deve.

Regras

Apenas uma transação direta /v2 abre dívida de tarifa.
Um crédito ao pagador pela API /v2 pode liquidar a dívida de tarifa aberta dele, da dívida mais antiga para a mais nova, até o valor do crédito.
Uma cobrança não cobra tarifa, e você não pode estorná-la.

Como saber que terminou

Liste as dívidas de tarifa do pagador com account_alias e status=open. A lista está vazia.

O que pode dar errado

Situação	O que você vê	O que fazer
O saldo do pagador já tem 256 dívidas de tarifa abertas	`422` com `0018`	O Midaz recusa o pagamento inteiro. Cobre a dívida de tarifa aberta ou credite o pagador e lance o pagamento de novo.
Uma cobrança não liquida nada	`collected` é `0`, e não há `transactionId`	O saldo não tem dívida aberta ou não tem valor disponível, ou o Midaz não pode mover o valor entre o saldo e uma conta de tarifa. Leia as dívidas de tarifa, como no passo 9, e o saldo.
Você tenta estornar uma cobrança	`422` com `0089`	Uma cobrança é definitiva. Lance uma nova transação se precisar devolver um valor.
A resposta de uma cobrança não chega	Nenhuma resposta, ou um timeout	Dentro do tempo do header `X-TTL` (300 segundos por padrão), envie a mesma cobrança com a mesma chave `X-Idempotency`. Depois de um `409` com `0084`, ou depois desse tempo, leia as dívidas de tarifa do pagador, como no passo 9, antes de cobrar de novo.

Relacionados