VTEX

A VTEX é uma plataforma de comércio digital empresarial que permite criar rapidamente uma loja online com recursos integrados. Para mais informações, visite o site oficial da VTEX.

Pré-requisitos

Antes de integrar o PayU com o VTEX, certifique-se de ter o seguinte:

• Uma conta PayU Latam ativa.
• Uma conta PayU Enterprise (PaymentsOS) ativa no modo de produção/ao vivo. Para mais detalhes sobre como ativá-la, consulte Ativando sua conta PayU Enterprise.
• Uma conta VTEX com direitos e permissões suficientes para acessar o painel administrativo da VTEX. Essa conta deve ter a autenticação de dois fatores ativada.

Disponibilidade por País e Métodos de Pagamento

A tabela abaixo mostra a disponibilidade da VTEX por país e os métodos de pagamento compatíveis:

País	Cartões de Crédito	Pagamentos em Dinheiro	Outros Métodos
Argentina	Cartões de crédito	Pagamentos em dinheiro	-
Brasil	AMEX, MasterCard, Visa	Boleto Bancário	-
Colômbia	AMEX, Codensa, Diners, MasterCard, Visa	Efecty, Su Red, referência bancária	PSE
Chile	Cartões de crédito	Pagamentos em dinheiro	-
México	Cartões de crédito	Pagamentos em dinheiro	SPEI
Peru	AMEX, MasterCard, Visa	-	-

Ativando sua Conta PayU Enterprise (Modo Ativo)

Por padrão, novas contas são configuradas no modo de teste. Para habilitar transações ao vivo, entre em contato com seu gerente de conta e envie uma solicitação com os seguintes detalhes:

• Merchant ID: Localize o Merchant ID da sua conta LATAM no Painel de Gerenciamento do PayU.
• Account ID: Encontre seu Account ID no painel de controle do PayU Enterprise clicando no seu nome de usuário no canto superior direito.
  

Configurando sua Conta PayU Enterprise

Para configurar os métodos de pagamento na VTEX para processamento através do nosso gateway, siga os passos abaixo. A configuração consiste em duas etapas. Antes de prosseguir, certifique-se de ter atendido aos pré-requisitos mencionados acima.

1. Configuração Inicial

O PayU Enterprise opera através do PaymentsOS, que atua como middleware entre o PayU Latam e o VTEX. O primeiro passo é configurar os seguintes componentes dentro da sua conta PayU Enterprise:

• Configuração do provedor
• Unidade de negócios
• Webhook

Você pode configurar esses componentes utilizando um dos seguintes métodos:

• Configurando a conta usando o Postman.
• Configurando a conta manualmente pelo painel da PayU Enterprise.

Configurando a Conta Usando o Postman

Siga estas etapas para configurar sua conta usando o Postman:

1. Clique no botão abaixo para importar nossa coleção do Postman (atualize a página se o botão não funcionar).

2. Após importar a coleção, defina as variáveis globais. Baixe o arquivo de variáveis globais aqui.

3. No Postman, clique em Import ao lado do nome do seu workspace e selecione o arquivo JSON baixado.

4. Clique em Import para finalizar o processo.

5. Execute os métodos da coleção na ordem exibida. Primeiro, selecione o método POST chamado 1. Login e, em seguida, vá até a aba Body.

6. Insira seu e-mail e senha da sua conta PayU Enterprise e clique em Send. Se o login for bem-sucedido, os dados de autenticação serão definidos para o próximo método.

7. Clique no método GET 2. Retrieve PayU Latam ID.

8. No canto superior direito, clique no ícone de olho para localizar o parâmetro env. Clique no ícone de lápis e defina-o como test para ambiente de teste ou live para produção.

9. Clique em Send para continuar.

10. Em seguida, configure o provedor, que armazena suas credenciais de processamento de pagamento. Selecione o método POST 3. Create Provider Configuration e vá até a aba Body.

Preencha os seguintes detalhes:

11. Configure a unidade de negócios, que vincula a configuração do provedor com as credenciais da API PayU Enterprise para processar transações. Selecione o método POST 4. Create Business Unit e, em seguida, navegue até a aba Body.

Preencha os seguintes detalhes:

12. Crie o webhook, que recebe notificações da VTEX quando o status de uma transação muda. Selecione o método POST 5. Create Webhook e, em seguida, navegue até a aba Body.

Defina o parâmetro endpoint com base no seu ambiente:

• Teste: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Produção: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

Mantenha todos os outros parâmetros com seus valores padrão.

Neste ponto, sua conta PayU Enterprise usando PaymentsOS está configurada. O próximo passo é Configurar o Provedor VTEX.

Configurando a Conta Manualmente Usando o Painel PayU Enterprise

Siga estas etapas para configurar sua conta usando o painel PayU Enterprise.

1. Criar a Configuração do Provedor

Um provedor armazena suas credenciais de processamento de pagamento. Siga estas etapas para configurar um:

1.1 No painel do PayU Enterprise, navegue até Configurations > Providers.

1.2 Clique no módulo correspondente ao país ou divisão que você está configurando.

1.3 Preencha os seguintes campos:

1.4 Clique em Create.

2. Criar a Unidade de Negócios

Uma unidade de negócios vincula a configuração do provedor com as credenciais da API do PayU Enterprise para processar transações. Siga estas etapas:

2.1 No painel, vá para Configurations > Business Units.

2.2 Clique em Create Business Unit e insira:

2.3 Na seção Choose a Default Provider for This Business Unit, selecione a Provider Configuration criada na Etapa 1. Depois, clique em Create.

3. Criar o Webhook

O webhook recebe notificações do VTEX quando o status de uma transação muda. Siga estas etapas:

3.1 No painel, navegue até Configurations > Webhooks.

3.2 Clique em Create a Webhook Endpoint e insira a URL apropriada com base no seu ambiente:

• Teste: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Produção: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

3.3 Na tabela Payment Event Alerts, ative o controle deslizante Update para Authorization e Charge. Em seguida, no campo Associated Business Units, insira a Business Unit criada na etapa anterior. Por fim, clique em Create.

Neste ponto, sua conta PayU Enterprise usando PaymentsOS está totalmente configurada. O próximo passo é configurar o provedor VTEX.

2. Configurando o Provedor VTEX

Depois de configurar sua conta PayU Enterprise, o próximo passo é configurar o provedor VTEX para cada método de pagamento. Para prosseguir, você deve ter uma conta de usuário válida para acessar o admin da VTEX.

Criando um Novo Provedor

1. No painel esquerdo, selecione Configurações da Loja > Provedores > Novo Provedor:

2. Localize PayU e selecione PayUv2:

3. Na configuração do conector, instale-o clicando no botão Instalar aplicativo. Em seguida, preencha os seguintes campos:

4. Clique em Salvar para concluir a configuração.

Configurando Métodos de Pagamento

Configure os métodos de pagamento que serão exibidos no site durante o checkout. Veja os métodos de pagamento disponíveis.

Configurando Cartões de Crédito ou Débito

Dependendo do seu país de processamento, você pode configurar a afiliação criada para usar cartões de crédito ou débito^*. Siga as etapas abaixo para adicionar esse método de pagamento à sua loja VTEX.

^* A disponibilidade de cartões de débito depende do seu país de processamento.

1. No painel esquerdo, selecione Transações > Pagamentos > Configurações. Selecione a guia Condições de Pagamento e clique no ícone de adição.

2. Selecione o método de pagamento que deseja adicionar. Os métodos de pagamento são agrupados por tipo.
   Para este exemplo, selecionamos American Express na seção de Cartão de Crédito.

3. Forneça os seguintes detalhes:

• Nome da Regra (para identificação rápida): Insira um nome descritivo para a condição de pagamento.
• Status: Defina o status da condição de pagamento. Você pode ter apenas uma condição de pagamento ativa por método de pagamento.
• Processar com afiliação: Selecione a afiliação do gateway configurada anteriormente.
• Pagamento à vista ou parcelado?: Selecione À vista.

4. Clique em Salvar. A nova condição de pagamento agora será listada na guia Condições de Pagamento.

Configurando Cartões Co-Branded ou Private Label

Os cartões co-branded e private label são cartões de crédito emitidos por uma loja ou marca, às vezes em parceria com redes como AMEX, VISA ou MasterCard. Siga estas etapas para adicionar esse método de pagamento à sua loja VTEX.

1. No painel esquerdo, selecione Transações > Pagamentos > Configurações. Selecione a guia Pagamentos customizados.

2. A guia Pagamentos customizados fornece cinco (5) espaços para configurar cartões co-branded e private label. Neste exemplo, configuramos o cartão colombiano Codensa, que é um cartão private label.
   Clique em qualquer caixa disponível na seção Cartões da Loja (Bandeira Própria).

3. Insira os seguintes detalhes do cartão, mantendo o formato exato:

• Nome: Codensa.
• Descrição: Codensa
• Intervalos de BIN: 590712-590712
• Código de pagamento do adquirente: codensa

Use a tabela abaixo para configurar cartões co-branded e private label. Você pode deixar os valores restantes com suas entradas padrão.

País	Nome	Descrição	Intervalos de BIN	Código de pagamento do adquirente
	Argencard	Argencard	501105-532362	argencard
	Cabal	Cabal	60423,60400,589657	cabal
	Cencosud	Cencosud	603493-603493	cencosud
	Naranja	Naranja	589562	naranja
	Shopping	Shopping	603488	shopping
	Codensa	Codensa	590712-590712	codensa

Para mais detalhes sobre a configuração de cartões co-branded e private label, visite o VTEX Help Center.

4. Clique em Salvar. Após criar o pagamento personalizado, você será redirecionado para a opção de criar uma Condição de Pagamento. Siga as instruções na seção Configurando Cartões de Crédito ou Débito para concluir esta etapa.

Configurando Métodos de Pagamento em Dinheiro

Como os pagamentos em dinheiro exigem que os clientes efetuem o pagamento em locais físicos, você pode configurar esse método de pagamento na VTEX como notas promissórias (Notes Payables).

Ao configurar um método de pagamento em dinheiro, os clientes são redirecionados para o checkout da PayU, onde podem baixar o comprovante de pagamento e pagá-lo no local físico correspondente. Siga as instruções abaixo para adicionar esse método de pagamento à sua loja VTEX.

1. No painel esquerdo, selecione Transações > Pagamentos > Configurações. Selecione a guia Pagamentos customizados.

2. Nesta guia, há cinco (5) espaços disponíveis para configurar métodos de pagamento em dinheiro. Neste exemplo, configuraremos o OXXO, um método de pagamento em dinheiro do México.
   Clique em qualquer caixa disponível na seção Promissórias.

3. Forneça as seguintes informações:

• Nome: Use o valor listado aqui na coluna parâmetro paymentMethod. Para este exemplo, insira OXXO.
  • Descrição: Insira uma descrição para exibição quando o cliente selecionar esse método de pagamento (opcional).
  • Data de Expiração da Nota Promissória: Especifique o número de dias antes do vencimento do pagamento em dinheiro. O padrão é 7 dias. Certifique-se de que esse valor corresponde à configuração Expiração do Pagamento (dias) configurada na afiliação da VTEX para evitar problemas de processamento.

Deixe os demais campos com seus valores padrão.

4. Clique em Salvar. Depois que o pagamento personalizado for criado, você será redirecionado para configurar uma nova Condição de Pagamento. Siga as instruções na seção Configurando Cartões de Crédito ou Débito.

Configurando PSE

Pré-requisitos:

• Este método de pagamento está disponível apenas para lojistas que processam pagamentos na Colômbia.
• Para oferecer PSE como método de pagamento, você deve instalar o Aplicativo PSE desenvolvido pela VTEX. Se ainda não o fez, acesse Configurações da Conta > Aplicações > App Store e procure por Bancos para PSE.
  Se o aplicativo não estiver disponível na loja, você pode solicitar sua instalação à equipe da VTEX enviando um ticket para o Suporte VTEX.
• Se você estiver utilizando uma integração VTEX Legacy, a VTEX precisará realizar uma configuração adicional antes que você possa configurar este método de pagamento. Entre em contato com seu representante VTEX ou solicite assistência via Suporte VTEX.

1. Para configurar o PSE, acesse o painel de administração da VTEX e vá até Configurações da Loja > Pagamentos > Configurações > Condições de Pagamento. Em seguida, siga estas etapas:

  1.1 Clique no botão +.

  1.2 Na categoria Outros, localize PSE.

  1.3 Preencha os seguintes campos:

    • Nome da Regra: Insira um nome descritivo para identificar este método de pagamento.
    • Processar com Afiliação: Selecione a afiliação do gateway configurada para processar pagamentos com PayUV2.
    • Status: Ative a condição de pagamento.

  1.4 Clique em Salvar para aplicar as configurações.

2. Configure o aplicativo Bancos para PSE com suas credenciais da PayU seguindo estas etapas:

  2.1 Faça login no painel de administração da VTEX e vá até Apps > Aplicativos Instalados > Banks for PSE.

  2.2 Preencha o formulário e clique em Salvar.

• Após concluir a configuração, você poderá processar transações em ambiente de produção com PSE.

Testando a Integração

Depois de configurar as condições de pagamento para seus métodos de pagamento, é altamente recomendável testar sua integração antes de processar transações reais.

Pré-requisitos para Testes Bem-sucedidos:

• Certifique-se de que sua conta PayU Enterprise está no modo TEST.
• Verifique se o Seletor de Ambiente em sua Afiliação ao Gateway VTEX está definido como TEST.
• Utilize as credenciais de teste apropriadas ao configurar a Afiliação ao Gateway VTEX. Você pode encontrar as credenciais de teste aqui.
• Após concluir seus testes, atualize a configuração com as informações de produção, incluindo sua conta PayU Enterprise, o seletor de ambiente na afiliação VTEX e as credenciais.

Passos para Realizar uma Transação de Teste

1. No painel administrativo da VTEX, clique em VISITAR LOJA no menu superior.

   

2. A loja configurada para sua conta VTEX será aberta. Selecione qualquer produto e prossiga com a compra.

   

3. No carrinho de compras, clique no botão Fechar Pedido.

   

4. Na seção de pagamento, os métodos de pagamento disponíveis aparecem agrupados por tipo. Selecione o método que deseja testar e insira os dados de teste. Você pode encontrar números de cartões de teste e informações relevantes aqui.
   Por fim, clique em Finalizar Compra.

   

Verificando a Transação

Depois que a compra for aprovada, você pode verificar a transação nos seguintes locais:

• Admin VTEX: Navegue até Pagamentos > Transações.

  

• Painel PayU Enterprise: Vá para Pagamentos > Buscar.

  

  Nota

  O parâmetro ID da Transação Externa dentro da Atividade da Transação corresponde ao ID do Pedido na PayU.

• Painel de Gestão PayU: Verifique a transação no módulo Relatório de Vendas.

  

• API de Consultas: Use o ID da Transação Externa como parâmetro OrderID.

Testando Fluxos de Duas Etapas

Se sua Afiliação ao Gateway estiver configurada para processar transações usando um fluxo de duas etapas, os fundos autorizados no cartão de crédito não serão liquidados até que você solicite explicitamente a liquidação. Para concluir a liquidação, você deve faturar o pedido.

Passos para Faturar um Pedido

1. Localize a transação no Admin VTEX, em Pagamentos > Transações, e clique nela.
   Em seguida, clique no botão Pedido no canto superior direito.

   

2. Role até a seção Pacote e clique em Faturar Pacote.

   

3. Insira os detalhes da fatura e clique em Enviar Fatura.
   Assim que a fatura for enviada ao cliente, o valor autorizado será cobrado do cartão do cliente.