Boletos

Endpoints to create, query, update, and cancel boletos.

Boleto Status

Status	Description
`draft`	Draft - boleto created but not registered
`registered`	Registered with Nuclea (PCR)
`paid`	Paid by the payer
`settled`	Settled - funds transferred
`cancelled`	Cancelled

Create Boleto

Creates a new boleto and registers it on Nuclea's PCR platform.

POST /boletos

Request Body

Field	Type	Required	Description
`nosso_numero`	string	Yes	Unique reference number (11 digits)
`amount_cents`	integer	Yes	Value in cents (e.g., 10000 = R$ 100.00)
`due_date`	string	Yes	Due date (YYYY-MM-DD)
`payer_document`	string	Yes	Payer's CPF/CNPJ (numbers only)
`payer_name`	string	Yes	Payer's full name
`beneficiary_ispb`	string	Yes	Beneficiary's ISPB (8 digits)
`beneficiary_name`	string	Yes	Beneficiary's name

Value in Cents

The amount_cents field must be sent in cents to avoid precision issues with decimal numbers. For example, R$ 150.50 should be sent as 15050.

Request Example

cURLJavaScriptPython

bash

curl -X POST "https://api.pixconnect.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto": {
      "nosso_numero": "12345678901",
      "amount_cents": 15000,
      "due_date": "2026-03-15",
      "payer_document": "12345678901",
      "payer_name": "Joao Silva Santos",
      "beneficiary_ispb": "02992335",
      "beneficiary_name": "Empresa XYZ Ltda"
    }
  }'

javascript

const response = await fetch(
  "https://api.pixconnect.com.br/api/v1/central/boletos",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      boleto: {
        nosso_numero: "12345678901",
        amount_cents: 15000,
        due_date: "2026-03-15",
        payer_document: "12345678901",
        payer_name: "Joao Silva Santos",
        beneficiary_ispb: "02992335",
        beneficiary_name: "Empresa XYZ Ltda"
      }
    }),
  }
);

const data = await response.json();
console.log(data);

python

import requests

url = "https://api.pixconnect.com.br/api/v1/central/boletos"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "boleto": {
        "nosso_numero": "12345678901",
        "amount_cents": 15000,
        "due_date": "2026-03-15",
        "payer_document": "12345678901",
        "payer_name": "Joao Silva Santos",
        "beneficiary_ispb": "02992335",
        "beneficiary_name": "Empresa XYZ Ltda"
    }
}

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

Success Response

Status: 201 Created

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "barcode": "23793381286000000000000000012345678901500001",
    "linha_digitavel": "23793.38128 60000.000003 00001.234567 8 90150000015000",
    "amount_cents": 15000,
    "due_date": "2026-03-15",
    "payer_document": "12345678901",
    "payer_name": "Joao Silva Santos",
    "beneficiary_ispb": "02992335",
    "beneficiary_name": "Empresa XYZ Ltda",
    "status": "registered",
    "pcr_protocol": "PCR2026021512345678",
    "registered_at": "2026-02-15T10:30:00Z",
    "paid_at": null,
    "cancelled_at": null,
    "inserted_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Possible Errors

Code	Error	Description
`400`	`BAD_REQUEST`	`boleto` field missing from request body
`422`	`VALIDATION_ERROR`	Invalid data (document, date, etc.)
`422`	`DUPLICATE_ENTRY`	`nosso_numero` already exists

Query Boleto

Retrieves the details of a boleto by its reference number.

GET /boletos/:nosso_numero

URL Parameters

Parameter	Type	Description
`nosso_numero`	string	Unique boleto reference number

Request Example

cURLJavaScriptPython

bash

curl -X GET "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "GET",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Success Response

Status: 200 OK

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "barcode": "23793381286000000000000000012345678901500001",
    "linha_digitavel": "23793.38128 60000.000003 00001.234567 8 90150000015000",
    "amount_cents": 15000,
    "due_date": "2026-03-15",
    "payer_document": "12345678901",
    "payer_name": "Joao Silva Santos",
    "beneficiary_ispb": "02992335",
    "beneficiary_name": "Empresa XYZ Ltda",
    "status": "registered",
    "pcr_protocol": "PCR2026021512345678",
    "registered_at": "2026-02-15T10:30:00Z",
    "paid_at": null,
    "cancelled_at": null,
    "inserted_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Possible Errors

Code	Error	Description
`404`	`NOT_FOUND`	Boleto not found

Update Boleto

Updates the data of a boleto. Only boletos with draft status can be updated.

PATCH /boletos/:nosso_numero

URL Parameters

Parameter	Type	Description
`nosso_numero`	string	Unique boleto reference number

Request Body

Field	Type	Description
`amount_cents`	integer	New value in cents
`due_date`	string	New due date (YYYY-MM-DD)
`payer_document`	string	New payer CPF/CNPJ
`payer_name`	string	New payer name

Status Restriction

Only boletos with draft status can be updated. Boletos already registered with Nuclea cannot be modified.

Request Example

cURLJavaScriptPython

bash

curl -X PATCH "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto": {
      "amount_cents": 20000,
      "due_date": "2026-03-20"
    }
  }'

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      boleto: {
        amount_cents: 20000,
        due_date: "2026-03-20"
      }
    }),
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "boleto": {
        "amount_cents": 20000,
        "due_date": "2026-03-20"
    }
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())

Success Response

Status: 200 OK

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "amount_cents": 20000,
    "due_date": "2026-03-20",
    "status": "draft",
    // ... other fields
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Possible Errors

Code	Error	Description
`400`	`BAD_REQUEST`	`boleto` field missing from request body
`404`	`NOT_FOUND`	Boleto not found
`422`	`INVALID_STATUS`	Boleto is not in `draft` status
`422`	`VALIDATION_ERROR`	Invalid data

Cancel Boleto

Cancels an existing boleto.

DELETE /boletos/:nosso_numero

URL Parameters

Parameter	Type	Description
`nosso_numero`	string	Unique boleto reference number

Cancellation

Boletos that are already paid or settled cannot be cancelled. Cancellation is irreversible.

Request Example

cURLJavaScriptPython

bash

curl -X DELETE "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "DELETE",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.json())

Success Response

Status: 200 OK

json

{
  "success": true,
  "data": {
    "nosso_numero": "12345678901",
    "status": "cancelled",
    "cancelled_at": "2026-02-15T14:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Possible Errors

Code	Error	Description
`404`	`NOT_FOUND`	Boleto not found
`422`	`INVALID_STATUS`	Boleto already paid or settled

Mark as Paid

Marks a boleto as paid. This endpoint is used when payment was confirmed externally.

POST /boletos/:nosso_numero/pay

URL Parameters

Parameter	Type	Description
`nosso_numero`	string	Unique boleto reference number

Webhook

When marking a boleto as paid, a boleto.paid webhook is automatically sent to the configured URL.

Request Example

cURLJavaScriptPython

bash

curl -X POST "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901/pay" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}/pay`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}/pay"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

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

Success Response

Status: 200 OK

json

{
  "success": true,
  "data": {
    "nosso_numero": "12345678901",
    "status": "paid",
    "paid_at": "2026-02-15T16:45:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Possible Errors

Code	Error	Description
`404`	`NOT_FOUND`	Boleto not found
`422`	`INVALID_STATUS`	Boleto already paid, settled, or cancelled

Boleto Fields

Returned Fields

Field	Type	Description
`id`	uuid	Unique boleto identifier
`nosso_numero`	string	Reference number (11 digits)
`barcode`	string	Barcode (44 digits)
`linha_digitavel`	string	Typeable line (47 formatted digits)
`amount_cents`	integer	Value in cents
`due_date`	date	Due date
`payer_document`	string	Payer's CPF/CNPJ
`payer_name`	string	Payer's name
`beneficiary_ispb`	string	Beneficiary's ISPB
`beneficiary_name`	string	Beneficiary's name
`status`	string	Current boleto status
`pcr_protocol`	string	PCR registration protocol (when registered)
`registered_at`	datetime	Date/time of Nuclea registration
`paid_at`	datetime	Date/time of payment
`cancelled_at`	datetime	Date/time of cancellation
`inserted_at`	datetime	Date/time of creation
`updated_at`	datetime	Date/time of last update

Next Steps

Settlements - Process settlement files
Webhooks - Receive real-time notifications
Boleto Flow - Understand the complete lifecycle

Boletos ​

Boleto Status ​

Create Boleto ​

Request Body ​

Request Example ​

Success Response ​

Possible Errors ​

Query Boleto ​

URL Parameters ​

Request Example ​

Success Response ​

Possible Errors ​

Update Boleto ​

URL Parameters ​

Request Body ​

Request Example ​

Success Response ​

Possible Errors ​

Cancel Boleto ​

URL Parameters ​

Request Example ​

Success Response ​

Possible Errors ​

Mark as Paid ​

URL Parameters ​

Request Example ​

Success Response ​

Possible Errors ​

Boleto Fields ​

Returned Fields ​

Next Steps ​

Boletos

Boleto Status

Create Boleto

Request Body

Request Example

Success Response

Possible Errors

Query Boleto

URL Parameters

Request Example

Success Response

Possible Errors

Update Boleto

URL Parameters

Request Body

Request Example

Success Response

Possible Errors

Cancel Boleto

URL Parameters

Request Example

Success Response

Possible Errors

Mark as Paid

URL Parameters

Request Example

Success Response

Possible Errors

Boleto Fields

Returned Fields

Next Steps