Primeiros passos

Nesta página, você encontrará informações essenciais para iniciar a utilização dos recursos disponibilizados pelas APIs do PagBank. Aqui, você encontrará definições e uma lista dos ambientes disponíveis, bem como explicações sobre tokens de autenticação e chaves públicas.

Além disso, você encontra um guia sobre como criar a sua conta e fazer a migração para o ambiente de Produção, garantindo que você esteja preparado para lidar com dados reais e aproveitar ao máximo os recursos oferecidos.

Navegue pelos tópicos a seguir para obter todas as informações necessárias para começar a utilizar as APIs do PagBank com confiança e eficiência.

Ambientes disponíveis

Você pode interagir com as APIs do PagBank por meio de dois ambientes: Sandbox e Produção.

📘

URL de cada ambiente

Cada ambiente disponibiliza duas URLs base. A seleção da URL a ser utilizada depende de qual API você irá utilizar.

Sandbox

O ambiente Sandbox é um ambiente de desenvolvimento controlado, projetado para que você realize testes durante a integração das funcionalidades disponibilizadas pelas APIs do PagBank. Ao executar testes no ambiente Sandbox, você pode ter a tranquilidade de que os dados e a contabilidade real não serão afetados, uma vez que os dados utilizados são fictícios, exclusivos para o modo de teste.

A URL base utilizada para acessar as APIS disponibilizadas pelo PagBank no ambiente Sandbox é apresentada a seguir:

https://sandbox.api.pagseguro.com/

Caso você esteja utilizando as APIs de Transferência e Pix Bacen, você utilizará uma URL diferente da mostrada acima. Para as APIs de Transferência e Pix Bacen você utilizará a seguinte URL base no ambiente Sandbox:

https://secure.sandbox.api.pagseguro.com

Produção

O ambiente de Produção é o ambiente principal, onde ocorrem eventos reais que afetam contas, pagamentos e transferências reais. Este ambiente é utilizado após a conclusão dos testes de integração e o seu serviço está pronto interagir com usuários reais. É importante ter em mente que, ao trabalhar no ambiente de Produção, todas as ações e transações terão efeitos reais nos dados e no sistema.

Certifique-se de migrar do ambiente Sandbox para o ambiente de Produção apenas quando estiver totalmente preparado para lidar com dados reais e impactar contas, pagamentos e transferências de forma legítima.

A URL base utilizada para acessar as APIS disponibilizadas pelo PagBank no ambiente de Produção é apresentada a seguir:

https://api.pagseguro.com

Caso você esteja utilizando as APIs de Transferência e Pix Bacen, você utilizará uma URL diferente da mostrada acima. Para as APIs de Transferência e Pix Bacen você utilizará a seguinte URL base no ambiente de Produção:

https://secure.api.pagseguro.com

Token de autenticação

Os tokens de autenticação oferecem uma maneira segura e eficiente de garantir a identidade do usuário ou aplicação ao acessar sistemas ou APIs, sem a necessidade de enviar credenciais sensíveis em cada solicitação. Eles ajudam a proteger as informações confidenciais e garantir que apenas usuários autorizados possam acessar os recursos adequados.

Token de autenticação ambiente Sandbox

  1. Acesse a sua conta de Sandbox.
  2. Localize o menu Perfis de Integração.
  3. Clique em Vendedor. O token de autenticação para o ambiente Sandbox estará disponível na seção Credenciais

Token de autenticação ambiente de Produção

  1. Acesse a sua conta PagBank;
  2. No menu lateral, selecione Venda online;
  3. Selecione a opção Integrações;
  4. Clique em Gerar Token.

📘

Token de autenticação para o ambiente de Produção

Obter o token de autenticação para o ambiente de Produção não habilita o uso de todas as funcionalidades disponibilizadas pelas APIs do PagBank. Algumas APIs requerem, além do token de autenticação, dados como client_id e client_secret, obtidos através da API Connect.

Criar conta e fluxo de utilização

O PagBank oferece a possibilidade de criação de contas apenas no ambiente Sandbox e não diretamente no ambiente de Produção. Todas as novas contas são alocadas no ambiente Sandbox para permitir testes e desenvolvimento. Para obter uma conta no ambiente de Produção, é necessário passar pelo processo de homologação da sua conta Sandbox. A seguir, você encontrará descrições detalhadas sobre como criar contas, realizar a homologação e obter os dados de acesso necessários.

SandBox

Os passos 2 e 3 do processo apresentado a seguir são exclusivos para a utilização das APIs de Transferência e Pix Bacen. Para as demais APIs os passos 2 e 3 podem ser desconsiderados.

  1. Para criar uma conta para o ambiente Sandbox utilize o portal de criação de contas do PagBank.
  2. Realize o processo do Connect challenge para obter um token de acesso para gerar seu certificado digital.
  3. Gere um Certificado Digital mTLS.

📘

Validade do certificado digital

Certificados digitais por padrão tem validade de 2 anos. No entanto, dependendo do integrador, esse período de validade pode variar.

Após a expiração do certificado digital, você deverar gerar um novo certificado.

Caso você gere um novo certificado digital antes da expiração da validade do certificado antigo, o certificado antigo será invalidado imediatamente.

  1. Crie uma aplicação utilizando a API Connect. Ao criar uma aplicação você irá obter os parâmetros de identificação da sua aplicação, client_id e account_id. Com essas informações você poderá pedir autorização aos seus usuários para executar ações em seu nome.
  2. Teste as APIs disponibilizadas pelo PagBank no ambiente Sandbox. Nessa etapa você deve se certificar que todos os processos estão ocorrendo conforme esperado. Depois, você pode passar para a etapa de homologação para obter a sua conta para o ambiente de Produção.

Produção

A utilização do ambiente de Produção depende da aprovação do processo de homologação. Depois da homologação, você deverá repetir parte dos passos realizados no ambiente sandbox para obter credenciais para o uso das APIs no ambiente de produção. Os passos para a utilização do ambiente de Produção são listados a seguir. Como para o ambiente Sandbox, os passos 2 e 3 do processo apresentado a seguir são exclusivos para a utilização das APIs de Transferência e Pix Bacen. Para as demais APIs os passos 2 e 3 podem ser desconsiderados.

  1. Solicite a homologação da sua conta. Para isso, acesse a página de homologação. Durante o processo de homologação, o time PagBank irá validar os logs relacionado a sua conexão e uso das APIs do PagBank. Se você for aprovado, terá sua conta liberada para o ambiente de Produção.
  2. Realize o processo do Connect challenge para obter um token de acesso para gerar seu certificado digital.
  3. Gere um Certificado Digital mTLS.
  4. Crie uma aplicação utilizando a API Connect. Ao criar uma aplicação você irá obter os parâmetros de identificação da sua aplicação, client_id e account_id. Com essas informações você poderá pedir autorização aos seus usuários para executar ações em seu nome.
  5. Utilize as APIs disponibilizadas pelo PagBank no ambiente de Produção. Para maiores informações sobre os funcionalidades acesse Funcionalidades disponíveis.

Chaves públicas

Nas APIs do PagBank, as chaves públicas são utilizadas para acessar o checkout transparente do PagBank. Se você optar por soluções como criptografia de cartões e autenticação 3D Secure (3DS), precisará de uma chave pública. Ao criar uma chave pública por meio da API do PagBank, o PagBank armazenará a chave privada correspondente. Dessa forma, quando você enviar uma mensagem criptografada com a chave pública, somente o PagBank poderá identificar o conteúdo. Para mais detalhes acesse Chaves públicas.

Chaves de idempotência

As chaves de idempotência são identificadores únicos usados para garantir a idempotência em solicitações aos endpoints de uma API. Em um serviço RESTful como do PagBank, ao fazer várias solicitações usando a mesma chave de idempotência, você sempre receberá a mesma resposta. Isso é útil em situações em que uma solicitação falha devido a um problema de comunicação e não há uma resposta conclusiva, como ao criar um pagamento. Ao reenviar a solicitação com a mesma chave de idempotência, é possível garantir que a segunda chamada não falhe. A chave de idempotência é enviada como um cabeçalho na solicitação e é usada para identificar uma transação específica.