Settlements

Endpoint to trigger the processing of settlement files (ACMP615) from Nuclea.

Settlement Cycles

Nuclea processes settlements in two daily cycles:

Cycle	Time	Description
Morning	08:30	Processes payments from previous day (afternoon)
Afternoon	16:30	Processes payments from current day (morning)

Automatic Processing

The system automatically processes ACMP615 files after each cycle (08:35 and 16:35). Use this endpoint only for manual reprocessing or testing.

Trigger Processing

Schedules a job to download and process settlement files from Nuclea's FTP.

POST /settlements/trigger

Request Body

All fields are optional. If not provided, default values will be used.

Field	Type	Default	Description
cycle	integer	current cycle	Settlement cycle: 1 (morning) or 2 (afternoon)
date	string	current date	Date to fetch files (YYYY-MM-DD)

Request Example

cURL

curl -X POST "https://api.pixconnect.com.br/api/v1/central/settlements/trigger" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "cycle": 1,
    "date": "2026-02-15"
  }'

JavaScript

const response = await fetch(
  "https://api.pixconnect.com.br/api/v1/central/settlements/trigger",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cycle: 1,
      date: "2026-02-15"
    }),
  }
);

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

Python

import requests

url = "https://api.pixconnect.com.br/api/v1/central/settlements/trigger"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "cycle": 1,
    "date": "2026-02-15"
}

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

Success Response

Status: 202 Accepted

{
  "success": true,
  "data": {
    "job_id": 12345,
    "date": "2026-02-15",
    "cycle": 1,
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Asynchronous Processing

The endpoint returns immediately with status 202 Accepted and a job_id. Processing occurs in the background. Use webhooks to be notified when processing is complete.

Possible Errors

Code	Error	Description
500	JOB_QUEUE_FAILED	Failed to queue the processing job

---

Settlement Flow

The diagram below illustrates the complete settlement processing flow:

+------------------------------------------------------------------+
|                    Settlement Flow                                |
+------------------------------------------------------------------+

  +----------+         +----------+         +----------+
  |   API    |         |  Oban    |         |   FTP    |
  | Request  |---------|   Job    |---------|  Nuclea  |
  +----------+         +----------+         +----------+
       |                    |                    |
       |  POST /trigger     |                    |
       |------------------->|                    |
       |                    |                    |
       |  202 Accepted      |  Download ACMP615  |
       |<-------------------|------------------>|
       |  (job_id: 12345)   |                    |
       |                    |<-------------------|
       |                    |   (.txt file)      |
       |                    |                    |
       |              +-----+-----+              |
       |              |  Parser   |              |
       |              |  ACMP615  |              |
       |              +-----+-----+              |
       |                    |                    |
       |              +-----+-----+              |
       |              | Reconcile |              |
       |              |  Boletos  |              |
       |              +-----+-----+              |
       |                    |                    |
       |              +-----+-----+              |
       |              |  Webhook  |              |
       |              |  boleto.  |              |
       |              |  settled  |              |
       |              +-----------+              |

ACMP615 File

The ACMP615 file is Nuclea's settlement file that contains processed payments.

File Structure

Record Type	Description
00	File header
20	Payment record
99	File trailer

Payment Record Fields (Type 20)

Position	Field	Description
1-2	tipo_registro	Always "20"
3-13	nosso_numero	Boleto reference
14-30	valor_pago	Amount paid in cents
31-38	data_pagamento	Payment date (YYYYMMDD)
39-46	hora_pagamento	Payment time (HHMMSS)

Related Webhooks

After settlement processing, the following webhooks may be triggered:

Event	Description
boleto.settled	Boleto settled - funds transferred
cycle.completed	Settlement cycle completed

For more details, see the Webhooks documentation.

Next Steps

• Health Check - Verify FTP configuration
• Settlement Flow - Complete process guide
• Webhooks - Configure notifications