Migração para a API V5: O que mudou e como se preparar

Estamos evoluindo para oferecer a você a melhor experiência possível! A migração para a V5 não é apenas uma atualização—é um salto em inovação, segurança e eficiência. Com uma API mais robusta, funcionalidades aprimoradas e um ecossistema ainda mais inteligente, garantimos que seu negócio estará sempre à frente. Essa mudança foi pensada para elevar sua operação a um novo patamar, com mais estabilidade, desempenho e recursos que fazem a diferença no dia a dia.

Para tornar sua migração ainda mais simples e tranquila, criamos este artigo com informações essenciais sobre o processo. Nosso compromisso é garantir um suporte eficaz, acompanhando você em cada etapa e esclarecendo todas as dúvidas para que essa transição aconteça da melhor forma possível.

Sabemos que mudanças nem sempre são fáceis, especialmente quando sua operação já está adaptada às versões anteriores e à usabilidade da dashboard. Sair da zona de conforto pode parecer desafiador, mas queremos reforçar que essa transição trará melhorias significativas. Entendemos que a adaptação leva tempo, e estamos aqui para apoiá-lo em cada etapa. No entanto, também queremos inspirá-lo a enxergar essa mudança como uma oportunidade—uma evolução que tornará sua experiência mais eficiente, segura e alinhada às melhores práticas do mercado.

Tour pela Nova Dashboard 2.0: Explore as Novidades e Funcionalidades

O primeiro passo no processo de migração é garantir que você tenha acesso à Dashboard 2.0 e conheça todas as suas opções e funcionalidades. Atualmente, oferecemos diversas configurações e funcionalidades que são autosserviço, proporcionando mais autonomia no uso do nosso produto.

Além disso, queremos assegurar que você tenha uma base de conhecimento sólida sobre fluxos e funcionalidades, disponibilizando documentações e artigos detalhados para apoiar sua jornada. 

Acesso à Documentação e Central de Ajuda

Um passo fundamental para iniciar seu processo de migração é conhecer nossa documentação técnica e a Central de Ajuda. Esses materiais fornecem detalhes essenciais sobre nossas funcionalidades e fluxos, garantindo que você tenha todas as informações necessárias para uma transição tranquila. 

Ao acessar a Central de Ajuda, será possível ver conteúdos das duas versões. Para garantir que está consultando informações atualizadas, você deve selecionar a opção Pagar.me  2.0, conforme indicado no print abaixo:
 

Sugestões de Leitura

Para facilitar os primeiros passos na utilização da nova API, selecionamos alguns artigos essenciais que oferecem mais visibilidade e suporte ao processo de migração. São conteúdos que explicam sobre as opções mais básicas e ações que podem ser realizadas via dashboard e são mais voltadas ao transacional, como por exemplo, como realizar estorno de transação, cancelamento, entre outros. Acreditamos que essa leitura pode ajudar a impulsionar sua adaptação. Mas não se preocupe! Se, após a leitura, ainda restarem dúvidas, nossa equipe está à disposição para ajudá-lo por meio de nossos canais de atendimento.

Configurações
Configurações | Acesso à Dashboard
Configurações | Usuários
Configurações | Como consultar a Chave Secreta e a Chave Pública

Dashboard - Funcionalidades Gerais
Dashboard | Criando uma Conta de Teste
Dashboard | Qual a diferença entre cobrança e pedido?
Dashboard | Quais são os possíveis status do meu pedido?
Dashboard | Como Buscar Pedidos e Cobranças?

Transações e Pagamentos
Dashboard | Como identificar o motivo da falha em uma cobrança?
Dashboard | Como capturar uma cobrança?
Dashboard | Como estornar uma cobrança?

Recebedores e Transferências
Dashboard | Criação e Edição de Dados Cadastrais, de Transferências e Bancários de Recebedores
Dashboard | Configurar Conta Bancária e Transferência Automática

Relatórios e Extrato
Dashboard | Aba Extrato
Dashboard | Como exportar relatórios no Dashboard?
Dashboard | Aba Resumo

Dashboard 2.0, entenda cada uma das opções do menu

Se você busca informações detalhadas sobre o acesso à dashboard, opções de cadastro e todas as funcionalidades disponíveis, recomendamos a leitura do  manual da dashboard. Nele, você encontrará artigos aprofundados que explicam cada opção da dashboard 2.0.

Para facilitar esse processo, preparamos um resumo guiado que explora todas as opções do menu da dashboard, detalhando suas funcionalidades e especificidades.

Na dashboard, você encontrará dois ambientes: nível "merchant" e nível "account". No nível Merchant, você terá acesso às informações gerais do seu cadastro e às opções de configuração. Esse ambiente é exclusivo para usuários proprietários e administradores, que possuem permissão para gerenciar e ajustar configurações. O menu principal deste ambiente inclui:

No nível account, você terá acesso às principais informações transacionais e funcionalidades. Nesse ambiente, é possível gerar chaves transacionais, consultar transações, configurar a conta, gerenciar extratos e realizar outras operações.

Além dos usuários proprietários e administradores, outros perfis de acesso também poderão visualizar e interagir com essas informações, conforme suas permissões.

Abaixo, exploramos cada seção, iniciando pela opção "Resumo" e concluindo com a área de "Configurações" da sua loja.

1 - Resumo

Na opção "Resumo", você tem uma visão geral de todas as transações realizadas, com diversas opções de filtro, como: hoje, ontem, últimos 7 dias, últimos 15 dias, último mês, intervalo específico, entre outros.

Essa tela permite uma análise completa das suas vendas, incluindo lucro, status das transações e taxas de conversão, oferecendo um controle mais preciso e a possibilidade de acompanhar seu desempenho de perto.

2 - Pedidos e Cobranças

Ao acessar a dashboard, é comum surgir a dúvida sobre as diferenças entre pedidos e cobranças. De forma simplificada:

• Pedido: Funciona como uma "comanda" da transação, onde você pode visualizar detalhes e descrições dos produtos vinculados à venda.
• Cobrança: Representa a transação efetiva, ou seja, o pagamento realizado pelo comprador. Aqui, você encontra informações como valor, quantidade de parcelas e detalhes do fluxo de autorização.

Ambas as seções oferecem filtros para facilitar a navegação e a análise dos dados. Além disso, há a opção de exportar relatórios, tornando a conciliação financeira e a conferência das vendas mais práticas.

3 - Link de pagamentos

Com a opção de “Link de Pagamentos”, você tem acesso à nossa solução mais atualizada, projetada para ampliar ainda mais suas possibilidades de venda. Essa funcionalidade é ideal para quem deseja vender sem precisar de um site próprio.

Dentre as opções disponíveis, você pode:

• Gerar um link único para múltiplos clientes.
• Criar vendas recorrentes, garantindo maior previsibilidade e personalização para o seu negócio.

Nosso produto de recorrência foi desenvolvido para oferecer mais praticidade e eficiência, ajudando você a vender de forma simples e segura. Para mais informações, acesse a nossa documentação referência para esta funcionalidade. 

4 - Contestações

Na opção "Contestações", você pode gerenciar todas as etapas do processo de chargeback de forma eficiente. Com a possibilidade de realizar contestações tanto individuais quanto em lote, essa funcionalidade torna o processo mais ágil e prático, além de proporcionar maior visibilidade para o acompanhamento de cada etapa.

5 - Financeiro - Extrato, Transferências, Antecipações e Liquidações

As opções dentro da área Financeiro do menu são destinadas ao acompanhamento dos recebimentos. 

No extrato, você terá a possibilidade de configurar um período específico e exportar tabela com as informações de seus recebíveis. Essa opção da dashboard permite visualizar suas movimentações, incluindo transferências (internas e externas), antecipações realizadas e detalhes sobre as liquidações. 

Para mais informações sobre estas opções, você pode consultar esses artigos que vão ajudar no entendimento sobre os processos de saque e liquidações no Pagar.me.

6 - Recorrência 

Na opção "Recorrência", você encontrará três categorias: Planos, Assinaturas e Faturas. A partir delas, é possível acessar e gerenciar facilmente os detalhes de clientes específicos, contando com diversas opções de filtros.

Na versão 2.0, a lógica de recorrência passou por mudanças significativas em relação à versão 1.0. Agora, há mais flexibilidade na composição de ciclos, esquemas de precificação, além da possibilidade de aplicar descontos e outras melhorias.

Uma dúvida comum é sobre a criação de planos via dashboard. Atualmente, na versão 2.0, ainda não é possível criar planos manualmente pela interface. No entanto, essa ação pode ser realizada via API, utilizando a seguinte rota: Criar Plano. Para mais detalhes sobre esta funcionalidade, basta acessar este link da nossa documentação.

7 - Recebedores

Para você que atua com o modelo de negócio “Marketplace”, esta opção na dashboard permite a gestão de recebedores. Nesse modelo de negócio, você vai cadastrar recebedores para gerar um identificador e incluí-los nas regras da funcionalidade Split no processo de criação de transações. 

É possível realizar a criação desses recebedores tanto via dashboard, quanto via API. Além disso, via dashboard você conseguirá gerir tanto as informações desses recebedores, quanto os seus fluxos financeiros, como por exemplo, a opção de extrato - para consultar entradas, saídas, realizar transferências, entre outros. 

Para mais informações sobre esta funcionalidade, você pode acessar este link da documentação. Neste link, você também vai encontrar diversos artigos da nossa central ajuda sobre o assunto.

8 - Clientes

Essa opção na dashboard auxilia o lojista na gestão de customers, que podem ser criados de duas formas:

1. Criação automática através da criação de pedidos: Sempre que uma transação é realizada, os dados do comprador são armazenados, gerando um customer_id e um card_id, que podem ser reutilizados em futuras transações. Um ponto importante é que a chave forte do customer é o e-mail. Isso significa que, se um comprador já possuir um customer cadastrado, ele será atualizado automaticamente. Por exemplo, caso um novo cartão seja utilizado, um novo card será adicionado ao mesmo customer, mantendo a associação entre as informações.
2. Criação via API, quando o lojista opta por criar o customer e o cartão previamente, utilizando as seguintes rotas da API: Criar Cliente e Criar Cartão.

Há diversas possibilidades para integrar essas opções ao seu desenvolvimento. Por isso, tanto para esta, quanto para outras funcionalidades, é recomendável uma análise mais aprofundada junto ao seu time técnico para garantir a melhor adaptação ao seu fluxo. Caso você integre por plataforma, vale entender as opções de desenvolvimento da mesma relacionadas a essas funcionalidades.

Para mais detalhes, consulte nossa documentação neste link.

9 - Webhooks

Nesta seção, você pode gerenciar as notificações enviadas pela nossa API em diversas situações, como atualizações de status de pedidos, cobranças, recebíveis, entre outros. As informações de webhook ficam disponíveis na listagem para consulta durante um período de 30 dias a contar da data do envio da notificação.

Há diversas opções de filtro para consultas de cenários específicos com a possibilidade de reenviar a notificação em casos de falha. Na opção de configurações, há uma lista de eventos que podem ser configurados para que você receba essas notificações conforme sua necessidade.

Se você possui um desenvolvimento próprio, será necessário adaptar sua aplicação para processar as requisições de atualização de status. Nesse caso, a configuração deve ser manual, na opção configurações > Webhooks. Caso utilize uma plataforma integrada, é importante verificar suas particularidades técnicas. Já para integrações via HUB, essa configuração é realizada durante a instalação do plugin. Neste link, será possível consultar mais informações sobre a funcionalidade e opções de configuração. Além disso, nesta seção em nossa central de ajuda, temos artigos que também tem o intuito de aprofundar sobre a funcionalidade. Vale a pena conferir!

10 - Equipe

Na versão 2.0, você conta com mais opções para definir o escopo de acesso dos usuários, garantindo um controle mais refinado. Esse modelo oferece maior segurança no compartilhamento de informações sensíveis, permitindo a configuração de permissões específicas para cada nível de usuário. 

Neste artigo, você vai encontrar as explicações detalhadas sobre cada uma das permissões, o escopo de cada uma, além do passo a passo para enviar convites, configurar e reconfigurar as permissões.

11 - Configurações

Nesta seção você vai conseguir realizar diversas configurações em sua loja: Há a opção conta, para consultar informações cadastrais, realizar a configuração de domínios e IP’s, personalizar o checkout e configurações da Wallet de clientes. Nos artigos abaixo, você vai encontrar o passo a passo detalhado para cada uma dessas opções.

• Checkout | Saiba mais sobre essa funcionalidade
• Allowlist de IPs | Saiba mais sobre essa funcionalidade
• Carteira de clientes | Conheça essa funcionalidade

Na seção “Chaves”, você pode gerenciar as chaves transacionais, utilizadas para processar transações e consumir nossa API. 

Temos um compromisso contínuo com a segurança transacional, implementando constantemente melhorias para reforçar a proteção dos nossos clientes. Por isso, nesta opção, você conta com recursos como a limitação de uso das chaves, permitindo a definição de perfis de acesso e a criação de múltiplas chaves. Após a criação, a chave poderá ser consultada apenas uma vez. Caso precise de mais informações, acesse este link da nossa Central de Ajuda.

Comparativo de funcionalidades (De/Para)

1. Criação de transações

2. Gerenciamento de clientes

3. Recorrência e Assinaturas

Clientes que utilizam Recorrência na versão 1.0

Para clientes que ainda utilizam o serviço de recorrência na versão 1.0, informamos que, no momento, não há ainda um processo automatizado para a migração de assinaturas. No entanto, nosso time de tecnologia está estudando essa possibilidade para futuras implementações.

Atualmente, é possível realizar a migração de cartões, um processo que transfere os dados de customers e cards atrelados às assinaturas da antiga versão para a versão 2.0. Ao concluir essa migração desses dados, você receberá um arquivo De/Para, contendo os novos ID’s de customer, que deverão ser utilizados para a recriação das assinaturas na nova versão. Caso precise de suporte para realizar essa solicitação, basta entrar em contato conosco por meio dos nossos canais de atendimento.

Para recriá-las, você deve utilizar esta rota e considerar os novos parâmetros e especificações da funcionalidade de recorrência na V5. Na requisição, ao invés de preencher todos os dados de customer e card, você poderá utilizar o customer_id e o card_id, sem a necessidade de enviar novamente o CVV nesse processo.

Vale destacar que a gestão desse processo fica a cargo do próprio lojista, que define os critérios mais adequados para a transição.

Os artigos da nossa central de ajuda também podem ser úteis para que o cliente entenda de uma forma mais simplificada esta funcionalidade.

• Assinatura | O que é uma fatura?
• Assinatura | O que é uma assinatura?
• Assinatura | O que é um plano?
• Assinatura | O que é uma venda recorrente?
   

4. Notificações (Postbacks e Webhooks)

5. Marketplace

Como migrar para a API V5?

Para iniciar o processo de migração, o primeiro passo é identificar o tipo de integração que você utiliza. As possibilidades são as seguintes:

• Integração via desenvolvimento próprio: Nesse caso, será necessário seguir nossa documentação para adaptar sua integração aos novos parâmetros e criar as chaves transacionais para conseguir realizar chamadas para nossa API.
• Integração via plataforma parceira (HUB): Se sua integração estiver vinculada a uma plataforma específica que tenha opção dentro do HUB, você pode verificar nesta lista o passo a passo específico para o seu caso. Lembrando que para este tipo de integração não há a necessidade de criar a chave transacional (Secret key) visto que a integração é automática.
• Outras opções.

Caso precise de mais informações ou suporte durante na identificação do tipo de migração e sobre os próximos passos, o nosso time de está disponível pelos seguintes canais de atendimento:

• Telefone: 4004-1330
• E-mail: relacionamento@pagar.me
• Chat: disponível dentro do portal

Iremos ajudá-lo nos primeiros passos para garantir o seu acesso a nova dashboard e principais explicações sobre funcionalidades para que você consiga seguir com as ações do seu lado. 

Abaixo vamos explicar um pouco mais sobre cada etapa do processo:

Primeiros Passos na Dashboard

Ao acessar a dashboard, primeiramente é necessário validar a necessidade de criação das chaves transacionais. Caso você seja desenvolvimento próprio ou esteja integrado a alguma plataforma que precise das chaves para integrar direto em seu sistema. Você deve seguir este passo a passo. Na V5 o formato das chaves são diferentes da versão anterior, tratam-se da secret_key e da public_key.

Após a etapa de verificação das chaves, recomendamos que você faça um tour pelas principais funcionalidades, explorando as seguintes opções:

• Como acessar e criar chaves de integração
• Como navegar pelo ambiente de testes
• Quais testes são mais relevantes nesta fase inicial
• Como consultar transações
• Como consultar o extrato

Isso te ajudará a se familiarizar com a API V5 e garantir uma integração mais fluida.

Configuração da company para V4

Clientes que transacionavam na versão 1.0 podiam configurar a API entre V1 e V4. No entanto, para a migração para a V5, é essencial que a configuração anterior esteja na V4, garantindo a comunicação correta entre as APIs e evitando falhas operacionais.

Por isso, ao acessar a Dashboard 2.0, ajuste a versão da API para V4 na PILOT. Caso essa configuração não seja realizada, não será possível transacionar na nova versão. Além disso, assim que você concluir a sua migração, exclua as chaves antigas na versão 1.0 e mantenha somente as chaves da V5 realizando chamadas para nossa API.

Para realizar essa configuração na PILOT, siga este passo a passo: Configurações > Dados da API

Testes Iniciais e Simulações em ambiente de testes

Caso você queira realizar testes de transações utilizando os os exemplos de requisições da nossa documentação V5, é possível utilizar a ferramenta Postman, enviando as requisições no formato JSON. Para facilitar o entendimento, preparamos um passo a passo resumido que pode lhe auxiliar durante esse processo.

As simulações devem ser restritas ao ambiente de testes. Caso realize testes em produção a sua conversão poderá ser impactada.

Passo a passo:

1. Baixar e Instalar o Postman
   1. Acessar o site oficial do Postman e realizar o download da versão compatível com o sistema operacional. Instalar e abrir o aplicativo.
2. Criar uma Nova Requisição
   1. No Postman, clicar em "New Request" (Nova Requisição).
   2. Escolher o método adequado para a ação que deseja testar. As opções são as seguintes:
      1. POST → Criar um novo recurso (exemplo: criar uma transação).
      2. GET → Consultar informações (exemplo: buscar um pagamento).
      3. PUT → Atualizar um recurso existente.
      4. DELETE → Remover um recurso.
3. Configurar a URL da API do Pagar.me

No campo de URL, insira o endpoint da API do Pagar.me  de acordo com o teste que deseja realizar. Exemplo para criar uma transação: https://api.pagar.me/core/v5/orders

4. Inserir a Secret Key (Autenticação)
   1. Vá até a aba "Authorization".
   2. No campo "Auth  Type", selecione "Basic Auth".
   3. No campo "Username", insira sua Secret Key (chave de integração), que pode ser encontrada na dashboard do Pagar.me  na opção configuração > Chaves.
5. Definir o Corpo da Requisição
   1. Acesse a aba "Body" e selecione a opção "raw".
   2. No campo de formato, escolha "JSON".
   3. Insira um payload/requisição de teste (dados que serão enviados na requisição).
6. Enviar a Requisição e Analisar o Resultado
   1. Clique no botão "Send" para enviar a requisição.
   2. No painel inferior do Postman, será exibida a resposta da API:
      1. 200 OK → Teste bem-sucedido.
      2. 400 ou 401 → Erro na requisição (verifique os dados enviados).

Recomendamos iniciar com os testes dos seguintes cenários:

• Transação capturada
• Transação com falha
• Transação pendente de captura
• Transação de Boleto Paga
• Transação de Pix

Os testes são realizados a partir do nosso simulador, disponível apenas no ambiente de testes. Neste ambiente, é possível testar diversos cenários utilizando identificadores-chave para simular diferentes meios de pagamento e status de transação.

Neste link, você encontra todos os cenários disponíveis para testes e pode realizá-los quantas vezes forem necessárias.

No ambiente de testes, há duas opções de configuração para os meios de pagamento: Simulador e PSP. No entanto, alguns cenários podem não estar disponíveis dependendo da configuração escolhida, devido a limitações do nosso sistema de simulação.

Se encontrar dificuldades durante os testes, tente alterar a configuração do meio de pagamento acessando Configuração > Meios de Pagamento e alternando entre as opções disponíveis antes de realizar novas tentativas.

Após concluir os testes, se sua integração for por desenvolvimento próprio, basta configurar as chaves transacionais do ambiente de produção em seu sistema para começar a realizar transações e utilizar todas as funcionalidades da nova API V5.

Caso sua integração seja por meio de uma plataforma, siga as orientações da documentação correspondente e realize as configurações conforme as especificidades da plataforma utilizada. Caso a sua plataforma não esteja nessa lista, você deve entrar em contato direto para configuração das chaves transacionais.

Se encontrar qualquer dificuldade ou precisar de suporte durante esse processo, nossa equipe de relacionamento está à disposição para auxiliá-lo. Reforçamos nosso compromisso em oferecer todo o suporte necessário durante a migração, garantindo que a transição ocorra de forma tranquila e eficiente.

Checklist final

Antes de iniciar operações em produção, recomendamos validar os seguintes pontos:

• As credenciais do ambiente de produção estão configuradas corretamente.
• As transações de teste foram bem-sucedidas.
• Os endpoints da API estão respondendo conforme esperado.
• Todas as funcionalidades críticas do seu sistema foram verificadas.

Monitoramento inicial

Nas primeiras transações em produção, sugerimos acompanhar os logs e métricas do seu sistema para identificar qualquer comportamento inesperado. Ferramentas de monitoramento podem ser úteis para esse acompanhamento.

Acesso a recursos de suporte

Se precisar de mais informações, você pode consultar:

• Nossa documentação oficial, onde encontrará detalhes sobre os endpoints e parâmetros.
• Nossa central de ajuda com explicações detalhadas sobre fluxos e funcionalidades.
• Nosso time de relacionamento, que está pronto para ajudar com qualquer necessidade.

Acompanhamento contínuo e melhorias

A migração para a nova API traz muitos benefícios para sua operação. Estamos constantemente aprimorando nossa solução e contamos com o seu feedback para continuar evoluindo. 

Sabemos que esse processo é sensível e estamos atentos a todos os detalhes para tornar sua experiência cada vez melhor.

Conte sempre conosco.