Segurança

📘

BTG Id

O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

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:

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 issuingAuthority aceita apenas os códigos retornados pelo endpoint GET /{companyId}/banking/payroll/onboarding/issuers. Valores fora dessa lista são rejeitados com 400 Bad Request.

Requisição — POST /{companyId}/banking/payroll/onboarding/employees

[
  {
    "companyTaxId": "12345678000190",
    "name": "Carlos Eduardo Mendes",
    "taxId": "34567890123",
    "email": "[email protected]",
    "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" }
  }
}