Introdução ao Connect

Nesta página, você encontrará os passos principais para conectar sua aplicação ao sistema PagBank. E-commerce, Marketplaces e sistemas de conciliação são exemplos de aplicações que podem ser conectadas ao PagBank. Ao fazer essa integração, sua aplicação será capaz de executar ações em nome dos usuários do PagBank. Para isso, é necessário registrar sua aplicação no PagBank e estabelecer a conexão com as contas dos usuários, caso eles já tenham uma conta aberta.

📘

Definição de usuário

Quando mencionamos usuário ao longo da documentação da API Connect, nos referimos ao vendedor. Ou seja, ao dono ou responsável pela aplicação criada.

O usuário/vendedor terá sua conta vinculada à aplicação e essa aplicação realizará ações em seu nome.

Utilizando a API Connect

O primeiro passo é criar uma aplicação no sistema PagBank, que corresponde ao seu E-commerce, por exemplo. Durante esse processo, você fornecerá informações necessárias para identificar o seu negócio, como nome, descrição e logotipo, além de definir o URL de redirecionamento após a aprovação das permissões pelo usuário. Para criar a sua aplicação, utilize o endpoint Criar aplicação. Na resposta são fornecidos parâmetros de identificação da sua applicação, client_id e account_id.

Caso você queira recuperar os dados da sua aplicação, você pode utilizar o endpoint Consultar aplicação.

Receba autorização do usuário

Depois de criar uma aplicação no PagBank e integrá-la ao seu sistema, como segundo passo você precisa da autorização do vendedor para realizar ações em seu nome. Nesta etapa, você pode solicitar a autorização e obter um codigo de confirmação de duas maneiras diferentes, utilizando o Connect Authorization ou o Connect via SMS:

• Connect Authorization: Este método permite que você solicite a autorização dos vendedores através de um processo de autenticação padrão, redirecionando o usuário para uma página PagBank. Acesse a seção Connect Authorization para mais detalhes.
• Connect via SMS (Autorização via SMS): Com esse método, você pode solicitar a autorização dos vendedores através do envio de um código de autenticação via SMS. Para utilizar o Connect SMS, utilize o endpoint Solicitar permissão via SMS. A permissão concedida usando o Connect SMS permite apenas criar transações e realizar consultas. No entanto, não é possível realizar estornos nem acessar dados cadastrais do vendedor por meio dessa forma de autorização. Acesse a seção Connect via SMS para mais detalhes.

📘

Connect Authorization ou Connect via SMS

Ambas as soluções permitem que você receba a autorização para efetuar ações em nome do usuário.

Com o Connect Autorization, essa autorização será concedida através de uma página do PagBank.

Utilizando o Connect via SMS, a autorização pode ser realizada inteiramente no seu sistema, utilizando endpoints para requisitar os dados ao usuário e transferir os códigos de acesso.

Ao final do processo de autorização, independente de qual foi utilizado, você terá em mãos o código de confirmação do vendedor.

Obtenha o token de acesso

No terceiro e último passo do processo de conexão, você utilizará o código de confirmação para obter o token de acesso (access_token). O access_token será utilizado em requisições futuras e confirmará a sua autenticidade ao realizar operações em nome desse vendedor. Portanto, você deve armazenar o access_tokenem seu sistema e vinculá-lo ao vendedor correspondente. Para obter o access_token você utilizará o endpoint Obter access token. Siga para a seção Access token para maiores informações.

A imagem a seguir sumariza o fluxo principal da API Connect:

Operações complementares

Além dos três passos descritos, a API Connect fornece endpoints adicionais para contemplar serviços complementares:

• Renovar access token: Utilizado para renovar a validade do access_token.
• Revogar access token: Revoga o acesso à conta de um vendedor.

Por fim, a API Connect também incorpora o processo de utilização de autenticação de dois fatores. Acesse a página Connect challenge para entender como utilizar essa solução.

Connect Authorization

Os passos relacionados ao processos de autorização usando o Connect Authorization são apresentados a seguir:

1. Você deve redirecionar o usuário para a página do PagBank. As informações relacionadas às permissões que você irá requisitar para o usuário serão fornecidas como query params na URL de redirecionamento. A tabela a seguir informa todos os possíveis parâmetros que podem ser incorporados na URL.

   Parâmetro	Tipo	Descrição
   client_id	String (36 caracteres)	Identificador único fornecido no momento da criação da aplicação.
   response_type	String (ENUM)	Define o tipo de resposta desejado. Por padrão utilize code.
   redirect_uri	String (5 - 350 caracteres)	URL para o redirecionamento do usuário após a autorização. Deve ser a mesma utilizada na criação da aplicação.
   scope	String (150 caracteres)	Permissões de acesso solicitadas.
   code	String (32 caracteres)	Código de autorização. Você trocará ele por um access_token. O código só pode ser usado uma única vez e tem a válidade de 10 min.
   state	Alfanumérico (128 caracteres)	Possibilita o repasse de informações necessárias para sua autorização. O concedente pode utilizar para controlar o acesso.

   O parâmetro scopedefine o nível de permissão atribuído ao vendedor. Os possíveis valores para scope e as permissões relacionadas são apresentados a seguir:

   • payments.read: Permissão para visualizar pedidos e cobranças.
   • payments.create: Permissão para criar e visualizar pedidos e cobranças.
   • payments.refund: Permissão para fazer reembolsos.
   • accounts.read: Permissão para consultar os dados de cadastro do vendedor.

   Caso deseje adicionar mais de uma permissão, combine seus identificadores usando o símbolo "+": payments.read+payments.create.

   A seguir é apresentado um exemplo de URL para o ambiente Sandbox:

   URL Sandbox

   <https://connect.sandbox.pagseguro.uol.com.br/oauth2/authorize?response_type=code&client_id=partner_client_id&redirect_uri=partner_callback_url&scope=scope.name1+scope.name2&state=xyz>
   

   Para o ambiente de Produção, a seguinte URL base deve ser utilizada:

   URL Base Produção

   https://connect.pagseguro.uol.com.br/oauth2/authorize?
   

   Você tem a opção de utilizar a página Solicitar autorização via Connect Authorization para construir essa URL. No entanto, é importante ressaltar que esse não é um endpoint. Você deve utilizar a URL gerada para redirecionar o seu usuário.

2. Se o vendedor já possui uma conta no PagBank, ele será solicitado a fazer login para visualizar as permissões que serão concedidas.

   1. No caso do ambiente Sandbox, será necessário utilizar informações do vendedor teste para realizar o login. Para obter as informações do vendedor teste você deve acessar a sua conta Sandbox. Caso ainda não tenha uma conta se registre acessando a página do PagBank Sandbox. Depois, no menu Perfil de Integração, acesse Aplicação e obtenha e-maile senha do vendedor teste. Utilize essas informações para finalizar o passo 2.

3. Após revisar as permissões, o vendedor pode aprovar ou negar o acesso. Se o vendedor aprovar as permissões, ele será redirecionado para a redirect_uri com um código de aprovação (code). A seguir é apresentado um exemplo para a URL para a qual o usuário poderia ser redirecionado:

   redirect_uri resultante

   \<redirect_uri>?code\<code_fornecido_PagBank>&state=\<valor_fornecido_passo_1>
   

4. Utilize o código code e o endpoint Obter access token para obter o access_token utilizado para autorizar operações futuras relacionadas a esse vendedor. Confira mais informações na seção Access token.

🚧

Validade do código

O código code só pode ser usado uma única vez e tem a válidade de 10 minutos.

📘

Mudança de e-mail pelo usuário

Se o usuário alterar o e-mail usado para autorizar a aplicação no PagBank, será necessário realizar uma nova autorização usando o novo e-mail.

Connect via SMS

Para utilizar a autorização através do Connect SMS é necessário que o usuário esteja cadastrado no PagBank. Os passos relacionados ao processos de autorização usando o Connect SMS são apresentados a seguir:

1. Para solicitar autorização de forma transparente, sem redirecionar o vendedor para o ambiente do PagBank, você precisará informar o e-mail do usuário cadastrado no PagBank. Com o e-mail do usuário e as informações da sua applicação (X_CLIENT_ID e X_CLIENT_SECRET), utilize o endpoint Solicitar autorização via SMS. A imagem a seguir exemplifica esse passo:
   
   

2. O vendedor receberá o SMS de confirmação no seu telefone cadastrado contendo o sms_code que deve ser fornecido à sua applicação.
3. Utilize o código sms_code e o endpoint Obter access token para obter o access_token utilizado para autorizar operações futuras relacionadas a esse vendedor. Confira mais informações na seção Access token.

Para melhorar a sua experiência de integração, o PagBank disponibiliza opções que permitem simular o processo de autorização com o Connect via SMS.

Simule a autorização com Connect via SMS

Ao utilizar o ambiente Sandbox, você pode simular (mock) a autorização e receber respostas pré-definidas. Utilize essa opção para testar o comportamento do seu sistema frente a cenários específicos. Você pode utilizar essa opção para analisar a resposta do seu sistema frente a uma autorização com sucesso, por exemplo.

Simular autorização via SMS

Para que você consiga simular cenários com o endpoint Solicitar autorização via SMS, você utilizará e-mails disponibilizados pelo PagBank ao realizar a requisição:

Não existem limitações para o número de e-mails utilizados. Todos irão gerar uma responta padronizada conforme descrito na tabela acima.

Simular obtenção do access token

Para que você consiga simular cenários com o endpoint Obter access token, você deverá utilizar os seguintes sms_code ao realizar a requisição:

Access token

A partir do código de confirmação (code ou sms_code) obtido anteriormente, você irá obter o access_token. Assim, você será capaz de realizar requisições em nome do usuário. Para obter o access_token utilize o endpoint Obter access token.

Ao realizar a requisição ao endpoint, você deve definir qual foi a autenticação utilizada sms, authorization_codeou challenge. Como resposta, você receberá o access_token ao qual o usuário foi vinculado e também o refresh_token, utilizado para renovar as suas credenciais periodicamente. A validade do access_token também é informada na resposta.

Para renovar o access_token, você deve utilizar o endpoint Renovar access token. Nele, você irá fornecer o refresh_token e receberá na resposta:

• Um novo access_token que pode ser utilizado até a nova data de expiração.
• Um novo refresh_token que será utilizado na próxima renovação.