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

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

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 ruta

organization_id

string

requerido

Organization ID (UUID)

ledger_id

string

requerido

Ledger ID (UUID)

account_id

string

requerido

Account ID (UUID)

Cuerpo

application/json

serviceCodes

string[] | null

requerido

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

Ejemplo:

["PAPER_STATEMENT", "CARD_REISSUE"]

description

string

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

Maximum string length: 256

Ejemplo:

"Tarifas de serviço de outubro"

metadata

object

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

Show child attributes

Respuesta

Created

accountId

string

requerido

Ejemplo:

"00000000-0000-0000-0000-000000000000"

accountPlanId

string

requerido

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

Ejemplo:

"00000000-0000-0000-0000-000000000000"

accountPlanVersion

integer<int64>

requerido

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

Ejemplo:

1

assetCode

string

requerido

Asset of the account the charge was taken in.

Ejemplo:

"BRL"

createdAt

string<date-time>

requerido

Ejemplo:

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

feeTransactionIds

string[] | null

requerido

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

string

requerido

Ejemplo:

"00000000-0000-0000-0000-000000000000"

items

object[] | null

requerido

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

Show child attributes

ledgerId

string

requerido

Ejemplo:

"00000000-0000-0000-0000-000000000000"

organizationId

string

requerido

Ejemplo:

"00000000-0000-0000-0000-000000000000"

period

string

requerido

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

Ejemplo:

"2026-10"

totalAmount

string

requerido

Sum of the amounts of the charged items.

Ejemplo:

"15"

description

string

Ejemplo:

"Tarifas de serviço de outubro"

metadata

object

Show child attributes

Primeros pasos

Núcleo

CRM

Fees

Manejo de errores

Eventos

Charge service fees to an account

Autorizaciones

Encabezados

Parámetros de ruta

Cuerpo

Respuesta