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.