Get a boleto batch

curl --request GET \
  --url https://api.example.com/v1/boletos/batches/{batch_id} \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

	url := "https://api.example.com/v1/boletos/batches/{batch_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/boletos/batches/{batch_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "closed": true,
  "counts": {
    "canceled": 1,
    "failed": 1,
    "inactivated": 0,
    "overdue": 0,
    "processing": 1,
    "registered": 2,
    "requested": 5,
    "settled": 0
  },
  "createdAt": "2026-10-14T19:34:00Z",
  "finished": true,
  "items": [
    {
      "amount": "150.00",
      "boletoId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "cancelable": true,
      "dueDate": "2030-01-15",
      "overdue": true,
      "payer": {
        "document": "<string>",
        "name": "<string>",
        "address": {
          "city": "<string>",
          "complement": "<string>",
          "neighborhood": "<string>",
          "number": "<string>",
          "state": "<string>",
          "street": "<string>",
          "zipCode": "<string>"
        }
      },
      "position": 0,
      "status": "CREATED",
      "discount": {
        "amount": "<string>",
        "limitDate": "<string>",
        "type": "<string>"
      },
      "errorCode": "PBP-0108",
      "errorMessage": "no title was issued for this emission",
      "fine": {
        "amount": "<string>",
        "type": "<string>"
      },
      "instructions": "<string>",
      "interest": {
        "amount": "<string>",
        "type": "<string>"
      },
      "ourNumber": "00000000152",
      "ourNumberDigit": "3",
      "ourNumberHolderBoletoId": "<string>",
      "providerId": "<string>",
      "requestedOurNumber": "00000000152"
    }
  ],
  "ledgerId": "7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e",
  "midazAccountId": "3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
  "organizationId": "0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d",
  "status": "CREATED"
}

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

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

Get a boleto batch

Reads one boleto batch of the X-Organization-Id organization: its outcome, its counts and every item, in ascending position. The outcome, the counts, closed, finished and each item’s overdue are derived from the items on every read, at the instant of the read. A batch that does not exist and a batch of another organization are both answered 404 PBP-0005, with the same body. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, 400 PBP-0001 when batch_id is not a UUID, and 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID.

GET

boletos

batches

{batch_id}

Get a boleto batch

curl --request GET \
  --url https://api.example.com/v1/boletos/batches/{batch_id} \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

	url := "https://api.example.com/v1/boletos/batches/{batch_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/boletos/batches/{batch_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "closed": true,
  "counts": {
    "canceled": 1,
    "failed": 1,
    "inactivated": 0,
    "overdue": 0,
    "processing": 1,
    "registered": 2,
    "requested": 5,
    "settled": 0
  },
  "createdAt": "2026-10-14T19:34:00Z",
  "finished": true,
  "items": [
    {
      "amount": "150.00",
      "boletoId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "cancelable": true,
      "dueDate": "2030-01-15",
      "overdue": true,
      "payer": {
        "document": "<string>",
        "name": "<string>",
        "address": {
          "city": "<string>",
          "complement": "<string>",
          "neighborhood": "<string>",
          "number": "<string>",
          "state": "<string>",
          "street": "<string>",
          "zipCode": "<string>"
        }
      },
      "position": 0,
      "status": "CREATED",
      "discount": {
        "amount": "<string>",
        "limitDate": "<string>",
        "type": "<string>"
      },
      "errorCode": "PBP-0108",
      "errorMessage": "no title was issued for this emission",
      "fine": {
        "amount": "<string>",
        "type": "<string>"
      },
      "instructions": "<string>",
      "interest": {
        "amount": "<string>",
        "type": "<string>"
      },
      "ourNumber": "00000000152",
      "ourNumberDigit": "3",
      "ourNumberHolderBoletoId": "<string>",
      "providerId": "<string>",
      "requestedOurNumber": "00000000152"
    }
  ],
  "ledgerId": "7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e",
  "midazAccountId": "3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
  "organizationId": "0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d",
  "status": "CREATED"
}

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

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

Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist.

Path Parameters

batch_id

string<uuid>

required

Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001.

Example:

"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"

Response

The batch with its outcome, its counts and every item, derived at the instant of the read.

batchId

string<uuid>

required

Batch identifier.

Example:

"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"

closed

boolean

required

Whether every item is SETTLED, CANCELED, INACTIVATED or FAILED: nothing else will happen to the batch, payment included. Always present. It moves back to false when a cancellation is refused and the item returns to CREATED. True implies finished.

counts

object

required

Show child attributes

createdAt

string<date-time>

required

When the batch was created, RFC 3339 in UTC.

Example:

"2026-10-14T19:34:00Z"

finished

boolean

required

Whether no item is PENDING: the issuance of the batch is over. Always present. It never moves back to false; an overdue item keeps it false.

items

object[] | null

required

Every item, in ascending position. Never paginated: a batch holds at most 25 items.

Show child attributes

ledgerId

string<uuid>

required

Ledger of the batch and of each item.

Example:

"7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e"

midazAccountId

string

required

Collection account of the batch and of each item.

Example:

"3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b"

organizationId

string<uuid>

required

Organization the batch was recorded with: always the organization of the X-Organization-Id header.

Example:

"0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d"

status

enum<string>

required

Issuance outcome of the batch, derived from its items on every read. CREATED: some item is still PENDING. COMPLETED: no item is PENDING and none is FAILED. PARTIAL_FAILURE: no item is PENDING and some, not all, are FAILED; those carry errorCode and errorMessage. FAILED: every item is FAILED. Only issuance moves it: payment, cancellation and write-off do not, and it never moves back to CREATED.

Available options:

CREATED,

COMPLETED,

PARTIAL_FAILURE,

FAILED

Boletos API

Boleto batches API

Payments API

Dashboards API

Admin API

Pix receiver API

Webhooks API

Error handling

Get a boleto batch

Authorizations

Headers

Path Parameters

Response