Skip to main content

Ficha técnica

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:

EscopoDescrição
brn:btg:empresas:banking:paymentsPermite criar e consultar pagamentos.

Workflow​

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"
}
  1. Este identificador é utizado nas requisições de criação para sinalizar que os pagamentos ou transferências pertecem a aquele lote. O 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"
    },
  ]
}
  1. Após isso, 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).

  1. 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.