Usar planes de tarifas

Esta guía crea un plan de tarifas con una comisión de transacción y una comisión de servicio, y lo usa en una cuenta. Planes de tarifas da las reglas que siguen los pasos.

Antes de empezar

Necesitas:

Un ledger y una cuenta para el cliente final, aquí con el alias @customer_001.
Una cuenta que recibe las comisiones, aquí con el alias @fee_revenue.
Los permisos account-plans y fee-charges en Midaz. Consulta Permisos.

Los ejemplos usan un ledger sin validación de rutas, donde una comisión de transacción selecciona transacciones por scheme. En un ledger con validación de rutas, da también un bloque accounting a cada comisión. Consulta Rutas contables. Los ejemplos usan estas variables de shell. Cada UUID es un valor de ejemplo. Usa los valores de tu propio entorno.

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

Crea el plan de tarifas

Envía el plan a Crear un plan de tarifas. La comisión tedSent cobra 7.90 por cada TED que envía la cuenta, después de 2 TED gratuitas en el mes. La comisión paperStatement cobra 3 por cada extracto en papel, después de 1 extracto gratuito en el mes.

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
      }
    }
  }'

Midaz responde 201 con el plan y su versión 1. Completa los valores predeterminados de referenceAmount y 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"
}

Guarda el id del plan:

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

Asigna el plan a la cuenta

Envía el plan a Asignar un plan de tarifas a una cuenta:

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\" }"

Midaz responde 200 con la asignación activa:

{
  "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 ahora, los paquetes de comisiones del ledger no cobran a @customer_001 en las transacciones /v2 que envía.

Envía una transacción y lee su comisión

Envía una TED desde la cuenta con Crear una transacción con el modelo directo v2. El scheme es TED, así que la comisión tedSent coincide:

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\" }
    ]
  }"

La respuesta 201 tiene accountPlanFees. La primera TED del mes usa una unidad 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"
  }
]

La tercera TED del mes supera la cuota gratuita. Su elemento tiene "outcome": "charged", "unit": 3 y "amount": "7.9". La cuenta envía 107.9: los 100 de la TED y la comisión, que va a @fee_revenue.Una transacción con otro scheme, o sin ninguno, recibe "outcome": "no_match". La cuenta no paga comisión en ella.Guarda accountPlanFees de la respuesta de creación. Las lecturas de la transacción no lo devuelven.

Lee el uso del mes

Lee las unidades de la cuenta con Obtener el uso del plan de tarifas de una cuenta:

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"

Después de tres TED, la respuesta es:

{
  "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 y period.end son el mes en la zona horaria del plan, en UTC.

Cobra comisiones de servicio

Cobra dos extractos en papel con Cobrar comisiones de servicio a una cuenta. Envía una clave X-Idempotency, y envía la misma clave cuando reintentes el mismo cobro:

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"
  }'

Midaz responde 201. El primer extracto usa la unidad gratuita, y el segundo cuesta 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"
}

La transacción de comisión debita 3 de @customer_001 y los acredita en @fee_revenue. Para deshacer el cobro en el mismo mes, revierte esa transacción.

Crea una nueva versión

Sube las TED gratuitas a 5 desde noviembre. Envía solo el campo que cambia a Actualizar un plan 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"
  }'

Midaz crea la versión 2 con las dos comisiones, y tedSent tiene freeQuota: 5. Antes del 1 de noviembre en la zona horaria del plan, la respuesta y las transacciones usan la versión 1, y currentVersion es 2.

Termina la asignación

Para quitar la cuenta del plan, usa Terminar la asignación de plan de tarifas de una cuenta:

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"

Midaz responde 204. Los paquetes de comisiones del ledger vuelven a aplicarse a la cuenta.

Midaz Core

CRM

Fees

Usar planes de tarifas

Antes de empezar

​Antes de empezar

Antes de empezar