Transferências

A API de Transferências do PagBank possibilita que você realize movimentações de saldo entre contas PagBank ou para contas de outras instituições bancárias. Por esse motivo, o PagBank disponibiliza dois tipos de transferências:

  • Transferências P2P: é uma transferência interna, utilizada para movimentar saldo entre contas PagBank.
  • Transferência PIX: é uma transferência externa que utiliza o sistema PIX. Com ela é possível movimentar saldo de uma conta PagBank para outra conta, pertencente a outro domicílio bancário.

A integração para os dois tipos ofertados é o mesmo, o que diferencia é o tipo da transferência (type) enviado no momento da solicitação. Portanto, você deve saber qual o tipo de transação deseja solicitar e enviar corretamente os dados solicitados em cada um dos cenários para que a identificação da conta destino seja realizada.

O tempo médio para a efetivação das transferências é de 1 minuto. No entanto, o prazo máximo é de 24 horas.

📘

Restrições no número de transferências PIX

Existe uma restrição de requisições por minuto para transferências do tipo PIX. Para identificar esse limite, você deve entrar em contato com o seu executivo comercial.

Pré-requisitos

Para utilizar a API de transferência é necessário que você já tenha completado dois passos anteriores:

  • Criado o seu certificado digital.
  • Criado uma aplicação.

Caso você ainda não disponha do certificado digital, acesse a página de Introdução ao certificado digital para ter acesso ao guia de criação do seu certificado.

Por outro lado, se você ainda não criou uma aplicação, você irá utilizar o endpoint Criar aplicação. Através desse endpoint você irá receber os parâmetros client_id e client_secret, utilizados para identificar a sua aplicação. Utilize a página de Connect para obter mais informações mais detalhadas acerca do processo de criação de aplicações.

Realize uma transferência

Além de realizar os passos de pré-requisito, você deverá possuir alguns dados antes de iniciar o processo de transferência. Para realizar uma transferência entre contas PagBank (P2P) é necessário informar a agência (bank_branch) e número da conta (account_number) ou o account_id da conta destino. Caso a transferência seja para uma conta externa, é necessário ter a chave PIX ou os dados bancários do recebedor. Com esses dados em mãos, você pode iniciar o processo de criação de uma transferência.

Primeiramente, você deve obter um token de acesso (access_token) para transferências. Esse token representa a concessão do usuário para que você realize a transferência em seu nome. Para isso, você irá utilizar o endpoint Obter access token para transferência. Nesse endpoint você deverá fornecer os seguintes dados:

ParâmetroDescrição
AuthorizationContem as informações do client_id e client_secret codificados em base64. As informações devem ser informadas seguindo o padrão (client_id:client_secret).
keyArquivo com extensão .key contendo a chave privada do certificado digital criada anteriormente.
certArquivo com extensão .pem contendo o certificado digital criado anteriormente.
grant_typeIndica o tipo de autenticação utilizada e deve assumir o valor client_credentials.
scopeDefine o escopo do access_token. Existem dois valores possíveis, transfer.create e transfer.read, habilitando a criação e a consulta de transferência, respectivamente. Você pode encaminhar ambos os valores na mesma requisição para que ambas ações sejam habilitadas.

Após obter o access_token, você está apto a solicitar a transferência utilizando o endpoint Criar transferência. Você deverá definir o valor da transferência e identificar o usuário de destino. Caso esta transferência seja para outra conta PagBank, a identificação do usuário de destino será feita pelo email ou account_id. Já se a transferência utilizará for externa, utilizando o PIX, você deverá fornecer a chave PIX ou os dados da conta bancária de destino. Por se tratar de uma operação assíncrona, você também precisa fornecer uma URL para recebimento da confirmação da transferência.

Consulte o estado de uma transferência

Após a sua criação, a transferência pode assumir 4 diferentes estados, apresentados na tabela a seguir:

Estado da transferênciaDescrição
CREATEDEsse estado é enviado na resposta da requisição de criação da transferência. Indica que a solicitação foi recebida com sucesso.
PROCESSINGIndica que a transferência está em andamento, mas não foi finalizada.
SUCCESSIndica que a transferêcnia foi concluída com sucesso;
FAILEDIndica que a solicitação de transferência não foi finalizada com sucesso. Isso pode ocorrer se:
• A solicitação foi reprovada pelo PagBank.
• Ela não foi autorizada pelo requisitante.
• O tempo de autorização, relacionado com a validade do access_token, foi ultrapassado.

Para verificar o atual estado da transferência, o PagBank disponibiliza dois endpoints de pesquisa:

  • Consultar transferência pelo ID: consulte uma transferência específica fornecendo o id de identificação da transferência recebido na resposta à criação da transferência. Você também precisa fornecer o access_token criado anteriormente e ele deve ter sido criado com o scope transfer.read, do contrário você não conseguirá realizar a consulta.
  • Consultar transferência pelo ID do cliente ou período: consulte transferências vinculadas a um cliente ou referentes a um período específico. Como várias transferências podem ser retornadas, esse endpoint disponibiliza a opção de utilizar paginação. A ordem das transferências é padrão, com as mais antigas sempre sendo retornadas primeiro. Além disso, apenas transferências realizadas nos últimos 4 meses podem ser retornadas. Caso você precise de um histórico mais extenso, entre em contato com o time de suporte do PagBank.

Teste a API e trate erros

Para avaliar a sua utilização da API de Transferência, o PagBank disponibiliza uma série de cenários de teste que você pode utilizar. Para visualizar esses cenários de teste, acesse a página Teste da API de Transferências. Por outro lado, se você deseja identificar a causa de erros associados ao uso da API de Transferência, acesse Códigos de erro.