Integrar conector ao New Payment Provider

VTEX Team

VTEX Team

Última atualização

O que é o New Payment Provider

New Payment Provider é o novo protocolo de integração entre a VTEX e as empresas que processam pagamentos.

Por meio dele, a VTEX passa a disponibilizar um contrato genérico público a todos os providers que desejam se integrar. Com isso, os providers ganham maior autonomia sobre a integração.

Por meio do Payment Provider, a VTEX envia um payload com os dados do pagamento para o parceiro, ele processa esses dados e nos envia a resposta com o status Aprovado, Negado ou Undefined.

Quando o provider responde “Undefined”, ele obrigatoriamente deve chamar o nosso “CallBackUrl” (que é enviado junto ao payload de pagamento) assim que tiver o status final (Aprovado ou Negado).

Além do serviço para receber o pagamento, o provider precisa implementar um serviço de cancelamento, de captura e reembolso.

O modelo da API é descrito no seguinte documento: http://resources.vtex.com/raml/pci-gateway/payment-provider/v2/payment-provider.html

O novo protocolo traz as seguintes melhorias em relação ao protocolo anterior:

  • Homologação feita pelo próprio provider (Parceiro) usando o admin da VTEX;
  • Suporte a pré-autorização (captura em 2 passos);
  • Suporte a protocolo OAuth para autenticação do lojista.

Conceitos

Provider: empresa que processa pagamentos;

Payment Provider: protocolo de integração desenvolvido pela VTEX;

Oauth: protocolo de autorização para APIs web voltado a permitir que aplicações client acessem um recurso protegido em nome de um usuário. Quando desenvolvemos uma API web temos em mente que ela seja consumida por aplicações client;

Profile: conjunto de dados do comprador, como endereço, número de documento, e-mail etc.;

Conector: nome da integração VTEX-Parceiro no ambiente do lojista na VTEX;

CallBackUrl: URL de retorno para um pagamento específico.

Pré-requisito

O único pré-requisito para se tornar um provider integrado à VTEX é ter o certificado PCI. (Mais informações no site do PCI Security Standards Council: https://pt.pcisecuritystandards.org).

Se o provider é certificado ou já iniciou o processo de certificação, ele já pode entrar em contato com a equipe comercial da VTEX para iniciar a integração.

Primeiros passos para se integrar à VTEX

1. Fase comercial

O primeiro passo é o contato comercial com a VTEX, que deve ser realizado pelo nosso site: http://partner.vtex.com.

Depois de fechado o contrato comercial, o provider é cadastrado e já recebe um e-mail com os dados de acesso ao ambiente Payment Provider, onde pode realizar as configurações e testes necessários.

2. Implementação do protocolo

Antes de fazer as configurações dentro do ambiente VTEX, o provider deve implementar o serviço back-end necessário para receber os pagamentos (API).

http://resources.vtex.com/raml/pci-gateway/payment-provider/v2/payment-provider.html

3. Acesso

Com os dados de acesso em mãos e o back-end implementado, o provider já pode iniciar o acesso à ferramenta de homologação, por meio do admin VTEX.

Para isso, é preciso entrar em: https://my_account_name.vtexcommercebeta.com.br/admin/payment-provider.

Nesse ambiente, é possível cadastrar os dados da implementação que foi criada e realizar os testes da integração.

4. Configuração inicial

Na barra superior do Payment Provider, clique em Configuração para abrir a tela de configurações.

Menu do Payment Provider

Nela, clique em “edit info”. Depois, você deve preencher os seguintes campos:

  • Connector Name: É o nome que você deseja dar ao seu conector VTEX. Este campo já estará preenchido no primeiro acesso, mas pode ser editado.
  • Service URL: É neste endereço que o serviço do Provider (parceiro) responde. Esta URL precisa seguir o formato determinado pelo protocolo. Essa URL base será concatenada, por exemplo, com o parâmetro “/payments”. Ou seja, se ela é http://10.10.10.10, a URL completa será http://10.10.10.10/payments.
  • Application Key: Neste campo deve ser inserido o parâmetro de request que será usado no cabeçalho de todas as requisições (independentemente de se usar protocolo OAuth ou não). Ou seja, é o parâmetro que funciona como usuário. Aqui encontra-se uma das diferenças para o protocolo antigo: a VTEX não envia mais o Account Name. Isso precisa ser resolvido por meio dessa chave.
  • Application Token: É o campo que funciona como senha. O provider precisa identificar quem é o Account Name (ou seja, o lojista) por meio do Application Key e do Application Token.
  • Available Payment Systems: É onde aparecem as bandeiras e meios de pagamento suportados pelo provider. Esses meios de pagamento são listados pelo serviço desenvolvido pelo provider em /payment-methods
  • Use OAuth: Com o novo protocolo, é possível desenvolver suporte a duas formas de autenticação do lojista: Key/Token (usuário/senha) ou OAuth. Por meio do OAuth, a chave precisa ser carregada na Key (Key = chave / Token = vazio). Ou seja, de qualquer maneira, todo request usará os dois campos (Key e Token). A diferença é que com OAuth o Token ficará vazio. Por isso, fique atento: se seu provider vai suportar protocolo OAuth, não pode ser utilizada nenhuma condição de validação do Token.
  • Use AntiFraud: Caso o provider deseje receber os dados do Profile junto aos dados do pagamento.
  • Reload connector data: Caso você tenha preenchido algum campo de maneira errada e deseje recarregar os dados salvos anteriormente, basta clicar neste botão.
  • Save data: Após revisar todos os campos, salve suas configurações. Este processo será concluído apenas se tudo estiver correto.

Tela inicial de configuração

Tela do formulário de cadastro dos dados do provider

Após salvar os dados, o provider pode clicar no botão “Start Homologation Mode” para começar os testes.

Botão “Start Homologation Mode”

Após iniciar o Modo Homologação, você estará pronto para começar os testes automatizados.

5. Testes

Depois de feitas as configurações, o provider pode testá-las para diferentes cenários.

A área de testes é dividida em quatro abas: Configuração, Configuração de teste, Execução e Resultados.

Permissões

Para ter acesso ao sistema, o usuário deve ser configurado com as roles “AdminSuper”, “PCI” e “PaymentProvider”.

Configuração de teste

Clicando na aba Configuração, o provider irá informar os dados do serviço por ele implementado para entrar no Modo Homologação.

Clicando na aba Configuração de teste, o provider tem acesso a outras cinco abas, cada uma delas correspondendo a um tipo de cenário diferente. Para cada um desses tipos, o provider tem à disposição os campos para preenchimento das informações do cartão (bandeira, número do cartão, nome do titular, cvv, validade etc.), além de diversos outros campos para preenchimento de informações adicionais.

Após preencher todos os campos desejados, basta salvar a configuração no botão ao final da página.

Seguem abaixo os cinco tipos de cenário que podem ser testados:

  1. Undefined: O teste de Undefined está entre os mais básicos que o provider deve realizar. Neste cenário, é realizada apenas uma transação, e em seguida verifica-se se ela foi ou não autorizada. Para que estes dois passos sejam concluídos corretamente, deve existir uma condição (valor da transação, número específico do cartão etc.), criada pelo provider, que não responda à transação no intervalo de 10 segundos. Após este tempo, deve-se obter “undefined” como resposta em até 5 segundos. Caso contrário, a transação deve ser cancelada.
  2. Not approved: Os testes de “Not approved” também realizam apenas uma transação e verificam se ela foi autorizada. Mas neste caso, deve existir uma condição (valor da transação, número específico do cartão etc.), indicada pelo cliente, que negue imediatamente a transação.
  3. One credit card: Este é o cenário de compra com um cartão de crédito.
  4. Two credit cards: Este é o cenário de compra com dois cartões de crédito, em que o valor do pedido é dividido entre os dois cartões.
  5. Bank issued: Este é o cenário de compra via boleto bancário.

Os cenários de One credit card, Two credit cards e Bank issued são mais complexos que os dois primeiros. Os testes de cada um deles realizam diversas simulações diferentes, tanto positivas quanto negativas.

Execução

Depois de configurados os cenários desejados, o provider deve acessar a aba Execução, onde os testes são de fato realizados.