Usar planos de tarifas

Este guia cria um plano de tarifas com uma tarifa de transação e uma tarifa de serviço e o usa em uma conta. Planos de tarifas traz as regras que os passos seguem.

Antes de começar

Você precisa de:

Um ledger e uma conta para o cliente final, aqui com o alias @customer_001.
Uma conta que recebe as tarifas, aqui com o alias @fee_revenue.
As permissões account-plans e fee-charges no Midaz. Veja Permissões.

Os exemplos usam um ledger sem validação de rotas, em que uma tarifa de transação seleciona transações pelo scheme. Em um ledger com validação de rotas, dê também um bloco accounting a cada tarifa. Veja Rotas contábeis. Os exemplos usam estas variáveis de shell. Todo UUID é um valor de exemplo. Use os valores do seu próprio ambiente.

MIDAZ_LEDGER_URL="https://midaz.example.com"
MIDAZ_BEARER_TOKEN="..."
MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"
MIDAZ_ACCOUNT_ID="0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e"   # the account of @customer_001

Crie o plano de tarifas

Envie o plano para Criar um plano de tarifas. A tarifa tedSent cobra 7.90 por cada TED que a conta envia, depois de 2 TEDs gratuitas no mês. A tarifa paperStatement cobra 3 por cada extrato em papel, depois de 1 extrato gratuito no mês.

curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Essential PF",
    "description": "Essential plan for individuals",
    "enable": true,
    "timezone": "America/Sao_Paulo",
    "fees": {
      "tedSent": {
        "feeLabel": "TED sent",
        "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 2
      },
      "paperStatement": {
        "feeLabel": "Paper statement",
        "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
        "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
        "creditAccount": "@fee_revenue",
        "freeQuota": 1
      }
    }
  }'

O Midaz responde 201 com o plano e a versão 1 dele. Ele preenche os valores padrão de referenceAmount e period:

{
  "id": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "label": "Essential PF",
  "description": "Essential plan for individuals",
  "enable": true,
  "timezone": "America/Sao_Paulo",
  "currentVersion": 1,
  "version": 1,
  "effectiveFrom": "2026-10-30T13:00:00Z",
  "fees": {
    "paperStatement": {
      "feeLabel": "Paper statement",
      "trigger": { "type": "service", "serviceCode": "PAPER_STATEMENT" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "3" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 1,
      "period": "monthly"
    },
    "tedSent": {
      "feeLabel": "TED sent",
      "trigger": { "type": "transaction", "schemes": ["TED"], "direction": "sent" },
      "calculationModel": { "applicationRule": "flatFee", "calculations": [{ "type": "flat", "value": "7.90" }] },
      "referenceAmount": "originalAmount",
      "creditAccount": "@fee_revenue",
      "freeQuota": 2,
      "period": "monthly"
    }
  },
  "createdAt": "2026-10-30T13:00:00Z",
  "updatedAt": "2026-10-30T13:00:00Z"
}

Guarde o id do plano:

MIDAZ_ACCOUNT_PLAN_ID="019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b"

Atribua o plano à conta

Envie o plano para Atribuir um plano de tarifas a uma conta:

curl -s -X PUT "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{ \"accountPlanId\": \"$MIDAZ_ACCOUNT_PLAN_ID\" }"

O Midaz responde 200 com a atribuição ativa:

{
  "id": "019a3b2d-5e6f-7a80-9b1c-2d3e4f5a6b7c",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountAlias": "@customer_001",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "startedAt": "2026-10-30T13:05:00Z",
  "endedAt": null
}

A partir de agora, os pacotes de tarifas do ledger não cobram @customer_001 nas transações /v2 que ela envia.

Envie uma transação e leia a tarifa dela

Envie uma TED da conta com Criar uma Transação no modelo direto v2. O scheme é TED, então a tarifa tedSent corresponde:

curl -s -X POST "$MIDAZ_LEDGER_URL/v2/transactions/direct" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: ted-0001' \
  -d "{
    \"description\": \"TED to another bank\",
    \"asset\": \"BRL\",
    \"amount\": \"100\",
    \"scheme\": \"TED\",
    \"debits\": [
      { \"alias\": \"@customer_001\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ],
    \"credits\": [
      { \"alias\": \"@ted_settlement\", \"organizationId\": \"$MIDAZ_ORGANIZATION_ID\", \"ledgerId\": \"$MIDAZ_LEDGER_ID\", \"amount\": \"100\" }
    ]
  }"

A resposta 201 traz accountPlanFees. A primeira TED do mês usa uma unidade gratuita:

"accountPlanFees": [
  {
    "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
    "accountAlias": "@customer_001",
    "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
    "accountPlanVersion": 1,
    "feeKey": "tedSent",
    "outcome": "quota",
    "unit": 1,
    "freeQuota": 2,
    "amount": "0"
  }
]

A terceira TED do mês passa da cota gratuita. O item dela traz "outcome": "charged", "unit": 3 e "amount": "7.9". A conta envia 107.9: os 100 da TED e a tarifa, que vai para @fee_revenue.Uma transação com outro scheme, ou sem nenhum, recebe "outcome": "no_match". A conta não paga tarifa nela.Guarde accountPlanFees da resposta de criação. As leituras da transação não o retornam.

Leia o uso do mês

Leia as unidades da conta com Consultar o uso do plano de tarifas de uma conta:

curl -s "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan/usage?period=2026-10" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"

Depois de três TEDs, a resposta é:

{
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
  "items": [
    {
      "feeKey": "paperStatement",
      "trigger": "fee:paperStatement",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 1,
      "used": 0,
      "remaining": 1,
      "charged": 0
    },
    {
      "feeKey": "tedSent",
      "trigger": "fee:tedSent:TED",
      "period": { "label": "2026-10", "start": "2026-10-01T03:00:00Z", "end": "2026-11-01T03:00:00Z" },
      "freeQuota": 2,
      "used": 3,
      "remaining": 0,
      "charged": 1
    }
  ]
}

period.start e period.end são o mês no fuso horário do plano, em UTC.

Cobre tarifas de serviço

Cobre dois extratos em papel com Cobrar tarifas de serviço de uma conta. Envie uma chave X-Idempotency e envie a mesma chave quando repetir a mesma cobrança:

curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/fee-charges" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency: statements-2026-10' \
  -d '{
    "serviceCodes": ["PAPER_STATEMENT", "PAPER_STATEMENT"],
    "description": "Paper statements of October"
  }'

O Midaz responde 201. O primeiro extrato usa a unidade gratuita, e o segundo custa 3:

{
  "id": "019a3b30-7c8d-7e90-a1b2-c3d4e5f6a7b8",
  "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
  "accountId": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
  "accountPlanId": "019a3b2c-1d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountPlanVersion": 1,
  "description": "Paper statements of October",
  "items": [
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "quota", "unit": 1, "freeQuota": 1, "amount": "0" },
    { "serviceCode": "PAPER_STATEMENT", "feeKey": "paperStatement", "outcome": "charged", "unit": 2, "freeQuota": 1, "amount": "3" }
  ],
  "totalAmount": "3",
  "assetCode": "BRL",
  "feeTransactionIds": ["019a3b30-8d9e-7fa0-b2c3-d4e5f6a7b8c9"],
  "period": "2026-10",
  "createdAt": "2026-10-30T14:00:00Z"
}

A transação de tarifa debita 3 de @customer_001 e os credita em @fee_revenue. Para desfazer a cobrança no mesmo mês, estorne essa transação.

Crie uma nova versão

Aumente as TEDs gratuitas para 5 a partir de novembro. Envie só o campo que muda para Atualizar um plano de tarifas:

curl -s -X PATCH "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/account-plans/$MIDAZ_ACCOUNT_PLAN_ID" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fees": { "tedSent": { "freeQuota": 5 } },
    "effectiveFrom": "2026-11-01T03:00:00Z"
  }'

O Midaz cria a versão 2 com as duas tarifas, e tedSent tem freeQuota: 5. Antes de 1º de novembro no fuso horário do plano, a resposta e as transações usam a versão 1, e currentVersion é 2.

Termine a atribuição

Para tirar a conta do plano, use Terminar a atribuição de plano de tarifas de uma conta:

curl -s -X DELETE "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts/$MIDAZ_ACCOUNT_ID/account-plan" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"

O Midaz responde 204. Os pacotes de tarifas do ledger voltam a se aplicar à conta.

Midaz Core

CRM

Fees

Usar planos de tarifas

Antes de começar

​Antes de começar

Antes de começar