Cobrar uma tarifa em uma transação (API)

Configure um pacote de tarifas uma vez e deixe o Midaz adicionar a tarifa a cada transação que corresponde a ele, pela API do Midaz.

Cobre uma tarifa automaticamente nas transações que correspondem a um pacote de tarifas.

​

Participantes

---

• Sua instituição. O seu sistema. Ele configura o pacote de tarifas e lança as transações.
• Midaz. O ledger. Ele seleciona o pacote, adiciona a tarifa e lança a transação.

​

Antes de começar

---

• A conta que recebe a tarifa existe no ledger. A tarifa indica essa conta em creditAccount.

​

Diagrama

---

​

Passo a passo pela API

---

#	Origem	Destino	Mensagem	API da Lerian	O que acontece
1	Sua instituição	Midaz	Chamada de API	POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages	Crie o pacote de tarifas com seu feeGroupLabel, seu minimumAmount, seu maximumAmount, seu enable e suas fees. Cada tarifa tem um creditAccount, a conta que a recebe.
2	Sua instituição	Midaz	Chamada de API	POST /v2/transactions/direct	Lance a transação. Envie o routeId ou os metadados que o pacote espera. Envie o header X-Idempotency.
3	Midaz	Midaz	Etapa interna		O Midaz seleciona o pacote que corresponde à transação.
4	Midaz	Midaz	Etapa interna		O Midaz adiciona as movimentações da tarifa à transação. Cada tarifa vai para o seu creditAccount.
5	Midaz	Midaz	Etapa interna		O Midaz aplica o pagamento e as movimentações da tarifa juntos. Todos os saldos mudam, ou nenhum deles muda.
6	Midaz	Sua instituição	Resposta da API		O Midaz responde 201 com a transação. O metadado feeApplied é "true", e packageAppliedID indica o pacote.

​

Regras

---

• Uma transação /v1 e um estorno não cobram tarifa nova.
• Um pacote habilitado se aplica quando a transação atende a cada condição que o pacote define, e o valor está na faixa de minimumAmount a maximumAmount. As condições são transactionRoute, segmentId e cada par em metadataSelector.
• A rota de transação é o routeId da transação. O segmento é aquele que as contas de origem compartilham.
• Quando vários pacotes se aplicam, vence o pacote com mais condições. O Midaz aplica no máximo um pacote a uma transação.
• Com isDeductibleFrom em false, as origens pagam a tarifa além do valor. Com true, os destinos recebem o valor menos a tarifa.
• Quando cada conta de origem está em waivedAccounts, o Midaz não cobra tarifa.
• Uma conta de origem com um plano de tarifas ativo paga as tarifas do plano dela. Um pacote de tarifas nunca cobra essa conta, também quando nenhuma tarifa do plano corresponde.
• Para ver a tarifa de um pacote antes de lançar, use Estimar o cálculo da tarifa.

​

Como saber que terminou

---

Os metadados da transação mostram feeApplied como "true" e packageAppliedID com o id do pacote. Cada operação de tarifa mostra o metadado feeLeg como "true".

​

O que pode dar errado

---

Situação	O que você vê	O que fazer
Dois pacotes correspondem com o mesmo número de condições	400 com 0198	Mude as condições de um dos pacotes. O erro indica quais são.
O pagador não pode pagar o valor e a tarifa	422 com 0018	O Midaz não moveu nada. Adicione fundos.
Nenhuma tarifa aparece na transação	201 sem feeApplied como "true"	Se feesSkipped é true, a requisição pulou o cálculo de tarifas. Se os metadados têm feeExemption, uma isenção impediu a tarifa. A sua message diz o motivo. Se uma conta de origem tem um plano de tarifas ativo, nenhum pacote cobra essa conta. Nos outros casos, confirme que enable é true no pacote. Depois compare transactionRoute, segmentId, metadataSelector e a faixa de valor do pacote com a transação.
A resposta não chega	Nenhuma resposta, ou um timeout	Não suponha que a transação falhou. Dentro do tempo do header X-TTL (300 segundos por padrão), envie a mesma requisição com a mesma chave X-Idempotency. Um 201 com X-Idempotency-Replayed: true devolve a primeira transação. Um 409 com 0084 significa que o Midaz ainda não tem o resultado guardado da primeira requisição: envie-a de novo mais tarde com a mesma chave. Depois desse tempo, leia as operações da conta de origem antes de enviar a transação de novo.

​

Relacionados

---

• Montar um ledger e lançar a primeira transação
• Liquidar a dívida de tarifa
• Lista de erros do Midaz