API Pix Automático da PagBrasil: Guia de Integração para desenvolvedores

É nesse contexto que a solução de Pix Automático da PagBrasil se destaca. Entendemos a criticidade da segurança e da flexibilidade para operações de recorrência. Por isso, nossa plataforma foi construída sobre pilares sólidos:

• Segurança robusta: a comunicação com nossa API é protegida por HTTPS, e cada transação é validada por mecanismos de autenticação. Além disso, a PagBrasil emprega medidas contra abuso ou uso indevido da API, podendo aplicar limitação de taxa ou medidas restritivas similares para garantir a integridade do sistema.
• Jornadas de consentimento adaptáveis: a PagBrasil oferece duas opções de jornada para o Pix Automático:
  • Pagamento inicial + consentimento: o usuário realiza um pagamento inicial e, simultaneamente, concede autorização para futuras cobranças recorrentes automáticas. Essa jornada está detalhada na seção 4 da documentação de integração.
  • Apenas consentimento: o usuário apenas concede a autorização para cobranças futuras, sem a necessidade de um pagamento imediato. Este modelo é perfeito para cenários como períodos de avaliação gratuita (trials) de serviços e seu fluxo de integração está especificado na seção 6 da documentação.
• Controle e customização: a integração via API proporciona um nível de personalização que permite aos desenvolvedores moldar a experiência de pagamento de acordo com as especificidades do seu negócio.

Compreender como integrar essa ferramenta poderosa é fundamental para desenvolvedores que buscam implementar ou aprimorar sistemas de cobrança recorrente. A API da PagBrasil oferece os recursos necessários para construir uma experiência de pagamento fluida e segura, aproveitando ao máximo o potencial do Pix Automático.

Por que integrar o Pix Automático via API? Benefícios para o desenvolvedor

A integração via API frequentemente não é apenas mais uma opção, mas sim o caminho mais eficaz e, em muitos casos, o único viável para incorporar plenamente essa avançada funcionalidade de pagamentos recorrentes. Essa necessidade surge, por exemplo, quando não há uma solução “plug and play” diretamente compatível com a plataforma ou aplicação específica do lojista, ou quando as limitações inerentes a esses sistemas exigem uma abordagem mais granular e customizada.

Nessas situações, a API é a chave para desbloquear todo o potencial de uma solução, colocando o poder e a flexibilidade nas mãos da equipe de desenvolvimento. Isso permite um alinhamento preciso entre a solução de pagamento e as regras de negócio da aplicação, garantindo uma implementação sob medida. Vejamos os principais benefícios que essa abordagem proporciona:

Controle total sobre a Experiência do Usuário (UX)

Ao integrar via API, você assegura que o cliente permaneça integralmente no seu ambiente durante todo o processo de checkout e consentimento para a recorrência. Essa abordagem é fundamental para evitar redirecionamentos desnecessários, que frequentemente podem causar desconfiança ou levar ao abandono da transação por parte do usuário.

Adicionalmente, você detém total liberdade para desenhar a interface de pagamento, garantindo que ela seja visualmente consistente com a identidade da sua marca e otimizada para a usabilidade do seu sistema. No fluxo de integração, a loja online envia as informações do pedido diretamente para a PagBrasil e, em resposta, recebe os dados necessários para exibir o QR Code Pix e o código alternativo diretamente na sua página para o cliente.

Flexibilidade para customizar o fluxo de checkout

A API permite que você adapte o processo de solicitação de pagamento e consentimento às particularidades e exigências do seu produto ou serviço. Isso significa que é possível decidir, por exemplo, o momento exato em que as opções de recorrência são apresentadas ao usuário ou definir de que forma os dados necessários para a transação e a configuração da assinatura serão coletados.

Integrando via API você terá a capacidade de enviar uma vasta gama de parâmetros para configurar a transação e a recorrência. Isso inclui detalhes do produto, informações completas do cliente (como nome, CPF/CNPJ, e-mail, telefone e endereço completo), o valor da transação, além de parâmetros específicos para a configuração do Pix Automático, como o ciclo da recorrência, a data da primeira cobrança futura e a descrição que identificará a assinatura no aplicativo bancário do cliente.

Integração direta com a sua lógica de negócio:

Com a integração via API, você pode incorporar a gestão de pagamentos recorrentes de forma transparente e direta aos seus sistemas internos. Isso é particularmente vantajoso para empresas que utilizam plataformas de Gerenciamento de Relacionamento com o Cliente (CRM), sistemas de Planejamento de Recursos Empresariais (ERP) ou outras soluções de software proprietárias, permitindo uma visão unificada das operações.

Essa capacidade de integração profunda também viabiliza a automação de processos críticos. Por exemplo, é possível automatizar a criação de pedidos e a solicitação de consentimento para o Pix Automático com base em eventos que ocorrem no seu sistema, como a inscrição de um novo cliente em um plano de assinatura ou o acionamento da renovação de um serviço existente.

Automação de processos de pagamento e notificação

A API promove uma extensiva automação dos processos de pagamento e das notificações relacionadas. Através de notificações instantâneas, conhecidas como webhooks, seu sistema é informado em tempo real sobre o status dos pagamentos e consentimentos.

Essa comunicação imediata permite que sua aplicação reaja automaticamente a esses eventos. Por exemplo, é possível liberar o acesso a produtos ou serviços assim que um pagamento é confirmado, atualizar o status de uma assinatura no seu banco de dados ou enviar comunicações relevantes e contextuais ao cliente. A PagBrasil encarrega-se de notificar o lojista quando um pagamento ou consentimento é autorizado, o que pode disparar o processo de fulfillment do pedido. Adicionalmente, é possível programar e automatizar a execução de cobranças recorrentes futuras, utilizando o identificador da recorrência que é obtido e retornado no momento em que o cliente concede o consentimento inicial.

Ao optar pela integração via API do Pix Automático da PagBrasil, você não está apenas adicionando um método de pagamento ao seu sistema; está implementando uma solução completa e adaptável, capaz de otimizar processos, melhorar a experiência do cliente e impulsionar a eficiência operacional do seu negócio de recorrência. É a solução definitiva para desenvolvedores que buscam robustez, controle e capacidade de personalização em cenários que exigem uma integração direta e profunda.

Entendendo as jornadas de integração

Um dos grandes diferenciais da solução de Pix Automático da PagBrasil é a sua flexibilidade para se adaptar a diferentes modelos de negócio e estratégias de aquisição de clientes. Isso se reflete nas duas jornadas de integração suportadas pela API, que permitem tanto a cobrança de um valor inicial no momento do consentimento quanto a simples obtenção da autorização para cobranças futuras.

Compreender essas duas abordagens é crucial para que o desenvolvedor escolha o fluxo mais adequado para cada caso de uso específico, garantindo uma experiência otimizada para o usuário final e alinhada aos objetivos da empresa.

Jornada 1: Pagamento inicial + Consentimento para recorrência

Nesta modalidade, o cliente realiza um pagamento Pix no momento em que concede a autorização para futuras cobranças recorrentes automáticas. É a jornada mais comum para o início de assinaturas pagas, onde o primeiro ciclo já é cobrado no ato da contratação.

Fluxo técnico (resumido):

1. Sua aplicação envia uma requisição para o endpoint de adição de ordem da PagBrasil, contendo os dados do pedido, do cliente e os parâmetros específicos da recorrência.
2. A PagBrasil retorna o link com a imagem do QR Code Pix, o “copia e cola”.
3. Após o cliente efetuar o pagamento e o consentimento, a PagBrasil notifica sua aplicação sobre a autorização.

Caso de uso ideal:

• Início de assinaturas de software (SaaS) onde o primeiro mês/período é pago no momento da adesão.
• Clubes de assinatura que cobram a primeira mensalidade para envio do primeiro produto.
• Serviços que requerem um pagamento inicial para ativação e subsequentes cobranças recorrentes.

O fluxo detalhado para esta jornada, incluindo todos os parâmetros de requisição e os detalhes da resposta, encontra-se na Seção 4 da documentação de integração do Pix Automático.

Jornada 2: apenas Consentimento para Recorrência (sem pagamento inicial)

Esta jornada permite que o cliente autorize as futuras cobranças recorrentes via Pix sem a necessidade de realizar um pagamento imediato. É uma estratégia excelente para oferecer períodos de avaliação gratuita (trials) de um serviço, por exemplo.

Fluxo técnico (resumido):

1. Sua aplicação envia uma requisição POST para o endpoint de criação de consentimento da PagBrasil, com os dados do cliente e os parâmetros da recorrência;
2. A PagBrasil retorna as informações necessárias para que o cliente autorize a recorrência em seu aplicativo bancário;
3. Após o consentimento do cliente, a PagBrasil notifica sua aplicação sobre a autorização da recorrência.

Caso de uso ideal:

• Oferecimento de períodos de trial para serviços online, onde o cliente cadastra o meio de pagamento e o consentimento, mas a primeira cobrança só ocorrerá após o término do período gratuito.
• Modelos “freemium” que, para liberar funcionalidades premium futuras de forma automática, solicitam o consentimento antecipado.
• Situações em que o início da cobrança está desvinculado do momento do cadastro, como em matrículas com início de pagamento posterior.

Os detalhes completos sobre como implementar esta jornada, incluindo os parâmetros específicos para a solicitação de consentimento, estão especificados na Seção 6 da documentação de integração do Pix Automático.

A escolha entre essas jornadas dependerá intrinsecamente da estratégia de negócio da sua aplicação. A API da PagBrasil está preparada para oferecer a flexibilidade necessária para ambos os cenários, assegurando que você possa implementar a melhor experiência de integração de pagamentos recorrentes com Pix Automático.

Lidando com as respostas: QR Code, Webhooks e Status

Após enviar uma requisição à API da PagBrasil, sua aplicação precisa estar preparada para processar a resposta síncrona e, fundamentalmente, para lidar com as notificações assíncronas (webhooks) que informarão sobre o progresso da transação ou do consentimento. Além disso, a API oferece endpoints para consulta de status sob demanda.

Resposta Inicial da API (Síncrona)

A resposta imediata da API varia conforme o endpoint utilizado:

Pagamento Inicial + Consentimento:

• A API retornará uma resposta contendo os detalhes do pedido.
• Os elementos cruciais nesta resposta são pix_image (a URL da imagem do QR Code Pix) e pix_code (o código alternativo “copia e cola” para usuários de dispositivos móveis que não podem escanear o QR Code).
• Sua aplicação deve exibir o QR Code e/ou o código para que o cliente possa efetuar o pagamento e conceder o consentimento através do aplicativo de seu banco. O formato da resposta é o mesmo de uma consulta via API.

Apenas Consentimento:

• A resposta também será com os detalhes da recorrência, mesmo formato de uma consulta via.
• Neste caso, como não há pagamento inicial, a resposta focará nos dados da recorrência que está aguardando o consentimento do cliente. O pix_rec_id, identificador da recorrência, será crucial e geralmente comunicado via webhook após a confirmação do consentimento.

Webhooks: a espinha dorsal da comunicação assíncrona

Os webhooks são essenciais para manter seu sistema atualizado em tempo real sobre as mudanças de status de um pagamento ou consentimento. Em vez de sua aplicação consultar repetidamente a API da PagBrasil (polling), a PagBrasil envia ativamente uma notificação para uma URL que você especifica em seu PagBrasil Dashboard.

Os Webhooks permitem que sua aplicação reaja imediatamente a eventos como:

• Pagamento autorizado (para liberar produtos/serviços).
• Consentimento de recorrência autorizado (para ativar uma assinatura).
• Falha no pagamento ou rejeição do consentimento.

Segurança e Autenticidade dos Webhooks: é vital garantir que os webhooks recebidos são genuinamente da PagBrasil e não foram adulterados.

Confirmação de Recebimento (Acknowledgement): após receber o webhook, seu servidor deve responder ao envio da PagBrasil confirmando o recebimento bem-sucedido (ex: “Received successfully [timestamp]”). Falhas na confirmação podem levar a notificações de erro e reenvios por parte da PagBrasil.

Consultando o status de pedidos e recorrências via API

Embora os webhooks sejam o método preferencial para atualizações de status, a API da PagBrasil também oferece endpoints para que sua aplicação consulte ativamente o status de um pedido ou de uma recorrência específica. Isso pode ser útil para reconciliações ou em cenários de contingência.

A correta implementação do tratamento das respostas síncronas, a escuta e validação dos webhooks, e a capacidade de consultar status sob demanda, formam um tripé robusto para uma integração resiliente e confiável com o Pix Automático da PagBrasil.

Casos de uso: exemplos práticos de aplicação

A flexibilidade do Pix Automático da PagBrasil o torna ideal para uma vasta gama de cenários de cobrança recorrente:

• E-commerce com Assinaturas e Clubes de Assinatura: este modelo de negócio, que inclui desde lojas virtuais oferecendo caixas de assinatura (com produtos de beleza, alimentos, livros, etc.) até serviços de reposição programada de produtos (como café, vitaminas, ração para pets) e clubes diversos (vinhos, cervejas artesanais, itens colecionáveis), encontra no Pix Automático uma forma eficiente de gerenciar os pagamentos periódicos.
  Geralmente, a jornada de “Pagamento Inicial + Consentimento” é a mais indicada, pois o cliente realiza o pagamento da primeira mensalidade/caixa no ato da contratação, já autorizando as cobranças futuras.
• SaaS (Software as a Service), Serviços de Streaming e Conteúdo Digital: empresas que fornecem acesso a software, plataformas online, ou conteúdo digital (como vídeos, músicas, cursos, publicações) mediante um modelo de assinatura, podem simplificar e modernizar significativamente suas cobranças com o Pix Automático.
  A escolha da jornada ideal dependerá da estratégia de aquisição de clientes. Para um acesso imediato pago, a jornada de “Pagamento Inicial + Consentimento” é a mais apropriada, cobrando o primeiro período no momento da adesão. Caso a empresa ofereça um período de avaliação gratuita (trial), a jornada de “Apenas Consentimento” é perfeitamente adequada. O cliente autoriza as cobranças futuras via Pix sem um desembolso inicial, e o primeiro pagamento é efetuado automaticamente após o término do trial.
• Doações Recorrentes: Organizações Não Governamentais (ONGs) e outras instituições que dependem de contribuições financeiras periódicas podem facilitar o processo para seus doadores utilizando o Pix Automático. Isso permite a configuração de doações automáticas, garantindo um fluxo de receita mais estável para a organização. A jornada de “Pagamento Inicial + Consentimento” é a mais adequada, onde o doador realiza a primeira contribuição e já autoriza as futuras.

Boas práticas de desenvolvimento e implementação

Uma integração robusta vai além do código funcional; ela envolve boas práticas que garantem segurança, estabilidade e uma boa experiência para o usuário final.

Tratamento consistente de erros:

Uma prática fundamental é a validação exaustiva de todos os dados do cliente diretamente na sua aplicação, antes mesmo de enviá-los à API da PagBrasil. Isso minimiza a ocorrência de erros básicos e rejeições desnecessárias, especialmente para campos como CPF/CNPJ e a sigla do estado, que possuem formatos específicos e exigem validação para prevenir o envio de valores inválidos.

Adicionalmente, seu sistema deve estar preparado para tratar adequadamente as mensagens de erro retornadas pela API, como a comum “Duplicated order.”, que pode ocorrer, por exemplo, ao tentar submeter um pedido com o mesmo número e customer_taxid de um pedido já pago, ou ao tentar reenviar um pedido já pago, ou ainda ao submeter dois pedidos com o mesmo número para customer_taxid diferentes.

Recomenda-se fortemente a implementação de um sistema de logging detalhado para todas as requisições e respostas da API, pois isso será um recurso inestimável para processos de depuração e auditoria. Complementarmente, a criação de mecanismos de alerta para falhas críticas na integração permitirá uma resposta rápida e eficaz da sua equipe técnica.

Gerenciamento de webhooks:

Como discutido anteriormente, seu servidor deve estar preparado para a lógica de reenvio de webhooks da PagBrasil. Se o seu servidor não confirmar o recebimento de um webhook ou se houver falha na conexão, a PagBrasil tentará reenviar a notificação. É crucial que seu sistema possa lidar com múltiplas notificações para o mesmo evento (verificando se já processou aquele status) e que responda corretamente para evitar loops de reenvio.

Segurança das credenciais e comunicações

A segurança das suas credenciais de API é primordial. Sua Secret Phrase e seu pbtoken devem ser armazenados de forma extremamente segura em seu ambiente de servidor, nunca devendo ser expostos no lado do cliente (client-side) ou versionados em repositórios de código acessíveis publicamente.

Além disso, um pilar da segurança da integração é a validação constante da signature (assinatura HMAC-MD5). Essa assinatura deve ser verificada em todas as respostas XML recebidas da API (como nas consultas de pedido ou recorrência) e, de maneira fundamental, em todos os Webhooks (IPNs) que sua aplicação receber.

Essa validação, que utiliza sua “Secret Phrase” como chave, garante tanto a autenticidade da origem da comunicação quanto a integridade dos dados transmitidos.

Experiência do Usuário (UX)

Durante todo o processo de pagamento e consentimento, é essencial manter o usuário claramente informado sobre o que está acontecendo. Após a leitura do QR Code e a confirmação no aplicativo bancário, por exemplo, forneça um feedback visual imediato e compreensível sobre o status da operação em sua interface.

Em situações onde um pagamento ou consentimento venha a falhar, é importante apresentar mensagens de erro que sejam amigáveis, claras e, sempre que possível, ofereçam orientações sobre como o usuário pode proceder para tentar novamente ou corrigir o problema.

Lidando com cenários específicos

Alguns cenários exigem atenção particular na implementação:

Expiração do Pix para pagamento inicial:

• Ao utilizar o endpoint para um pagamento inicial com consentimento, você pode definir um prazo de validade para o QR Code Pix através do parâmetro pix_expiration.
• Caso este parâmetro não seja enviado, o sistema utilizará o valor padrão configurado no seu PagBrasil Dashboard.
• É uma boa prática informar claramente ao usuário final o prazo que ele tem para realizar o pagamento Pix, para evitar que o QR Code expire antes da conclusão.
• A data e hora de expiração também são retornadas na consulta de um pedido via API.

Retentativas de cobrança recorrente:

• A PagBrasil permite a retentativa de cobranças recorrentes que possam ter falhado. Este processo é detalhado na Seção 7 da documentação de integração e utiliza o mesmo endpoint /api/order/add.
• É crucial que, ao reenviar uma cobrança recorrente que falhou, você identifique explicitamente que se trata de uma retentativa. Isso é feito enviando o parâmetro pix_rec_retry com o valor “1”.
• A ausência deste parâmetro em uma retentativa pode levar o banco do cliente a interpretar a nova cobrança como uma tentativa de desonrar o ciclo de consentimento acordado, podendo resultar em problemas.
• A PagBrasil define regras para essas retentativas: é permitido um máximo de três retentativas, que devem ser espaçadas em dias diferentes, ocorrer dentro de 7 dias da data original da cobrança e sempre manter o mesmo valor da cobrança original.

Ao considerar estes casos de uso e seguir as dicas de implementação, você estará mais preparado para construir uma integração com o Pix Automático da PagBrasil que seja não apenas funcional, mas também robusta, segura e que ofereça uma excelente experiência aos seus usuários.

Próximos passos: colocando a mão na massa

Com o conhecimento adquirido ao longo deste guia sobre as jornadas de integração, os endpoints da API, o tratamento de respostas, webhooks e as boas práticas de desenvolvimento, você está bem preparado para iniciar a implementação do Pix Automático da PagBrasil em sua aplicação. Chegou a hora de colocar a teoria em prática.

1. Consulte a documentação técnica completa:
   1. Este artigo ofereceu uma visão abrangente, mas a documentação técnica completa é sua fonte primária para todos os detalhes, incluindo a lista exaustiva de parâmetros, exemplos de retorno, rotinas de validação de CPF/CNPJ e atualizações. Você pode encontrar a documentação de integração do Pix Automático e outros recursos valiosos diretamente no PagBrasil Dashboard, usualmente na seção de “Recursos”.
2. Acesse o ambiente de Sandbox e obtenha suas credenciais:
   1. O primeiro passo prático é realizar a integração no ambiente de Sandbox da PagBrasil. O manual de integração disponibiliza as URLs de teste dos endpoints.
   2. Para autenticar suas requisições, você precisará de credenciais fornecidas pela PagBrasil.
   3. Utilize este ambiente para realizar todos os testes necessários, cobrindo as diferentes jornadas e cenários relevantes para sua aplicação.
3. Entre em contato com o suporte da PagBrasil:
   1. Durante o processo de integração, é natural que surjam dúvidas específicas. A equipe de suporte técnico da PagBrasil está à disposição para auxiliar. Você pode entrar em contato através do e-mail support@pagbrasil.com.
   2. Quando sua integração estiver concluída e exaustivamente testada no ambiente de Sandbox, o próximo passo é migrar para o ambiente de Produção. Para isso, você precisará solicitar a ativação da sua conta para produção e receberá as URLs de produção correspondentes. O contato com a equipe da PagBrasil também será fundamental para este processo de “go live”.

Lembre-se que uma integração bem planejada e testada é a chave para uma operação de pagamentos recorrentes via Pix Automático eficiente e sem surpresas. A PagBrasil oferece as ferramentas e o suporte para que sua jornada de desenvolvimento seja um sucesso.

Sua solução de pagamento recorrente pronta para o futuro

Ao longo deste guia, mergulhamos na integração do Pix Automático da PagBrasil via API. Desde a compreensão do poder transformador do Pix para o cenário de pagamentos recorrentes no Brasil, passando pelas nuances das jornadas de integração, a exploração detalhada dos endpoints, parâmetros e webhooks, até as dicas práticas e casos de uso, nosso objetivo foi fornecer a você, desenvolvedor, o conhecimento necessário para implementar uma solução de pagamentos robusta, segura e flexível.

A integração do Pix Automático da PagBrasil não é apenas sobre adicionar mais um método de pagamento ao seu sistema. Trata-se de abraçar a vanguarda da tecnologia de pagamentos, oferecendo aos seus clientes e usuários uma experiência fluida, ágil e adaptada às suas expectativas modernas. Os diferenciais da nossa solução – como a segurança inerente às transações via API, a flexibilidade das jornadas de consentimento que se adequam tanto a pagamentos iniciais quanto a períodos de trial, e o controle granular que a integração direta proporciona – são projetados para otimizar processos, reduzir atritos e, em última análise, impulsionar a eficiência operacional e a satisfação do cliente.

Ao optar pela API da PagBrasil, você está equipando sua aplicação ou a de seus clientes com uma ferramenta poderosa, capaz de automatizar cobranças, simplificar a gestão de assinaturas e garantir um fluxo de receita recorrente mais previsível e estável. Para os desenvolvedores, isso significa maior controle sobre a experiência do usuário, flexibilidade para customização e a capacidade de integrar profundamente a lógica de pagamentos ao core do negócio.

O futuro dos pagamentos recorrentes já chegou, e ele é impulsionado pela instantaneidade e conveniência do Pix. Com o Pix Automático da PagBrasil, sua solução de pagamento estará não apenas pronta para este futuro, mas na liderança dele.

Encorajamos você a revisitar a documentação técnica, explorar o ambiente de Sandbox e iniciar sua jornada de integração. A equipe da PagBrasil está pronta para apoiá-lo em cada etapa. Integre hoje mesmo e transforme a maneira como sua aplicação lida com pagamentos recorrentes.

Em caso de dúvidas, entre em contato com a nossa equipe.