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âmetro | Descrição |
|---|---|
Authorization | Contem 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). |
key | Arquivo com extensão .key contendo a chave privada do certificado digital criada anteriormente. |
cert | Arquivo com extensão .pem contendo o certificado digital criado anteriormente. |
grant_type | Indica o tipo de autenticação utilizada e deve assumir o valor client_credentials. |
scope | Define 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ência | Descrição |
|---|---|
| CREATED | Esse estado é enviado na resposta da requisição de criação da transferência. Indica que a solicitação foi recebida com sucesso. |
| PROCESSING | Indica que a transferência está em andamento, mas não foi finalizada. |
| SUCCESS | Indica que a transferêcnia foi concluída com sucesso; |
| FAILED | Indica 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
idde identificação da transferência recebido na resposta à criação da transferência. Você também precisa fornecer oaccess_tokencriado anteriormente e ele deve ter sido criado com oscopetransfer.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.
Updated about 2 months ago