Charge service fees to an account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCodes": [
    "PAPER_STATEMENT",
    "CARD_REISSUE"
  ],
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

	payload := strings.NewReader("{\n  \"serviceCodes\": [\n    \"PAPER_STATEMENT\",\n    \"CARD_REISSUE\"\n  ],\n  \"description\": \"Tarifas de serviço de outubro\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serviceCodes: ['PAPER_STATEMENT', 'CARD_REISSUE'],
    description: 'Tarifas de serviço de outubro',
    metadata: {}
  })
};

fetch('https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

payload = {
    "serviceCodes": ["PAPER_STATEMENT", "CARD_REISSUE"],
    "description": "Tarifas de serviço de outubro",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "accountPlanId": "00000000-0000-0000-0000-000000000000",
  "accountPlanVersion": 1,
  "assetCode": "BRL",
  "createdAt": "2026-10-22T12:00:00Z",
  "feeTransactionIds": [
    "<string>"
  ],
  "id": "00000000-0000-0000-0000-000000000000",
  "items": [
    {
      "amount": "3",
      "feeKey": "extratoImpresso",
      "freeQuota": 2,
      "outcome": "charged",
      "serviceCode": "PAPER_STATEMENT",
      "unit": 3
    }
  ],
  "ledgerId": "00000000-0000-0000-0000-000000000000",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "period": "2026-10",
  "totalAmount": "15",
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Charge service fees to an account

Charges service fees of the account plan of the account. Each occurrence of a code in serviceCodes is one unit. Units inside the free quota of their fee come out as quota and cost nothing; units past it come out as charged at the fee’s flat amount. Codes the account’s plan does not declare, and every code of an account without a plan, come out as not_covered and consume nothing. All charged units post in a single fee transaction in the account’s asset, debiting the account and crediting each fee’s creditAccount, on the fees’ transaction route when the ledger validates accounting routes; neither account plans nor fee packages apply to it. When no unit is charged the charge is recorded without a transaction. The X-Idempotency header is required (400, 0552); a retry with the same key and body returns the recorded charge with X-Idempotency-Replayed and charges nothing again. A code no fee of the ledger declares is refused (422, 0549), as is a code only transaction fees declare (422, 0550) and codes whose fees have different transaction routes (422, 0551). When the fee transaction is refused, for insufficient funds for instance, the charge is refused with the same error and nothing is consumed. ledgerId in the query or the body is refused with 0235.

POST

organizations

{organization_id}

ledgers

{ledger_id}

accounts

{account_id}

fee-charges

Charge service fees to an account

curl --request POST \
  --url https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCodes": [
    "PAPER_STATEMENT",
    "CARD_REISSUE"
  ],
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

	payload := strings.NewReader("{\n  \"serviceCodes\": [\n    \"PAPER_STATEMENT\",\n    \"CARD_REISSUE\"\n  ],\n  \"description\": \"Tarifas de serviço de outubro\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serviceCodes: ['PAPER_STATEMENT', 'CARD_REISSUE'],
    description: 'Tarifas de serviço de outubro',
    metadata: {}
  })
};

fetch('https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://ledger.sandbox.lerian.net/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/fee-charges"

payload = {
    "serviceCodes": ["PAPER_STATEMENT", "CARD_REISSUE"],
    "description": "Tarifas de serviço de outubro",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "accountPlanId": "00000000-0000-0000-0000-000000000000",
  "accountPlanVersion": 1,
  "assetCode": "BRL",
  "createdAt": "2026-10-22T12:00:00Z",
  "feeTransactionIds": [
    "<string>"
  ],
  "id": "00000000-0000-0000-0000-000000000000",
  "items": [
    {
      "amount": "3",
      "feeKey": "extratoImpresso",
      "freeQuota": 2,
      "outcome": "charged",
      "serviceCode": "PAPER_STATEMENT",
      "unit": 3
    }
  ],
  "ledgerId": "00000000-0000-0000-0000-000000000000",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "period": "2026-10",
  "totalAmount": "15",
  "description": "Tarifas de serviço de outubro",
  "metadata": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

Required. Idempotency key of the charge, unique per account: a retry with the same key and body returns the recorded charge with X-Idempotency-Replayed, a different body under the same key answers 409 (0084).

Parâmetros de caminho

organization_id

string

obrigatório

Organization ID (UUID)

ledger_id

string

obrigatório

Ledger ID (UUID)

account_id

string

obrigatório

Account ID (UUID)

Corpo

application/json

serviceCodes

string[] | null

obrigatório

Service codes to charge, 1 to 100. Each occurrence is one unit; codes are normalized to trimmed upper case.

Required array length: 1 - 100 elements

Exemplo:

["PAPER_STATEMENT", "CARD_REISSUE"]

description

string

Description of the charge, also used as the description of the fee transaction.

Maximum string length: 256

Exemplo:

"Tarifas de serviço de outubro"

metadata

object

Flat metadata of the charge, also written to the fee transaction.

Show child attributes

Resposta

Created

accountId

string

obrigatório

Exemplo:

"00000000-0000-0000-0000-000000000000"

accountPlanId

string

obrigatório

Account plan active for the account when the charge was taken; null when the account had none.

Exemplo:

"00000000-0000-0000-0000-000000000000"

accountPlanVersion

integer<int64>

obrigatório

Version of the account plan in effect when the charge was taken; 0 when the account had no plan.

Exemplo:

1

assetCode

string

obrigatório

Asset of the account the charge was taken in.

Exemplo:

"BRL"

createdAt

string<date-time>

obrigatório

Exemplo:

"2026-10-22T12:00:00Z"

feeTransactionIds

string[] | null

obrigatório

Fee transactions that charged the charged items; empty when nothing was charged.

string

obrigatório

Exemplo:

"00000000-0000-0000-0000-000000000000"

items

object[] | null

obrigatório

One item per service code of the request, in request order.

Show child attributes

ledgerId

string

obrigatório

Exemplo:

"00000000-0000-0000-0000-000000000000"

organizationId

string

obrigatório

Exemplo:

"00000000-0000-0000-0000-000000000000"

period

string

obrigatório

Monthly quota period (YYYY-MM) the units were counted in, in the plan timezone.

Exemplo:

"2026-10"

totalAmount

string

obrigatório

Sum of the amounts of the charged items.

Exemplo:

"15"

description

string

Exemplo:

"Tarifas de serviço de outubro"

metadata

object

Show child attributes

Primeiros passos

Núcleo

CRM

Fees

Tratamento de erros

Eventos

Charge service fees to an account

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta