Ficha técnica
Escopos necessários
O token para consumir a API de Folha de pagamentos deve ser gerado usando o Authorization Code.
O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.
É necessário incluir o seguintes escopo:
| Escopo | Descrição |
|---|---|
| brn:btg:empresas:banking:payroll | Permite o manuseio completo da API de Folha de Pagamentos |
Folha de Pagamento — Visão Geral da API
A API de Folha de Pagamento do BTG Empresas permite que sua empresa gerencie pagamentos em massa e o cadastro de colaboradores de forma centralizada, segura e rastreável. Esta documentação apresenta os principais fluxos disponíveis e como utilizá-los no dia a dia da sua operação.
Fluxo de Pagamentos
O fluxo de pagamentos é organizado em torno do conceito de lote: um agrupamento de pagamentos submetidos juntos para processamento. Isso permite que sua equipe financeira tenha controle granular sobre cada remessa, com rastreabilidade completa de status e histórico de transações.
Criar Lote de Pagamento
O ponto de entrada do fluxo é a submissão de um lote. Nesta etapa, você agrupa os pagamentos que devem ser processados em uma mesma remessa. A API suporta uma ampla variedade de modalidades, como salário, adiantamento, férias, décimo terceiro, rescisão, PLR, pró-labore, bolsa de estágio, benefício, reembolso, comissão, dividendos e outras.
Ao submeter o lote, você define para cada linha o colaborador destinatário, o valor líquido, os dados bancários de crédito e a data agendada para execução. A submissão é processada de forma assíncrona: a API retorna imediatamente com o identificador do lote e o processamento ocorre em segundo plano.
Requisição — POST /{companyId}/banking/payroll/payments
{
"description": "Folha de Pagamento - Junho 2026",
"scheduledDate": "2026-06-30T00:00:00Z",
"paymentType": 2,
"companies": [
{
"taxId": "12345678000190",
"debitParty": {
"branchCode": "0001",
"number": "123456-7"
},
"items": [
{
"taxId": "12345678901",
"bankCode": "208",
"branchCode": "0001",
"accountNumber": "987654-3",
"netAmount": 4500.00,
"reference": "João Silva - Salário Jun/2026"
},
{
"taxId": "98765432100",
"bankCode": "208",
"branchCode": "0001",
"accountNumber": "112233-4",
"netAmount": 7200.00,
"reference": "Maria Souza - Salário Jun/2026"
}
]
}
]
}
O header
X-Idempotency-Key(UUID v4) é obrigatório para evitar processamento duplicado em caso de retentativa.
Resposta — 202 Accepted
{
"requestId": "a3f1b2c4-9d8e-4f5a-b6c7-d8e9f0a1b2c3",
"paymentId": 78432,
"status": "submitted",
"submittedAt": "2026-06-17T14:23:11Z",
"totalEmployees": 2,
"totalAmount": 11700.00,
"scheduledDate": "2026-06-30T00:00:00Z"
}
Guarde o requestId e o paymentId retornados: eles são usados nas operações de consulta e cancelamento do lote.
Listagem de Pagamentos
Todos os lotes submetidos ficam disponíveis para consulta. A listagem permite que sua equipe acompanhe o estado de cada remessa — identificando lotes submetidos, em aprovação, liquidados, com falha ou cancelados — e aplique filtros por período, status, referência ou outros critérios relevantes para o seu contexto.
Atenção: a listagem aplica um filtro implícito por janela de tempo. Pagamentos fora da janela padrão podem não aparecer mesmo após liquidação. Utilize os filtros startDate e endDate para ampliar o período de busca quando necessário.
Resposta — GET /{companyId}/banking/payroll/payments?startDate=2026-06-01&endDate=2026-06-30
{
"links": {
"next": { "href": "/btg-company/banking/payroll/payments?cursor=eyJwYWdlIjoyfQ==" },
"prev": null
},
"data": [
{
"requestId": "a3f1b2c4-9d8e-4f5a-b6c7-d8e9f0a1b2c3",
"paymentId": 78432,
"reference": "Folha de Pagamento - Junho 2026",
"scheduledDate": "2026-06-30",
"debitDate": "2026-06-30",
"status": "settled",
"paymentType": "PAG_SALARIO",
"validatedAmount": 11700.00,
"originalAmount": 11700.00,
"paidAmount": 11700.00,
"errorTransferCount": 0,
"company": {
"name": "Empresa Exemplo Ltda",
"taxId": "12345678000190",
"account": { "branch": "0001", "number": "123456-7" }
},
"links": {
"self": { "href": "/btg-company/banking/payroll/payments/78432" }
}
}
]
}
Detalhes do Lote de Pagamento
Para cada lote, é possível acessar uma visão detalhada com todas as linhas de pagamento que o compõem. Esta consulta exibe o status individual de cada transação, os valores envolvidos, contadores de liquidações e falhas, e qualquer informação de retorno do processamento bancário — como confirmações ou erros por linha.
Os estados finais de um lote são settled (liquidado), failed (falhou) e cancelled (cancelado). Use esta visão para auditar remessas específicas, identificar divergências e obter a visão consolidada da operação.
Resposta — GET /{companyId}/banking/payroll/payments/78432
{
"paymentId": 78432,
"description": "Folha de Pagamento - Junho 2026",
"status": "settled",
"debitParty": { "branchCode": "0001", "number": "123456-7" },
"submittedAt": "2026-06-17T14:23:11Z",
"approvedAt": "2026-06-17T15:00:00Z",
"settledAt": "2026-06-30T10:15:33Z",
"cancelledAt": null,
"scheduledDate": "2026-06-30T00:00:00Z",
"totalEmployees": 2,
"totalAmount": 11700.00,
"settledCount": 2,
"failedCount": 0,
"items": [
{
"employeeId": "emp-001",
"name": "João Silva",
"taxId": "12345678901",
"line": 1,
"paymentType": "PAG_SALARIO",
"netAmount": 4500.00,
"status": "settled",
"transactionStatus": "LIQUIDADO",
"settledAt": "2026-06-30T10:15:33Z",
"failureReason": null
},
{
"employeeId": "emp-002",
"name": "Maria Souza",
"taxId": "98765432100",
"line": 2,
"paymentType": "PAG_SALARIO",
"netAmount": 7200.00,
"status": "settled",
"transactionStatus": "LIQUIDADO",
"settledAt": "2026-06-30T10:15:33Z",
"failureReason": null
}
],
"links": {
"self": { "href": "/btg-company/banking/payroll/payments/78432" },
"cancel": null
}
}
Cancelar Lote de Pagamento
É possível cancelar um lote que já foi submetido, desde que ele ainda esteja nos status submitted (submetido) ou pending_approval (aguardando aprovação). O cancelamento interrompe o processamento do lote integralmente.
Esta operação é irreversível: uma vez cancelado, o lote não pode ser reativado. Caso necessite reprocessar os pagamentos, um novo lote deverá ser criado.
Requisição — POST /{companyId}/banking/payroll/payments/{requestId}/cancel
{
"reason": "Erro nos valores informados. Novo lote será submetido em seguida."
}
Resposta — 200 OK
A resposta confirma o cancelamento sem corpo adicional. Para verificar o estado atualizado do lote, consulte os detalhes via GET /payments/{paymentId}.
Fluxo de Colaboradores
O gerenciamento de colaboradores é o que viabiliza o fluxo de pagamentos: cada destinatário de um lote precisa estar cadastrado, com conta bancária válida e status ativo na plataforma. A API oferece endpoints para cobrir todo o ciclo de vida de um colaborador — do onboarding até o desligamento e reativação.
Solicitação de Abertura de Conta
Para que um colaborador possa receber pagamentos via folha, é necessário cadastrá-lo e solicitar a abertura de uma conta digital BTG Empresas em seu nome. A solicitação é feita com os dados cadastrais do colaborador — como CPF, nome completo, data de admissão, salário bruto mensal, e-mail, telefone, endereço e documento de identidade com o respectivo emissor — e desencadeia o processo de análise e criação da conta.
A submissão é assíncrona: a API retorna 202 Accepted imediatamente, e o processamento ocorre em segundo plano. O resultado pode ser acompanhado consultando os detalhes do colaborador ou o estado da sua conta bancária.
O campo
issuingAuthorityaceita apenas os códigos retornados pelo endpointGET /{companyId}/banking/payroll/onboarding/issuers. Valores fora dessa lista são rejeitados com400 Bad Request.
Requisição — POST /{companyId}/banking/payroll/onboarding/employees
[
{
"companyTaxId": "12345678000190",
"name": "Carlos Eduardo Mendes",
"taxId": "34567890123",
"email": "carlos.mendes@empresa.com.br",
"phone": "11987654321",
"admissionDate": "2026-06-01",
"grossMonthlySalary": 5800.00,
"accountType": "CHECKING",
"idNumber": "12.345.678-9",
"issuingAuthority": "SSP-SP",
"address": {
"street": "Rua das Flores",
"number": "42",
"neighborhood": "Vila Madalena",
"zipCode": "05443000"
},
"isUnderage": false
}
]
Resposta — 202 Accepted
{
"status": "accepted"
}
Listagem de Colaboradores
A listagem apresenta todos os colaboradores vinculados à sua empresa, com seus respectivos status. A partir desta visão, é possível identificar colaboradores com conta ativa (active), onboarding em andamento (pending), conta suspensa (suspended) e colaboradores desligados (inactive).
A listagem suporta filtros por status, nome, CPF, tipo de conta, portabilidade e tipo de contrato, além de paginação por cursor, sendo adequada tanto para uso em interfaces administrativas quanto para integrações automatizadas com sistemas de RH.
Resposta — GET /{companyId}/banking/payroll/employees?status=active&pageSize=2
{
"data": [
{
"name": "João Silva",
"taxId": "12345678901",
"status": "active",
"isActive": true,
"onboardingCompleted": "true",
"isSuspended": false,
"admissionDate": "2024-03-01T00:00:00Z",
"terminationDate": null,
"company": { "name": "Empresa Exemplo Ltda", "taxId": "12345678000190" },
"accounts": [
{ "type": "CHECKING", "status": "active", "bankCode": "208", "branch": "0001", "number": "987654-3" }
],
"links": { "self": { "href": "/btg-company/banking/payroll/employees/12345678901" } }
},
{
"name": "Maria Souza",
"taxId": "98765432100",
"status": "active",
"isActive": true,
"onboardingCompleted": "true",
"isSuspended": false,
"admissionDate": "2023-07-15T00:00:00Z",
"terminationDate": null,
"company": { "name": "Empresa Exemplo Ltda", "taxId": "12345678000190" },
"accounts": [
{ "type": "CHECKING", "status": "active", "bankCode": "208", "branch": "0001", "number": "112233-4" }
],
"links": { "self": { "href": "/btg-company/banking/payroll/employees/98765432100" } }
}
],
"links": {
"next": { "href": "/btg-company/banking/payroll/employees?cursor=eyJwYWdlIjoyfQ==&status=active" },
"previous": null
}
}
Acompanhamento da Abertura de Conta
Por ser um processo assíncrono, a abertura de conta pode ser acompanhada de duas formas: consultando o status do colaborador na listagem geral (onde aparecerá como pending enquanto o onboarding estiver em andamento) ou consultando especificamente os dados da conta bancária do colaborador, que retorna o estado atual do onboarding, a data de conclusão e eventuais erros.
Recomenda-se implementar um mecanismo de polling nessas consultas para monitorar a evolução do status sem a necessidade de verificações manuais recorrentes.
Resposta — GET /{companyId}/banking/payroll/employees/{employeeTaxId}/account
Conta ainda em processamento:
{
"employeeId": "emp-003",
"accountType": "CHECKING",
"status": "pending",
"onboardingFinalizado": false,
"onboardingFinishedAt": null,
"errors": null,
"bank": null,
"agency": null,
"number": null,
"links": {
"self": { "href": "/btg-company/banking/payroll/employees/34567890123/account" },
"employee": { "href": "/btg-company/banking/payroll/employees/34567890123" }
}
}
Conta ativada com sucesso:
{
"employeeId": "emp-003",
"accountType": "CHECKING",
"status": "active",
"onboardingFinalizado": true,
"onboardingFinishedAt": "2026-06-18T09:42:00Z",
"errors": null,
"bank": "208",
"agency": "0001",
"number": "445566-7",
"links": {
"self": { "href": "/btg-company/banking/payroll/employees/34567890123/account" },
"employee": { "href": "/btg-company/banking/payroll/employees/34567890123" }
}
}
Detalhes do Colaborador
A consulta de detalhes retorna o perfil completo de um colaborador cadastrado: seus dados pessoais, status atual, tipo de contrato, informações de portabilidade, datas de admissão e desligamento, estado de suspensão e as informações de conta bancária vinculada.
Use esta consulta para verificar a elegibilidade de um colaborador para receber pagamentos antes de incluí-lo em um lote, ou para suporte e auditoria de casos específicos.
Resposta — GET /{companyId}/banking/payroll/employees/{employeeTaxId}
{
"employeeId": "emp-001",
"name": "João Silva",
"taxId": "12345678901",
"status": "active",
"contractType": "CLT",
"portability": false,
"admissionDate": "2024-03-01T00:00:00Z",
"terminationDate": null,
"suspended": false,
"suspensionEndDate": null,
"accounts": [
{ "type": "CHECKING", "status": "active", "agency": "0001", "number": "987654-3" }
],
"company": { "cnpj": "12345678000190", "name": "Empresa Exemplo Ltda" },
"links": {
"self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
"deactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/deactivate", "method": "POST" },
"reactivate": null
}
}
Inativar e Ativar Colaborador
Ao desligar um colaborador, é possível registrar o encerramento do vínculo empregatício na plataforma. Esta operação está disponível para colaboradores com status active e os move para o status inactive, impedindo que sejam incluídos em novos lotes de pagamento. O desligamento aceita data de rescisão e motivo.
Requisição — POST /{companyId}/banking/payroll/employees/{employeeTaxId}/deactivate
{
"terminationDate": "2026-06-30",
"reason": "Demissão sem justa causa"
}
Resposta — 200 OK
{
"employeeId": "emp-001",
"status": "inactive",
"terminationDate": "2026-06-30",
"requestedAt": "2026-06-17T16:05:22Z",
"links": {
"self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
"reactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/reactivate", "method": "POST" }
}
}
A reativação é igualmente disponível: caso o colaborador retorne à empresa, ele pode ser reativado — desde que esteja no status inactive — voltando ao status active e tornando-se elegível novamente para receber pagamentos via folha.
Requisição — POST /{companyId}/banking/payroll/employees/{employeeTaxId}/reactivate
Sem corpo de requisição.
Resposta — 200 OK
{
"employeeId": "emp-001",
"status": "active",
"reactivatedAt": "2026-08-01T09:10:00Z",
"links": {
"self": { "href": "/btg-company/banking/payroll/employees/12345678901" },
"deactivate": { "href": "/btg-company/banking/payroll/employees/12345678901/deactivate", "method": "POST" }
}
}