💸 Boleto Payments: How to Use It

🔍 What is the Boleto Payments?

The Boleto Payments API (v2) allows you to programmatically manage and execute boleto bancário payments (bank slips) in Brazil, including both:

• Manual boletos (initiated via barcode)
• DDA (Débito Direto Autorizado) pre-authorized invoices retrieved automatically from financial institutions

You can use this API to:

• Fetch and display pending DDA bills
• Initiate boleto payments (DDA or manual)
• Retrieve a complete payment history

📌 Available Endpoints

Operation	Endpoint	Method
Get all DDA invoices	/v2/payments/dda	GET
Get DDA invoice by UUID	/v2/payments/dda/{uuid}	GET
Create boleto payment	/v2/payments	POST
Get all boleto payments	/v2/payments	GET

1️⃣ Get all DDA invoices

Use this endpoint to retrieve all DDA invoices (pending or unpaid) available to your company. These invoices are issued by suppliers or creditors and automatically associated with your account by the banking network.

🔗 Endpoint

GET /v2/payments/dda

📤 cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

JSON

[
  {
    "uuid": "dda-uuid-001",
    "issuer": "Empresa XYZ",
    "amount": 350.75,
    "dueDate": "2025-07-20",
    "status": "PENDING"
  }
]

2️⃣ Get DDA Invoice by UUID

Use this endpoint to retrieve detailed information for a specific DDA invoice using its uuid.

🔗 Endpoint

GET /v2/payments/dda/{uuid}

📤 cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments/dda/dda-uuid-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

JSON

{
  "uuid": "dda-uuid-001",
  "issuer": "Empresa XYZ",
  "amount": 350.75,
  "dueDate": "2025-07-20",
  "status": "PENDING",
  "barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}

3️⃣ Create a Boleto Payment

Use this endpoint to initiate a boleto payment using a valid barcodeDigitableLine. This works for both DDA and manually obtained boletos.

You can optionally attach metadata to link this payment to specific internal processes.

🔗 Endpoint

POST /v2/payments

📤 cURL Request

cURL

curl -X POST \
"https://public-api.mx.clara.com/api/v2/payments" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "barcodeDigitableLine": "23791887700000350758091001100123456789000000000"
}'

📥 Sample JSON Response

JSON

{
  "uuid": "payment-uuid-001",
  "status": "PROCESSING",
  "amount": 350.75,
  "dueDate": "2025-07-20",
  "executedAt": "2025-07-18T12:00:00Z"
}

4️⃣ Get All Boleto Payments

Use this endpoint to retrieve the list of all boleto payments initiated from your account, including both DDA and manual payments.

You can apply filters such as status, startDate, or endDate.

🔗 Endpoint

GET /v2/payments

📤 cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/payments?status=SUCCESS&startDate=2025-07-01" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

JSON

[
  {
    "uuid": "payment-uuid-001",
    "barcodeDigitableLine": "23791887700000350758091001100123456789000000000",
    "amount": 350.75,
    "status": "SUCCESS",
    "executedAt": "2025-07-18T12:00:00Z"
  },
  {
    "uuid": "payment-uuid-002",
    "barcodeDigitableLine": "00193373700000001000500940144816060652304638300",
    "amount": 100.00,
    "status": "FAILED",
    "executedAt": "2025-07-15T10:30:00Z"
  }
]

💡 Tip: Use the DDA endpoints to show users their pre-approved invoices. You can pay them by simply passing the barcodeDigitableLine to the /v2/payments endpoint.

⚠️ Note: All payments must comply with due dates and available balance. Payment execution is not guaranteed if validation fails or if the boleto is expired.