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

Gestão de lote de pagamento

Escopos necessários

O token para consumir a API de Gestão de lote de pagamento 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 escolher um dos seguintes escopos:

Workflow

sequenceDiagram
    participant Client
    participant API de gestão de lote
		participant API de pagamentos

    Client->>API de gestão de lote: POST /batch-payments
    API de gestão de lote-->>Client: 201 Created (retorna batchId)

    Client->>API de pagamentos: POST /payments (com batchId no payload do pagamento)
    API de pagamentos-->>Client: 201 Created

    Client->>API de gestão de lote: PATCH /batch-payments/{batchId} (para processar lote)
    API de gestão de lote-->>Client: 200 OK

Realização do fluxo

Para utilização deste recurso, foi criado um fluxo onde:

1. O usuário abre um lote antes de realizar as requisições de criação de pagamentos e transferências:

curl --request POST \
  --url https://api.empresas.btgpactual.com/30306294000145/banking/batch-payments \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/9.3.2' \
  --data '{
  "taxId": "30306294000145"
}'

Esta requisição retorna o identificador do lote batchId:

{
  "batchId": "829c47f2-3b5c-4103-8d15-a55bd66ae905",
  "expiresAt": "2024-11-22T19:18:18.233Z",
  "maxSize": 200,
  "taxId": "46786961000174"
}

2. Este identificador é utizado nas requisições de criação para sinalizar que os pagamentos ou transferências pertecem a aquele lote. Todo objeto de transferência ou pagamento dentro do array de items deve possuir obatchId acompanhado do identificador e agreementId acompanhado de"INDIVIDUAL_APPROVE" .

{
  items:[
    {
      "type": "PIX_MANUAL",
      "batchId": "829c47f2-3b5c-4103-8d15-a55bd66ae905",
      "agreementId": "INDIVIDUAL_APPROVE",
      "amount": 2,
       //demais informações do pagamento...
      "paymentDate": "2024-12-26"
    },
    {
      "type": "PIX_KEY",
      "batchId": "829c47f2-3b5c-4103-8d15-a55bd66ae905",
      "agreementId": "INDIVIDUAL_APPROVE",
      "amount": 7,
       //demais informações do pagamento...
      "paymentDate": "2024-12-26"
    },
    //demais pagamentos...
  ]
}  

3. Após decidir que incluiu os pagamentos ou transferências suficientes no lote, o usuário deverá solicitar a finalização e processamento do lote, por meio de uma requisição PATCH passando como path parameter o seu identificador.

curl --request PATCH \
  --url https://api.empresas.btgpactual.com/30306294000145/banking/batch-payments/829c47f2-3b5c-4103-8d15-a55bd66ae905 \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/9.3.2' \ \
  --data '{
  "isFinished": true
}'

Caso esta requisição não seja realizada e o lote não seja abandonado, o processamento ocorrerá automaticamente após a expiração do lote(dado fornecido juntamente ao identificador quando o lote é criado).

4. Caso o usuário queira abandonar um lote, impedindo que o mesmo seja processado, é possível realizar a seguinte requisição antes de realizar a requisiçãoPATCH de processamento:

curl --request DELETE \
  --url https://api.empresas.btgpactual.com/30306294000145/banking/batch-payments/829c47f2-3b5c-4103-8d15-a55bd66ae905 \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/9.3.2' 

Assim, abandonando o lote informado no path parameter.

Particularidades

Este fluxo é particular no sentido de que ele altera o comportamento da API de pagamentos de algumas formas.

Validações

No momento da request de inserção do pagamento pela request POST realizada, são realizadas validações quanto aos campos inseridos, afim de garantir que todos os campos obrigatórios estão inseridos.

No momento da request de processamento de lote PATCH, são validados os dados presentes no pagamento, subtraindo do lote os pagamentos que não estão aptos a serem realizados.

Retorno de sucesso

O retorno da API de pagamento, quando é inserido um pagamento em um lote, torna-se 202 - ACCEPTED com body vazio.