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.
Liberação da API
Para você utilizar a API, você deve entrar em contato com o seu executivo comercial. Ele irá fornecer todas as informações e orientações necessárias para a ativação dessa funcionalidade.
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 1 day ago