v1

latestOpenAPI 3.1.02026-08-0629140119.9 KB

Boleto Payments

Creates a batch of boleto payments.

External Reference IDs

Each payment must have a unique external_reference_id within the bank account. Attempting to create a payment with a duplicate external_reference_id will fail with 400 Bad Request.

Idempotency

With X-Idempotency-Key header: Multiple requests with the same idempotency key return the same batch (safe retries).
Without X-Idempotency-Key header: Each request creates a new batch. Duplicate external_reference_id values will fail.

Amount Handling

If amount_in_cents is provided, it will be used for the payment.
If amount_in_cents is null, the amount will be extracted from the barcode line during processing.

Uniqueness Scope

The external_reference_id is unique per bank account, not globally. Different accounts can use the same external_reference_id.

Allowed Beneficiaries (allowed_tax_ids)

When allowed_tax_ids is provided, it acts as an allowlist that restricts which beneficiary documents are accepted for the entire batch. The tax_id in each payment must be present in the list. When empty, payments to any document are accepted.

post/v1/boleto-payments

Headers

X-Idempotency-Keystring nullable

Optional idempotency key for safe retries. When provided, requests with the same key return the same result. Without this header, duplicate external_reference_id values will fail with 400 Bad Request.

Request body

allowed_tax_idsstring[]

Optional list of CPF/CNPJ that restricts the allowed beneficiary documents for this batch. When provided, the tax_id in each payment must be present in the list. When empty, payments to any document are accepted.

Example request

{
  "allowed_tax_ids": [
    "12345678909"
  ],
  "payments": [
    {
      "amount_in_cents": 11631,
      "description": "Pagamento boleto",
      "external_reference_id": "boleto-001",
      "line": "34191091070544794730971544640008884660000011631",
      "tax_id": "12345678909"
    }
  ]
}

Response

Boleto payments batch created successfully

Example response

{
  "batch": {
    "created_at": "2026-05-28T14:30:00Z"
  },
  "payments": [
    {
      "created_at": "2026-05-28T14:30:00Z",
      "scheduled_date": "2026-06-01"
    }
  ]
}