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

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

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.

Parámetros de ruta

batch_id

string<uuid>

requerido

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

Ejemplo:

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

Respuesta

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

batchId

string<uuid>

requerido

Batch identifier.

Ejemplo:

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

closed

boolean

requerido

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

requerido

Show child attributes

createdAt

string<date-time>

requerido

When the batch was created, RFC 3339 in UTC.

Ejemplo:

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

finished

boolean

requerido

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

requerido

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

Show child attributes

ledgerId

string<uuid>

requerido

Ledger of the batch and of each item.

Ejemplo:

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

midazAccountId

string

requerido

Collection account of the batch and of each item.

Ejemplo:

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

organizationId

string<uuid>

requerido

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

Ejemplo:

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

status

enum<string>

requerido

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.

Opciones disponibles:

CREATED,

COMPLETED,

PARTIAL_FAILURE,

FAILED

API de Boletos

API de lotes de boletos

API de Pagos

API de Dashboards

API de Administración

API del receptor Pix

API de Webhooks

Manejo de errores

Get a boleto batch

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta