Initiate a DARF payment

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/payments/darf \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fineAmount": "5.00",
  "interestAmount": "10.00",
  "mainAmount": "100.00",
  "midazAccountId": "<string>",
  "referenceDate": "2026-04-01",
  "treasuryRevenueCode": "0086",
  "type": "S",
  "description": "<string>",
  "dueDate": "2026-05-10",
  "history": "<string>",
  "ledgerId": "<string>",
  "referenceNumber": 123,
  "totalIncomeAmount": "<string>",
  "totalIncomePercent": "<string>"
}
'

package main

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

func main() {

	url := "https://payments.sandbox.lerian.net/v1/payments/darf"

	payload := strings.NewReader("{\n  \"fineAmount\": \"5.00\",\n  \"interestAmount\": \"10.00\",\n  \"mainAmount\": \"100.00\",\n  \"midazAccountId\": \"<string>\",\n  \"referenceDate\": \"2026-04-01\",\n  \"treasuryRevenueCode\": \"0086\",\n  \"type\": \"S\",\n  \"description\": \"<string>\",\n  \"dueDate\": \"2026-05-10\",\n  \"history\": \"<string>\",\n  \"ledgerId\": \"<string>\",\n  \"referenceNumber\": 123,\n  \"totalIncomeAmount\": \"<string>\",\n  \"totalIncomePercent\": \"<string>\"\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({
    fineAmount: '5.00',
    interestAmount: '10.00',
    mainAmount: '100.00',
    midazAccountId: '<string>',
    referenceDate: '2026-04-01',
    treasuryRevenueCode: '0086',
    type: 'S',
    description: '<string>',
    dueDate: '2026-05-10',
    history: '<string>',
    ledgerId: '<string>',
    referenceNumber: 123,
    totalIncomeAmount: '<string>',
    totalIncomePercent: '<string>'
  })
};

fetch('https://payments.sandbox.lerian.net/v1/payments/darf', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/payments/darf"

payload = {
    "fineAmount": "5.00",
    "interestAmount": "10.00",
    "mainAmount": "100.00",
    "midazAccountId": "<string>",
    "referenceDate": "2026-04-01",
    "treasuryRevenueCode": "0086",
    "type": "S",
    "description": "<string>",
    "dueDate": "2026-05-10",
    "history": "<string>",
    "ledgerId": "<string>",
    "referenceNumber": 123,
    "totalIncomeAmount": "<string>",
    "totalIncomePercent": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "createdAt": "<string>",
  "id": "<string>",
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "status": "<string>",
  "totalAmount": "<string>",
  "type": "<string>",
  "providerId": "<string>",
  "providerRequestId": "<string>"
}

{
  "createdAt": "<string>",
  "id": "<string>",
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "status": "<string>",
  "totalAmount": "<string>",
  "type": "<string>",
  "providerId": "<string>",
  "providerRequestId": "<string>"
}

{
  "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>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

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

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

POST

payments

darf

Initiate a DARF payment

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/payments/darf \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fineAmount": "5.00",
  "interestAmount": "10.00",
  "mainAmount": "100.00",
  "midazAccountId": "<string>",
  "referenceDate": "2026-04-01",
  "treasuryRevenueCode": "0086",
  "type": "S",
  "description": "<string>",
  "dueDate": "2026-05-10",
  "history": "<string>",
  "ledgerId": "<string>",
  "referenceNumber": 123,
  "totalIncomeAmount": "<string>",
  "totalIncomePercent": "<string>"
}
'

package main

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

func main() {

	url := "https://payments.sandbox.lerian.net/v1/payments/darf"

	payload := strings.NewReader("{\n  \"fineAmount\": \"5.00\",\n  \"interestAmount\": \"10.00\",\n  \"mainAmount\": \"100.00\",\n  \"midazAccountId\": \"<string>\",\n  \"referenceDate\": \"2026-04-01\",\n  \"treasuryRevenueCode\": \"0086\",\n  \"type\": \"S\",\n  \"description\": \"<string>\",\n  \"dueDate\": \"2026-05-10\",\n  \"history\": \"<string>\",\n  \"ledgerId\": \"<string>\",\n  \"referenceNumber\": 123,\n  \"totalIncomeAmount\": \"<string>\",\n  \"totalIncomePercent\": \"<string>\"\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({
    fineAmount: '5.00',
    interestAmount: '10.00',
    mainAmount: '100.00',
    midazAccountId: '<string>',
    referenceDate: '2026-04-01',
    treasuryRevenueCode: '0086',
    type: 'S',
    description: '<string>',
    dueDate: '2026-05-10',
    history: '<string>',
    ledgerId: '<string>',
    referenceNumber: 123,
    totalIncomeAmount: '<string>',
    totalIncomePercent: '<string>'
  })
};

fetch('https://payments.sandbox.lerian.net/v1/payments/darf', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/payments/darf"

payload = {
    "fineAmount": "5.00",
    "interestAmount": "10.00",
    "mainAmount": "100.00",
    "midazAccountId": "<string>",
    "referenceDate": "2026-04-01",
    "treasuryRevenueCode": "0086",
    "type": "S",
    "description": "<string>",
    "dueDate": "2026-05-10",
    "history": "<string>",
    "ledgerId": "<string>",
    "referenceNumber": 123,
    "totalIncomeAmount": "<string>",
    "totalIncomePercent": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "createdAt": "<string>",
  "id": "<string>",
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "status": "<string>",
  "totalAmount": "<string>",
  "type": "<string>",
  "providerId": "<string>",
  "providerRequestId": "<string>"
}

{
  "createdAt": "<string>",
  "id": "<string>",
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "status": "<string>",
  "totalAmount": "<string>",
  "type": "<string>",
  "providerId": "<string>",
  "providerRequestId": "<string>"
}

{
  "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>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

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

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

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Organization-Id

string

Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Declared optional on the schema so that refusal keeps its own code instead of the schema's PBP-0001.

Idempotency-Key

string

Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012.

Body

application/json

fineAmount

string

required

Fine amount as a decimal string, up to two decimal places. Must be non-negative.

Maximum string length: 32

Example:

"5.00"

interestAmount

string

required

Interest amount as a decimal string, up to two decimal places. Must be non-negative.

Maximum string length: 32

Example:

"10.00"

mainAmount

string

required

Principal amount as a decimal string, up to two decimal places. Must be positive.

Maximum string length: 32

Example:

"100.00"

midazAccountId

string

required

Midaz account the payment settles from. The TAXPAYER of the DARF is the registered owner of this account, read from the Midaz CRM — the request does not state one. A holder whose registered name exceeds 80 bytes cannot be paid on this rail: the name is never shortened to fit, and the refusal is 422 PBP-0207.

referenceDate

string<date>

required

Tax period reference date, YYYY-MM-DD.

Example:

"2026-04-01"

treasuryRevenueCode

string

required

Federal treasury revenue code (codigo da receita): the four zero-padded digits listed in the tax code catalogue the provider publishes as TaxMessageCodes.pdf. Send the four digits alone — the service prefixes them with TRC_ on the way to the provider, and a value that already carries that prefix is forwarded unchanged. The code is not checked against the catalogue here; an unknown code is refused by the provider.

Example:

"0086"

type

string

required

DARF type: S for Simples, N for Normal.

Example:

"S"

description

string

Optional free-text description carried on the payment.

dueDate

string<date>

Optional due date, YYYY-MM-DD.

Example:

"2026-05-10"

history

string

Optional free-text history carried on the payment.

ledgerId

string

Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.

referenceNumber

integer<int64>

Optional reference number carried to the tax authority.

totalIncomeAmount

string

Optional total income amount as a decimal string.

Maximum string length: 32

totalIncomePercent

string

Optional total income percentage as a decimal string.

Maximum string length: 32

Response

Created. The payment provider acknowledged the DARF payment: it is in status CREATED and carries the provider's providerId. Its outcome arrives later; follow it with GET /v1/payments/{id}. A request under an Idempotency-Key that already names a DARF payment the provider acknowledged is answered 201 too, with that payment as it stands, in whatever status it has reached. Compare the 202, where the outcome at the provider is not known.

createdAt

string

required

string

required

ledgerId

string

required

Midaz ledger the payment was written with. Always present.

organizationId

string

required

Midaz organization the payment was written with. Always present.

status

string

required

The payment's status when this answer was produced. CREATED on a 201 for a new payment; UNCONFIRMED on a 202, while the outcome at the payment provider is unknown. A request already on record is answered with the payment's status at that moment, which may be any status a payment takes. A replay of the same Idempotency-Key serves the stored answer, whose status may since have changed: read the payment by id for its current state.

totalAmount

string

required

type

string

required

providerId

string

Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED (the 202 answer): the provider has acknowledged nothing yet. Read the payment by id later to obtain it.

providerRequestId

string

Reference this API sent to the payment provider when it instructed the payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. Absent when the payment carries no such reference.

Boletos API

Payments API

Dashboards API

Admin API

Webhooks API

Error handling

Initiate a DARF payment

Authorizations

Headers

Body

Response