{"section":"tutorials","requestedLocale":"pt","requestedSlug":"desenvolvendo-um-conector-de-pagamento-para-a-vtex","locale":"pt","slug":"desenvolvendo-um-conector-de-pagamento-para-a-vtex","path":"docs/pt/tutorials/pagamentos/visão-geral-de-pagamentos/desenvolvendo-um-conector-de-pagamento-para-a-vtex.md","branch":"main","content":"Este artigo oferece um guia completo para parceiros que desejam desenvolver [conectores de pagamentos](/pt/docs/tutorials/o-que-e-conector) 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.\n\nAo 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.\n\nEste conteúdo é direcionado a:\n\n- __Desenvolvedores e equipes técnicas de parceiros de pagamento:__ responsáveis pela implementação de soluções de integração eficientes. \n- __Gerentes de produto e times de integração:__ encarregados de garantir a coesão e a operação eficaz dos conectores dentro da plataforma.\n- __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.\n\n## Visão geral\n\nNa VTEX, um conector de pagamentos é o serviço externo que implementa o [VTEX Payment Provider Protocol (PPP)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol). 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.\n\nConfira as seções que você encontrará neste guia:\n\n- [Requisitos técnicos obrigatórios](#requisitos-tecnicos-obrigatorios)\n- [Benefícios da integração PPP](#beneficios-da-integracao-ppp)\n- [Fases de desenvolvimento do conector](#fases-de-desenvolvimento-do-conector)\n- [Escolha da infraestrutura para o conector](#escolha-da-infraestrutura-para-o-conector)\n- [Boas práticas no desenvolvimento de conectores](#boas-praticas-no-desenvolvimento-de-conectores-confiabilidade-e-valor-agregado)\n\n## Requisitos técnicos obrigatórios\n\nOs parceiros que desejam desenvolver um conector de pagamento na VTEX devem implementar as seguintes funcionalidades em suas integrações:\n\n- Autorização de pagamentos (síncrona ou assíncrona).\n- Cancelamento de autorizações antes da captura de valores.\n- Captura de valores (imediata ou agendada).\n- Reembolso de valores após a captura, caso a transação já tenha sido efetivada.\n- Notificações assíncronas de status transacional (atualização automática do status do pagamento na VTEX).\n- Conformidade com a certificação [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance), caso deseje processar meios de pagamento como cartões de crédito, débito ou [co-branded](/pt/tracks/pagamentos--6GAS7ZzGAm7AGoEAwDbwJG/1wWt35dRwEboRs1nrSx7G0#cartoes-da-loja-co-branded). Caso não possua esta certificação, é necessário implementar o conector utilizando a solução [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) da VTEX.\n- 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.\n- Desenvolver os endpoints do conector segundo as melhores práticas para criação de APIs.\n\n## Benefícios da integração PPP\n\nA implementação de conectores desenvolvidos por meio do [VTEX Payment Provider Protocol (PPP)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol) oferece as seguintes vantagens:\n\n- __Otimização de esforço técnico:__ reduz a necessidade do desenvolvimento de integrações customizadas.\n- __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.\n- __Maior conversão de vendas:__ flexibilidade para adaptar-se às particularidades e necessidades específicas de cada lojista.\n- __Gestão centralizada:__ as informações de configuração do conector podem ser administradas diretamente no Admin VTEX.\n\n## Fases de desenvolvimento do conector\n\nO processo de desenvolvimento de um conector VTEX pode ser dividido em quatro fases:\n\n<blockquote><ui>1. **Implementação da API:** os endpoints são desenvolvidos de acordo com o [VTEX Payment Provider Protocol (PPP)](https://developers.vtex.com/docs/api-reference/payment-provider-protocol), incorporando definições como ambiente de operação, infraestrutura e fluxo de compra.</ui>  \n\n<blockquote><ui>2. **Realização de testes:** o conector é validado por meio de testes pré-definidos que asseguram seu funcionamento adequado. Esta etapa é crucial, pois erros identificados podem impactar o SLA de entrega originalmente previsto.</ui>\n\n<blockquote>> ℹ️ Após a conclusão dos [testes iniciais](/pt/docs/tutorials/payment-provider-protocol#4-testes) e o envio do conector para homologação, recomendamos iniciar os [testes de compra](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework#placing-an-order-with-your-new-connector) em ambiente de teste. Essa ação é fundamental para identificar inconsistências que possam interferir no progresso da homologação.</blockquote>\n\n<blockquote><ui>3. **Homologação:** o parceiro desenvolvedor do conector abre uma solicitação, que será tratada pela equipe de Partner Support da VTEX. A partir dessa etapa, inicia-se o processo de validação interna e a publicação do conector no ambiente VTEX.</ui>\n\n<blockquote>> ⚠️ Para iniciar o processo de [homologação de um conector de pagamento](https://developers.vtex.com/docs/guides/integrating-a-new-payment-provider-on-vtex#7-homologation-and-go-live) na plataforma é necessário ter um contrato ativo e não possuir pendências financeiras com a VTEX.</blockquote>\n\n<blockquote><ui>4. **Ativação do conector:** uma vez homologado e publicado, os lojistas poderão configurar os [meios de pagamento](/pt/docs/tutorials/afiliacoes-de-gateway) em suas lojas por meio do [Admin VTEX](/pt/docs/tutorials/admin-vtex-comece-aqui).</ui></blockquote>\n\nPara mais detalhes sobre o fluxo de criação de um conector, acesse [Integrating a new payment provider on VTEX](https://developers.vtex.com/docs/guides/integrating-a-new-payment-provider-on-vtex). \n\n## Escolha da infraestrutura para o conector\n\nDurante a fase de implementação da API, o parceiro pode definir o tipo de infraestrutura que deseja utilizar para integrar o conector na VTEX.\n\nVeja abaixo as características de cada uma das opções de infraestrutura disponíveis:\n\n### Infraestrutura própria\n\n#### Benefícios:\n\n- __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.\n\n- __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](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance), é 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](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy) para captura desses dados.  \n\n#### Aspectos a considerar:  \n\n- __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.\n\n- __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](https://developers.vtex.com/docs/guides/split-payouts-on-payment-provider-protocol) 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.\n\n### Infraestrutura VTEX IO \n\n#### Benefícios:\n\n- __[Payment Provider Framework (PPF)](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework):__ guia completo para a construção de conectores utilizando o VTEX IO.\n\n- __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.\n\n- __Diversas opções de personalização:__ possibilita a criação de componentes de front-end para o [Store Framework](https://developers.vtex.com/docs/guides/store-framework), incluindo banners na página inicial da loja, páginas de categorias, upsell, entre outros.\n\n- __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.\n\n- __Acesso a eventos em tempo real:__ utiliza o [Event Bus](https://medium.com/dev-axe/aws-amazon-eventbridge-event-bus-explained-ad52ec36d185) para acompanhar ações realizadas na plataforma.\n\n- __Integração simplificada com Banco de Dados como Serviço:__ conecta-se facilmente a bancos de dados como VBase e [Master data](/pt/docs/tutorials/master-data) para gerenciar dados de maneira eficiente na sua aplicação.\n\n- __Dispensa a necessidade de desenvolvedores PCI-DSS:__ conectores criados no VTEX IO utilizam o [Secure Proxy](https://developers.vtex.com/docs/guides/payments-integration-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](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance).\n\n- __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.\n\n- __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.  \n\n#### Recursos operacionais:\n\n- __Estrutura Serverless:__ o VTEX IO opera diretamente no ambiente VTEX, eliminando a necessidade de infraestrutura externa.\n\n- __GraphQL + REST APIs:__ oferece suporte a diversas formas de comunicação, proporcionando flexibilidade na integração.\n\n#### Aspectos a considerar:\n\n- __Impossibilidade de acesso direto aos dados de cartão pelo conector__: o VTEX IO não é compatível com os requisitos do [PCI-DSS](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance), 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](https://developers.vtex.com/docs/guides/payments-integration-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.\n\n- __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.\n\n- __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. \n\nA 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](https://developers.vtex.com/docs/api-reference/payment-provider-protocol) é obrigatório para meios de pagamento, enquanto o VTEX IO oferece mais flexibilidade para customizações avançadas.\n\nNa 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.\n\n## Boas práticas no desenvolvimento de conectores: confiabilidade e valor agregado\n\nA 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. \n\n### Diferencial técnico: Idempotência  \n\nA [idempotência](http://pt.wikipedia.org/wiki/Idempot%C3%AAncia) 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.\n\nAs seguintes características operacionais são observadas em conectores que possuem idempotência:\n\n- 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.\n\n- Em casos de falha na rede (comunicação), a confiabilidade da integração é assegurada.\n\n- Quando um lojista ou adquirente reporta um problema transacional, a idempotência garante que os logs e as respostas sejam consistentes e previsíveis.\n\n- 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.\n\n#### Implementando a idempotência\n\nPara implementar a idempotência é necessário adotar as seguintes especificações durante o desenvolvimento do conector: \n\n1. Garantir um identificador único para cada transação (`paymentId`).\n2. Armazenar e reutilizar a resposta (sucesso, falha, pendente) da requisição em caso de reenvio.\n3. Definir um tempo de expiração para os registros idempotentes.\n4. Assegurar que a idempotência seja mantida também para cancelamentos e estornos.\n5. Em caso de utilização da infraestrutura VTEX IO:\n   - Considere utilizar o VBase para armazenar a resposta com base no `paymentId` enviado pelo Gateway de pagamento, através da rota [Create Payment](https://developers.vtex.com/docs/api-reference/payment-provider-protocol#post-/payments).\n   - 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](https://github.com/vtex-apps/payment-provider-example/blob/main/node/connector.ts#L53).\n\n### Recursos estratégicos para o negócio \n\nAlé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.\n\n#### Suporte a carteiras digitais (Apple Pay, NuPay, Google Pay, PayPal)\n\nO 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:  \n\n- __Checkout mais fluido:__ reduz a fricção no pagamento, já que os dados do cartão estão armazenados na carteira digital.\n- __Segurança aprimorada:__ o uso de autenticação biométrica e tokenização minimiza fraudes e chargebacks.\n- __Maior conversão:__ menos etapas no checkout resultam em menor abandono de carrinho.  \n\n#### Suporte ao Google Pay com tokenização DPAN (Device Primary Account Number)\n\nO suporte ao Google Pay com [tokenização DPAN](/pt/docs/tutorials/dpan-e-fpan-entendendo-a-seguranca-no-fluxo-de-pagamentos-tokenizados-online) proporciona vantagens importantes para a segurança e a experiência do usuário:  \n\n- __Maior segurança:__ os dados reais do cartão não são compartilhados, reduzindo riscos de fraude.\n- __Menor fricção em compras recorrentes:__ DPANs podem ser reutilizados (pagamentos recorrentes) sem necessidade de solicitar novamente os dados do usuário.\n- __Compatibilidade com múltiplos dispositivos:__ permite o uso do mesmo cartão em diferentes dispositivos sem nova autenticação.\n- __Redução de custos com fraudes:__ a tokenização evita o uso indevido de credenciais, o que pode diminuir o número de chargebacks.  \n\n> ⚠️ O suporte ao Google Pay com DPAN só está disponível por meio da [carteira Google Pay nativa da VTEX](/pt/docs/tracks/google-pay).  \n\n#### Suporte a pagamento via POS (VTEX Sales App) \n\nConectores compatíveis com pagamentos via [POS](https://pt.wikipedia.org/wiki/Caixa_(varejo)) no [VTEX Sales App](https://help.vtex.com/pt/docs/tracks/vtex-sales-app-primeiros-passos-e-configuracoes) viabilizam transações [Omnichannel](/pt/docs/tracks/comercio-unificado-101) entre o ambiente físico e digital. Entre os benefícios, estão:\n\n- __Integração entre canais:__ o cliente pode iniciar uma compra online e finalizá-la na loja física utilizando o mesmo meio de pagamento.\n- __Redução de erros operacionais:__ como o pagamento é integrado ao VTEX Sales App, não é necessário registrar transações manualmente no [ERP](https://pt.wikipedia.org/wiki/Sistema_integrado_de_gest%C3%A3o_empresarial).\n- __Melhoria na experiência de compra:__ vendedores conseguem processar pagamentos rapidamente em um único sistema.\n- __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.  \n\n#### Suporte ao split de recebíveis\n\nConectores com funcionalidade de [split de recebíveis](/pt/docs/tutorials/split-de-pagamento#split-de-recebiveis) 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.\n\n- __Distribuição automatizada de pagamentos__: o valor da transação é dividido de forma automática, garantindo eficiência e menor risco operacional.\n- __Redução de custos e complexidade__: elimina repasses manuais, reduz custos administrativos e acelera a conciliação financeira.\n- __Flexibilidade para diferentes modelos de negócio__: viabiliza operações com modelos como marketplace, ship-from-store e dropshipping.\n\n## Saiba mais\n\n- [VTEX Payment Provider Protocol - Help Center](/pt/docs/tutorials/payment-provider-protocol)\n- [Secure Proxy - Help Center](https://developers.vtex.com/docs/guides/payments-integration-secure-proxy#custom-supported-operators)\n- [VTEX Master Data - Help Center](/pt/docs/tutorials/master-data)\n- [Implementing a Payment Provider - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-implementing-a-payment-provider)\n- [Payment Provider Framework - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-payment-provider-framework)\n- [Split Payouts on Payment Provider Protocol - Dev. Portal](https://developers.vtex.com/docs/guides/split-payouts-on-payment-provider-protocol)\n- [PCI-DSS - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-pci-dss-compliance)\n- [Payment apps - Dev. Portal](https://developers.vtex.com/docs/guides/payments-integration-payment-app)\n- [Whats is VTEX IO - Dev. Portal](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-vtex-io)\n- [Exemplo de integração: payment-provider-example - GitHub](https://github.com/vtex-apps/payment-provider-example)\n- [Developing services on VTEX IO - Learning Center](https://learn.vtex.com/docs/course-service-course-lang-en)"}