Este artigo oferece um guia completo para parceiros que desejam desenvolver conectores de pagamentos compatíveis com a plataforma VTEX. O foco é garantir uma integração eficiente e padronizada, permitindo que os conectores sejam usados em todas as lojas da plataforma.

Ao adotar as diretrizes apresentadas, os parceiros garantem que sua integração atenda aos mais altos padrões de qualidade, agregando valor tanto para os lojistas quanto para seus clientes, e promovem a inovação e a competitividade no comércio digital.

Este conteúdo é direcionado a:

• Desenvolvedores e equipes técnicas de parceiros de pagamento: responsáveis pela implementação de soluções de integração eficientes.
• Gerentes de produto e times de integração: encarregados de garantir a coesão e a operação eficaz dos conectores dentro da plataforma.
• Equipes de suporte técnico de provedores de pagamento, gateways e sistemas antifraude: oferecem suporte contínuo, assegurando a operação estável e a conformidade das soluções.

Na VTEX, um conector de pagamentos é o serviço externo que implementa o VTEX Payment Provider Protocol (PPP). Este protocolo permite a comunicação entre a plataforma e os provedores de pagamento (como gateways, adquirentes e soluções antifraude), possibilitando que lojistas processem transações de forma integrada e padronizada, sem a necessidade de desenvolver integrações personalizadas.

Confira as seções que você encontrará neste guia:

• Requisitos técnicos obrigatórios
• Benefícios da integração PPP
• Fases de desenvolvimento do conector
• Escolha da infraestrutura para o conector
• Boas práticas no desenvolvimento de conectores

Os parceiros que desejam desenvolver um conector de pagamento na VTEX devem implementar as seguintes funcionalidades em suas integrações:

• Autorização de pagamentos (síncrona ou assíncrona).
• Cancelamento de autorizações antes da captura de valores.
• Captura de valores (imediata ou agendada).
• Reembolso de valores após a captura, caso a transação já tenha sido efetivada.
• Notificações assíncronas de status transacional (atualização automática do status do pagamento na VTEX).
• Conformidade com a certificação PCI-DSS, caso deseje processar meios de pagamento como cartões de crédito, débito ou co-branded. Caso não possua esta certificação, é necessário implementar o conector utilizando a solução Secure Proxy da VTEX.
• Assegurar a alta disponibilidade e a abrangência regional do conector, em conformidade com as disposições estabelecidas no contrato de parceria firmado com a VTEX.
• Desenvolver os endpoints do conector segundo as melhores práticas para criação de APIs.

A implementação de conectores desenvolvidos por meio do VTEX Payment Provider Protocol (PPP) oferece as seguintes vantagens:

• Otimização de esforço técnico: reduz a necessidade do desenvolvimento de integrações customizadas.
• Escalabilidade: novos meios de pagamento podem ser adicionados rapidamente. Uma vez publicado, o conector de um parceiro torna-se disponível a todos os lojistas da VTEX, potencializando o alcance e a adoção da solução.
• Maior conversão de vendas: flexibilidade para adaptar-se às particularidades e necessidades específicas de cada lojista.
• Gestão centralizada: as informações de configuração do conector podem ser administradas diretamente no Admin VTEX.

O processo de desenvolvimento de um conector VTEX pode ser dividido em quatro fases:

Para mais detalhes sobre o fluxo de criação de um conector, acesse Integrating a new payment provider on VTEX.

Durante a fase de implementação da API, o parceiro pode definir o tipo de infraestrutura que deseja utilizar para integrar o conector na VTEX.

Veja abaixo as características de cada uma das opções de infraestrutura disponíveis:

Benefícios:

• Liberdade na escolha das ferramentas de desenvolvimento: como a infraestrutura é totalmente controlada pelo desenvolvedor, ele tem plena liberdade para selecionar as ferramentas que melhor atendem às suas necessidades, como linguagens de programação, bancos de dados e outros recursos tecnológicos.

• Recebimento direto de dados de cartão no conector: ao desenvolver um conector em sua própria infraestrutura, em conformidade com os padrões PCI-DSS, é possível receber os dados de cartão diretamente, caso seja necessário para o negócio. Isso elimina a necessidade de utilizar funcionalidades como o Secure Proxy para captura desses dados.

Aspectos a considerar:

• Necessidade de manutenção de infraestrutura: ao desenvolver o conector em sua própria infraestrutura, o time de desenvolvimento assume a responsabilidade pela manutenção, escalabilidade e estabilidade do sistema, o que aumenta a carga de trabalho para garantir seu bom funcionamento.

• Menor autonomia para realizar mudanças: ao desenvolver um conector fora da infraestrutura VTEX IO, alterações como a adição de novos meios de pagamento ou a ativação de split exigem que o desenvolvedor entre em contato com a equipe da VTEX para solicitar modificações. Esse processo está sujeito a um SLA definido pela equipe de pagamentos da VTEX, podendo durar até 30 dias.

Benefícios:

• Payment Provider Framework (PPF): guia completo para a construção de conectores utilizando o VTEX IO.

• Flexibilidade total: pode ser utilizado para qualquer tipo de integração, não se limitando apenas a meios de pagamento. Além disso, oferece facilidade para implementar personalizações adicionais no conector, quando necessário.

• Diversas opções de personalização: possibilita a criação de componentes de front-end para o Store Framework, incluindo banners na página inicial da loja, páginas de categorias, upsell, entre outros.

• Desenvolvimento integrado ao ecossistema VTEX: permite criar apps que interagem com todas as APIs e eventos da plataforma, como a captação de dados de CRM, detalhamento das informações do carrinho e checkout, dados de logística, entre outros.

• Acesso a eventos em tempo real: utiliza o Event Bus para acompanhar ações realizadas na plataforma.

• Integração simplificada com Banco de Dados como Serviço: conecta-se facilmente a bancos de dados como VBase e Master data para gerenciar dados de maneira eficiente na sua aplicação.

• Dispensa a necessidade de desenvolvedores PCI-DSS: conectores criados no VTEX IO utilizam o Secure Proxy para o tratamento de dados de cartão, garantindo que o conector não tenha acesso direto aos dados sensíveis, embora o parceiro ainda precise ser PCI-DSS.

• Ausência de manutenção de infraestrutura: ao desenvolver o conector no VTEX IO, toda a gestão de infraestrutura é automatizada, permitindo que o desenvolvedor concentre-se exclusivamente nas regras de negócio, sem se preocupar com questões técnicas de infraestrutura.

• Atualização automatizada por versionamento da app: as atualizações do conector são realizadas de forma automatizada, sem necessidade de intervenção do time da VTEX.

Recursos operacionais:

• Estrutura Serverless: o VTEX IO opera diretamente no ambiente VTEX, eliminando a necessidade de infraestrutura externa.

• GraphQL + REST APIs: oferece suporte a diversas formas de comunicação, proporcionando flexibilidade na integração.

Aspectos a considerar:

• Impossibilidade de acesso direto aos dados de cartão pelo conector: o VTEX IO não é compatível com os requisitos do PCI-DSS, portanto, conectores desenvolvidos nesta plataforma não têm acesso direto aos dados de cartão. Para tratar essas informações, é necessário usar a funcionalidade Secure Proxy. Caso o modelo de negócio precise processar os dados do cartão antes de enviá-los à adquirente, o VTEX IO pode não ser a melhor opção, já que não permite esse nível de acesso.

• Limitações nas linguagens e frameworks suportados: o VTEX IO é compatível apenas com algumas linguagens e frameworks específicos, como React, Node e .NET. Desenvolvedores que não estão familiarizados com essas tecnologias precisarão se adaptar ao ambiente, o que pode demandar tempo adicional para aprendizado e ajustes no fluxo de trabalho.

• Necessidade de aprendizado do VTEX IO: embora o VTEX IO seja intuitivo e fácil de usar, ele possui características específicas que exigem que o desenvolvedor compreenda seu funcionamento para aproveitar seu potencial total. Para aqueles sem experiência prévia, será necessário um tempo de adaptação para aprender as particularidades da plataforma.

A escolha entre desenvolver um conector na infraestrutura própria ou no VTEX IO depende das necessidades de cada integração e do nível de personalização desejado. O PPP é obrigatório para meios de pagamento, enquanto o VTEX IO oferece mais flexibilidade para customizações avançadas.

Na definição da infraestrutura, considere o know-how da equipe como um fator estratégico. Trabalhar com tecnologias familiares reduz riscos, acelera a entrega e aumenta a eficiência operacional.

A seguir, são apresentadas as melhores práticas para o desenvolvimento de conectores, abrangendo uma característica técnica e recursos de negócios essenciais para garantir a eficácia e a qualidade da integração. As características descritas refletem as melhores abordagens observadas ao longo dos anos de colaboração com adquirentes, agências e provedores de antifraude, visando sempre a construção de soluções de alta performance e confiabilidade.

A idempotência no conector garante que múltiplas requisições com os mesmos parâmetros tenham o mesmo efeito, independentemente de quantas vezes sejam enviadas. Esse comportamento é essencial em fluxos críticos, como o transacional. Além disso, a VTEX realiza tentativas automáticas de chamadas idênticas (retry), o que pode resultar em múltiplas requisições com o mesmo paymentId para atualizar o status da transação.

As seguintes características operacionais são observadas em conectores que possuem idempotência:

• Pagamentos duplicados são evitados em caso de reenvio automático. Este comportamento assegura o processamento único de uma transação, evitando duplicidades. Caso o conector não seja idempotente, podem ocorrer cobranças duplicadas, gerando inconsistências.

• Em casos de falha na rede (comunicação), a confiabilidade da integração é assegurada.

• Quando um lojista ou adquirente reporta um problema transacional, a idempotência garante que os logs e as respostas sejam consistentes e previsíveis.

• O número de chamadas desnecessárias ao provedor é reduzido. Caso o pagamento já tenha sido processado, o conector pode simplesmente retornar a resposta previamente registrada, evitando a necessidade de uma nova requisição ao adquirente.

Implementando a idempotência

Para implementar a idempotência é necessário adotar as seguintes especificações durante o desenvolvimento do conector:

1. Garantir um identificador único para cada transação (paymentId).
2. Armazenar e reutilizar a resposta (sucesso, falha, pendente) da requisição em caso de reenvio.
3. Definir um tempo de expiração para os registros idempotentes.
4. Assegurar que a idempotência seja mantida também para cancelamentos e estornos.
5. Em caso de utilização da infraestrutura VTEX IO:
   • Considere utilizar o VBase para armazenar a resposta com base no paymentId enviado pelo Gateway de pagamento, através da rota Create Payment.
   • Ao receber uma nova chamada, o conector pode verificar no VBase se uma requisição semelhante já foi registrada. Se sim, a resposta previamente registrada pode ser retornada. Veja este exemplo de implementação.

Além da confiabilidade técnica, alguns recursos funcionais podem ampliar significativamente o impacto comercial do conector. A seguir, destacamos funcionalidades que contribuem diretamente para o sucesso da operação, promovendo maior segurança, eficiência e conversão.

Suporte a carteiras digitais (Apple Pay, NuPay, Google Pay, PayPal)

O uso crescente de carteiras digitais (wallets) traz mais segurança e conveniência para os consumidores. Conectores que suportam essas carteiras oferecem os seguintes benefícios:

• Checkout mais fluido: reduz a fricção no pagamento, já que os dados do cartão estão armazenados na carteira digital.
• Segurança aprimorada: o uso de autenticação biométrica e tokenização minimiza fraudes e chargebacks.
• Maior conversão: menos etapas no checkout resultam em menor abandono de carrinho.

Suporte ao Google Pay com tokenização DPAN (Device Primary Account Number)

O suporte ao Google Pay com tokenização DPAN proporciona vantagens importantes para a segurança e a experiência do usuário:

• Maior segurança: os dados reais do cartão não são compartilhados, reduzindo riscos de fraude.
• Menor fricção em compras recorrentes: DPANs podem ser reutilizados (pagamentos recorrentes) sem necessidade de solicitar novamente os dados do usuário.
• Compatibilidade com múltiplos dispositivos: permite o uso do mesmo cartão em diferentes dispositivos sem nova autenticação.
• Redução de custos com fraudes: a tokenização evita o uso indevido de credenciais, o que pode diminuir o número de chargebacks.

O suporte ao Google Pay com DPAN só está disponível por meio da carteira Google Pay nativa da VTEX.

Suporte a pagamento via POS (VTEX Sales App)

Conectores compatíveis com pagamentos via POS no VTEX Sales App viabilizam transações Omnichannel entre o ambiente físico e digital. Entre os benefícios, estão:

• Integração entre canais: o cliente pode iniciar uma compra online e finalizá-la na loja física utilizando o mesmo meio de pagamento.
• Redução de erros operacionais: como o pagamento é integrado ao VTEX Sales App, não é necessário registrar transações manualmente no ERP.
• Melhoria na experiência de compra: vendedores conseguem processar pagamentos rapidamente em um único sistema.
• Suporte a diferentes opções de pagamento: o POS pode aceitar cartões de crédito, débito, Pix via QR Code e carteiras digitais.

Suporte ao split de recebíveis

Conectores com funcionalidade de split de recebíveis permitem dividir automaticamente o valor de uma transação entre diferentes destinatários no momento da autorização ou da captura, dependendo da configuração do provedor. Essa funcionalidade é essencial para marketplaces e operações omnichannel.

• Distribuição automatizada de pagamentos: o valor da transação é dividido de forma automática, garantindo eficiência e menor risco operacional.
• Redução de custos e complexidade: elimina repasses manuais, reduz custos administrativos e acelera a conciliação financeira.
• Flexibilidade para diferentes modelos de negócio: viabiliza operações com modelos como marketplace, ship-from-store e dropshipping.

• VTEX Payment Provider Protocol - Help Center
• Secure Proxy - Help Center
• VTEX Master Data - Help Center
• Implementing a Payment Provider - Dev. Portal
• Payment Provider Framework - Dev. Portal
• Split Payouts on Payment Provider Protocol - Dev. Portal
• PCI-DSS - Dev. Portal
• Payment apps - Dev. Portal
• Whats is VTEX IO - Dev. Portal
• Exemplo de integração: payment-provider-example - GitHub
• Developing services on VTEX IO - Learning Center