Payroll
Payroll — Overview
The BTG Empresas Payroll API lets your company manage bulk payments and employee registration in a centralized, secure, and traceable way. This documentation presents the main flows available and how to use them in your day-to-day operation.
Payments Flow
The payments flow is organized around the concept of a batch: a grouping of payments submitted together for processing. This gives your finance team granular control over each remittance, with full traceability of status and transaction history.
Create Payment Batch
The entry point of the flow is submitting a batch. In this step, you group the payments that should be processed in the same remittance. The API supports a wide variety of types, such as salary, advance, vacation, year-end bonus, severance, profit sharing (PLR), pro-labore, internship stipend, benefit, reimbursement, commission, dividends, and others.
When you submit the batch, you define, for each line, the recipient employee, the net amount, the credit bank details, and the date scheduled for execution. The submission is processed asynchronously: the API returns immediately with the batch identifier and processing happens in the background.
Payments Listing
All submitted batches are available for lookup. The listing lets your team track the state of each remittance — identifying batches that are submitted, pending approval, settled, failed, or canceled — and apply filters by period, status, reference, or other criteria relevant to your context.
Attention: the listing applies an implicit time-window filter. Payments outside the default window may not appear even after settlement. Use the startDate and endDate filters to widen the search period when needed.
Payment Batch Details
For each batch, you can access a detailed view with all the payment lines that make it up. This lookup shows the individual status of each transaction, the amounts involved, settlement and failure counters, and any return information from bank processing — such as per-line confirmations or errors.
The final states of a batch are settled, failed, and cancelled. Use this view to audit specific remittances, identify discrepancies, and get a consolidated view of the operation.
Cancel Payment Batch
You can cancel a batch that has already been submitted, provided it is still in the submitted or pending_approval status. Cancellation stops the batch's processing entirely.
This operation is irreversible: once canceled, the batch cannot be reactivated. If you need to reprocess the payments, a new batch must be created.
Employees Flow
Employee management is what makes the payments flow possible: each recipient of a batch must be registered, with a valid bank account and active status on the platform. The API offers endpoints that cover an employee's entire lifecycle — from onboarding to termination and reactivation.
Account Opening Request
For an employee to receive payments via payroll, you must register them and request the opening of a BTG Empresas digital account in their name. The request is made with the employee's registration data — such as CPF, full name, hire date, gross monthly salary, email, phone, address, and ID document with its issuer — and triggers the account analysis and creation process.
The submission is asynchronous: the API returns 202 Accepted immediately, and processing happens in the background. The result can be tracked by looking up the employee's details or the state of their bank account.
Employees Listing
The listing presents all employees linked to your company, with their respective statuses. From this view, you can identify employees with an active account (active), onboarding in progress (pending), a suspended account (suspended), and terminated employees (inactive).
The listing supports filters by status, name, CPF, account type, portability, and contract type, as well as cursor pagination, making it suitable both for use in administrative interfaces and for automated integrations with HR systems.
Account Opening Tracking
Because it is an asynchronous process, account opening can be tracked in two ways: by looking up the employee's status in the general listing (where they appear as pending while onboarding is in progress) or by specifically looking up the employee's bank account data, which returns the current onboarding state, the completion date, and any errors.
We recommend implementing a polling mechanism on these lookups to monitor the status's progress without the need for recurring manual checks.
Employee Details
The details lookup returns the complete profile of a registered employee: their personal data, current status, contract type, portability information, hire and termination dates, suspension state, and the linked bank account information.
Use this lookup to verify an employee's eligibility to receive payments before including them in a batch, or for support and auditing of specific cases.
Deactivate and Activate Employee
When you terminate an employee, you can record the end of the employment relationship on the platform. This operation is available for employees with active status and moves them to inactive status, preventing them from being included in new payment batches. The termination accepts a termination date and reason.
Reactivation is equally available: if the employee returns to the company, they can be reactivated — provided they are in inactive status — returning to active status and becoming eligible again to receive payments via payroll.