Fees

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/fees

Which rate-card lanes are measured and charged for this org

The public rate card has four lanes, told apart by the direction of the money: MOVIMENTAR (money leaving under a mandate, 10 bps), FATURAR (money being born in the receiver's account, 1%), GOVERNAR (account governance, per governed account) and OPERAR (non-monetary outcomes). A published price is not the same thing as a measured one, and this answer keeps the two apart per lane so a client never shows a figure the platform is not computing.

computed says whether this build measures the lane from the organization's own ledger; charging says whether the organization is actually invoiced for it; latest is the last computed period and is only ever non-null on a computed lane (its shape is the one the lane's own read returns: GET /v1/fees/movimentar, GET /v1/fees/governar). Today MOVIMENTAR and GOVERNAR are the computed lanes; FATURAR and OPERAR are not measured and always answer latest: null. charging is each lane's own switch: an organization can be charged for one lane and not the other. period is the current calendar month in Sao Paulo time.

Scope: fees:read.

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/fees \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/fees HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/fees",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/fees", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/fees");

{
  "period": "string",
  "lanes": {
    "movimentar": {
      "computed": true,
      "charging": true,
      "latest": {
        "period": "string",
        "consumerCount": 1,
        "movedMinor": 1,
        "freeTierAppliedMinor": 1,
        "billableMinor": 1,
        "refundCreditMinor": 1,
        "refundedCount": 1,
        "feeMinor": 1,
        "rateTier": "self_serve",
        "computedAt": "2026-01-15T12:00:00.000Z",
        "invoiced": true
      }
    },
    "faturar": {
      "computed": true,
      "charging": true
    },
    "governar": {
      "computed": true,
      "charging": true,
      "latest": {
        "period": "string",
        "governedAccountsCount": 1,
        "consumerIdsSha256": "string",
        "feeMinor": 1,
        "computedAt": "2026-01-15T12:00:00.000Z",
        "invoiced": true
      }
    },
    "operar": {
      "computed": true,
      "charging": true
    }
  }
}

GET /v1/fees/governar

The org's latest GOVERNAR-lane fee period (rate card v1)

What the calling credential's organization owes CodeSpar for the most recently computed calendar month (Sao Paulo time) under the GOVERNAR lane of the public rate card (Account governance): R$4,90 per governed account active in the month. A governed account active in the month is a holder that had a consumer mandate active at some instant of the month AND at least one outcome settled under one of their mandates in the month (a debit in the wallet ledger, or a receipt sealed). A holder with mandates and no settled outcome in the month costs nothing; a holder with three mandates is one account; the population resets every month.

This lane prices the ACCOUNT, not the outcome. The same debit that pays 10 bps under MOVIMENTAR is what shows the account was alive in the month; it is not priced twice, because the two lines price two different things.

HOW TO READ THE NUMBERS. governedAccountsCount is how many holders were counted; feeMinor is that count times R$4,90, in centavos; consumerIdsSha256 is the SHA-256 (hex) of the counted consumer ids sorted and joined by a newline, so a client can verify its own list of accounts against the figure; the ids themselves stay on the platform's row for audit. invoiced says whether the period has been invoiced; a period is invoiced at most once.

null (200) when no period has been computed for the organization yet. The period is computed by the platform, not on this read; computedAt says when.

Scope: fees:read.

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/fees/governar \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/fees/governar HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/fees/governar",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/fees/governar", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/fees/governar");

{
  "period": "string",
  "governedAccountsCount": 1,
  "consumerIdsSha256": "string",
  "feeMinor": 1,
  "computedAt": "2026-01-15T12:00:00.000Z",
  "invoiced": true
}

GET /v1/fees/movimentar

The org's latest MOVIMENTAR-lane fee period (rate card v1)

What the calling credential's organization owes CodeSpar for the most recently computed calendar month (Sao Paulo time) under the MOVIMENTAR lane of the public rate card: money leaving under a consumer mandate is priced at 10 bps of the value executed, floor R$0,05 and cap R$2,00 per transaction, with the first R$1.000 moved in the month free per organization. Rail fees (Pix, boleto, card) are never in this figure; the rail is passed through at the partner's price on a separate line.

HOW TO READ THE NUMBERS. Every amount is BRL in centavos. movedMinor is the value moved in the month; freeTierAppliedMinor is the part the monthly franchise absorbed; billableMinor is the difference; refundCreditMinor is fee handed back for full refunds within 7 days of last month's payments (the first refund per payer-receiver pair in 30 days); feeMinor is what is owed after that credit, never below zero. rateTier names the commit tier (self_serve 10 bps / R$2,00; commit_8bps R$1,50; commit_6bps R$1,00). invoiced says whether the period has been invoiced; a period is invoiced at most once.

null (200) when no period has been computed for the organization yet. The period is computed by the platform, not on this read, so the figure can lag the ledger by up to a month; computedAt says when.

Scope: fees:read.

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/fees/movimentar \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/fees/movimentar HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/fees/movimentar",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/fees/movimentar", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/fees/movimentar");

{
  "period": "string",
  "consumerCount": 1,
  "movedMinor": 1,
  "freeTierAppliedMinor": 1,
  "billableMinor": 1,
  "refundCreditMinor": 1,
  "refundedCount": 1,
  "feeMinor": 1,
  "rateTier": "self_serve",
  "computedAt": "2026-01-15T12:00:00.000Z",
  "invoiced": true
}