VTEX

Este artigo mostra o procedimento para habilitar o PayU em seu site VTEX.

A VTEX é uma plataforma de comércio digital que permite criar rapidamente uma loja online com recursos prontos para uso. Para obter mais informações, consulte o site oficial da VTEX.

Pré-requisitos

  • Você precisa de uma conta PayU Latam ativa.
  • Você precisa de uma conta ativa do PaymentsOS. Se você não tiver uma conta, clique aqui para criar uma.
    Todos os comerciantes que precisam integrar o PayU com a VTEX devem ter uma conta PaymentsOS no modo produtivo/live.
  • Você precisa de uma conta VTEX com direitos e permissões suficientes para acessar o painel administrativo da VTEX. Esta conta deve ter a autenticação de dois fatores habilitada.

Procedimento de configuração

O procedimento para habilitar os meios de pagamento que processamos em nossa plataforma na VTEX é dividido em duas etapas. Antes de continuar, certifique-se de atender aos pré-requisitos acima.

1. Configure sua conta do PaymentsOS

A integração da PayU Latam com a VTEX é feita utilizando PaymentsOS como middleware. Como primeiro passo, você precisa configurar os seguintes objetos em sua conta do PaymentsOS.

  • Uma configuração de provedor.
  • Uma Unidade de Negócios.
  • Um WebHook.

Você pode configurar esses objetos usando uma das seguintes opções:

Configurar 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 para o Postman (pode ser necessário atualizar a página se o botão não funcionar).


  1. Depois de executar a coleção, você precisa definir os globais. Baixe o arquivo global aqui.

  2. Na coleção Postman, clique em Import ao lado do nome da área de trabalho e localize o arquivo json baixado anteriormente.

  3. Ao terminar, clique em Import.

  4. É obrigatório executar os métodos de coleta na ordem apresentada. Primeiro, clique no método POST chamado 1. Login e abra a guia Body.

PrintScreen

  1. Digite o e-mail (email) e a senha (password) da sua conta do PaymentsOS. Em seguida, clique em Send.

  2. Se o login for bem-sucedido, os dados de autenticação são atribuídos no segundo método.
    Clique no método GET chamado 2. Retrieve PayU Latam ID.

  3. No canto superior direito, clique no ícone de olho e localize o parâmetro env. Em seguida, clique no ícone de lápis e digite test se estiver processando no ambiente de teste, ou live caso contrário.

PrintScreen

  1. Uma vez configurado, clique em Send.

  2. Clique no método POST chamado 3. Create Provider Configuration, este método cria o Configuração de Provedor no PaymentsOS. Em seguida, vá para a guia Body.

PrintScreen

Insira as seguintes informações:

Parâmetro Descrição
name Insira um nome para a Configuração do Provedor.
description Insira uma descrição significativa para a Configuração de Provedor.
Este valor é opcional.
apiLogin Usuário ou login fornecido pelo PayU. Como faço para obter minha API Login
apiKey Senha fornecida pelo PayU. Como faço para obter minha API key
configuration_data.accountId ID da conta PayU de acordo com o país em que você vai vender.
configuration_data.merchantId ID do seu negócio na PayU Latam.
configuration_data.partnerID Identificador PayU. Insira ZOOZ_VTEX_V2 como o valor.
configuration_data.cashRedirect Envie True para garantir o fluxo correto de encomendas com métodos de pagamento em dinheiro na VTEX.
Nota: Esta configuração é importante para todos os comerciantes que processam pagamentos em dinheiro com a VTEX.
  1. Clique no método POST chamado 4. Create Business Unit, este método cria a Unidade de Negócios no PaymentsOS. Em seguida, vá para a guia Body.

PrintScreen

Insira as seguintes informações:

Parâmetro Descrição
id Identificador da Unidade de Negócios. Este id deve estar em letras minúsculas e sem espaços.
Certifique-se de ter inserido o valor correto para o id, pois este valor não pode ser atualizado posteriormente.
description Insira uma descrição significativa para a Unidade de Negócios.
Esse valor é opcional.
  1. Clique no método POST chamado 5. Create Webhook, este método cria o WebHook no PaymentsOS. Este WebHook é a URL de confirmação que receberá as notificações enviadas pela VTEX quando uma transação mudar de estado.
    A seguir, vá para a guia Body.

PrintScreen

Defina o parâmetro endpoint com os seguintes valores de acordo com seu ambiente.

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

Deixe os outros valores com seu valor padrão.

Neste ponto, você configurou sua conta do PaymentsOS como middleware, o próximo passo é a configuração do provedor VTEX.

Configure a conta manualmente usando o Painel de controle do PaymentsOS

Siga estas etapas para configurar sua conta usando o painel de controle do PaymentsOS.

  1. Crie a Configuração de Provedor.
    No painel de controle do PaymentsOS, expanda o menu Configuração e selecione Provedores de Pagamento.

PrintScreen

Use o campo Buscar na seção Criar uma nova configuração de Provedor e digite PayU para encontrar o provedor PayU Latam.

PrintScreen

Insira as seguintes informações para a Configuração de Provedor:

Parâmetro Descrição
Configurar Nome Insira um nome para a Configuração do Provedor.
Descrição Insira uma descrição significativa para a Configuração de Provedor.
Este valor é opcional.
apiLogin Usuário ou login fornecido pelo PayU. Como faço para obter minha API Login
apiKey Senha fornecida pelo PayU. Como faço para obter minha API key
accountId ID da conta PayU de acordo com o país em que você vai vender.
merchantId ID do seu negócio na PayU Latam.
paymentCountry País de processamento no formato ISO 3166 Alpha-3.
cashRedirect Seleccione True para garantir o fluxo correto de encomendas com métodos de pagamento em dinheiro na VTEX.
Nota: Esta configuração é importante para todos os comerciantes que processam pagamentos em dinheiro com a VTEX.

Quando terminar, clique em Salvar.

PrintScreen

  1. Crie a Unidade de Negócios.
    No painel do PaymentsOS, expanda o menu Configuração e selecione Unidades de Negócios.

PrintScreen

Clique no botão Criar uma Unidade de Negócios e insira as seguintes informações:

Parâmetro Descrição
Nome da Unidade de Negócios Nome da Unidade de Negócios. Este id deve estar em letras minúsculas e sem espaços.
Certifique-se de ter inserido o valor correto para o id, pois este valor não pode ser atualizado posteriormente.
Descrição Insira uma descrição significativa para a Unidade de Negócios.
Esse valor é opcional.

Na seção Escolha um Provedor padrão para esta Unidade de Negócios, escolha a Configuração do Provedor criada na etapa anterior.
Ao terminar, clique em Salvar.

PrintScreen

  1. Crie o webhook. Este WebHook é a URL de confirmação que receberá as notificações enviadas pela VTEX quando uma transação mudar de status.

De volta ao painel do PaymentsOS, expanda o menu Configuração e selecione Webhooks.

PrintScreen

Clique no botão Criar Endpoint para Webhook e insira a URL de acordo com seu ambiente:

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

Na tabela Payment Events Alert, acione o evento Update para Authorization e Charge. Além disso, selecione no combo Unidades de Negócios Associadas a Unidade de Negócios criada na etapa anterior.
Ao terminar, clique em Criar.

PrintScreen

Neste ponto, você configurou sua conta do PaymentsOS como middleware, o próximo passo é a Configuração do provedor VTEX.

2. Configuração do provedor VTEX

Depois de configurar sua conta PaymentsOS, o próximo passo é a configuração do provedor VTEX para cada forma de pagamento. Para esta etapa, é obrigatório que você tenha um usuário válido para acessar o VTEX admin.

Configurar la afiliación de Gateway

Antes de configurar a Afiliação de Gateway, certifique-se de ter configurado o FingerPrint para PayU. Para isso, veja este artigo.

  1. No VTEX admin, expanda o menu Pagamentos dentro do grupo Transações. Em seguida, selecione Configurações.

PrintScreen

  1. Antes de configurar as Condições de pagamento, você deve criar um novo provedor. No painel esquerdo, selecione Configurações da Loja > Provedores > Novo provedor:

PrintScreen

  1. Localize PayU e selecione PayUv2:

PrintScreen

  1. Nas configurações do conector, você precisa instalá-lo clicando no botão Instalar app. Em seguida, insira as seguintes informações.

PrintScreen

Campo Descrição
Nome da afiliação Nome que você deseja atribuir para identificar a Afiliação de Gateway.
Seletor de Ambiente Selecione o ambiente onde deseja criar as transações.
De acordo com a seleção que fizer aqui, você deve inserir outros parâmetros selecionando o mesmo ambiente no PaymentsOS.
Application Key ID do aplicativo da Unidade de Negócios.
Application Token Chave de API privada da Unidade de Negócios.
Captura automática de pagamento Selecione como deseja fazer a captura (pagamento) em sua afiliação.
  • Para fluxos de uma etapa, selecione Inmediatamente: captura automática al autorizar el pago.
  • Para fluxos de duas etapas, selecione Desactivado: no capturado automáticamente para executar a captura assim que você faturar o pedido.
  • Selecione Agendada: Defina quando a captura automática será realizada para definir um tempo em horas para capturar automaticamente o pedido.

Para obter mais informações, consulte Recurso de captura automática personalizada na documentação do desenvolvedor.
O valor padrão de esta opção é de sete (7) dias após a aprovação.
Prazo agendado em horas para a captura automática Este campo aparece quando você seleciona Agendada: Defina quando a captura automática será realizada como forma de captura de pagamento; selecione o período programado que deseja configurar de acordo com suas configurações. Este valor deve ser um número inteiro, portanto, decimais não são permitidos.
Tipo Autorizacion Selecione se suas transações de pagamento são executadas em fluxos de uma ou duas etapas.
  • Para fluxos de uma etapa, selecione Autorizacion y Captura.
  • Para fluxos de duas etapas, selecione Pre-Autorizacion.

Consulte o seguinte link para saber mais sobre fluxos de pagamento.
Public Key Chave de API pública da Unidade de negócios.
Idioma Selecione o idioma em que deseja que o sistema emita as encomendas, os idiomas suportados são:
  • Espanhol
  • Inglês
  • Português
Expiración pago (días) Refere-se ao número de dias que você deseja personalizar para pagamentos em dinheiro.
Importante: Este valor deve corresponder ao valor configurado no método de pagamento no campo Validade da nota promissória explicado na seção Configurar o meio de pagamento em dinheiro desta documentação.
Ativar split e enviar recebedores? Selecione Não neste campo.

Quando terminar, clique em Salvar.

Configurar métodos de pagamento

Defina os métodos de pagamento a serem exibidos no site para pagamento. Veja nossos métodos de pagamento disponíveis.

Configurar cartões de débito ou crédito

De acordo com seu país de processamento, você pode configurar a afiliação que criou para usar cartões de crédito ou débito* . Siga estas instruções para adicionar esta forma de pagamento à sua loja VTEX.

* O uso de cartões de débito depende do seu país de processamento.

  1. Na opção Configuração (Transações > Pagamentos > Configurações), selecione a guia Condições de pagamento e clique no ícone de adição.

PrintScreen

  1. Selecione o método de pagamento que deseja incluir. Os métodos de pagamento são agrupados por tipo.
    Para nosso exemplo, selecionamos American Express na seção Cartão de crédito.

PrintScreen

  1. Insira as seguintes informações.
  • Nome da Regra (para fácil identificação): insira um nome significativo para a condição de pagamento ao lado do método de pagamento selecionada.
  • Status: selecione o status da condição de pagamento. Você só pode ter uma condição de pagamento ativa por método de pagamento.
  • Processar com a afiliação: selecione a afiliação do gateway configurada anteriormente.
  • À vista ou parcelado?: selecione À vista*.

PrintScreen

  1. Clique em Salvar. Quando você cria a condição de pagamento, ela é listada na guia Condições de pagamento.

PrintScreen

Configurar cartões co-branded ou bandeira própria

Os cartões co-branded ou bandeira própria são cartões emitidos por uma loja ou marca em associação com uma rede como AMEX, VISA, MasterCard, etc. Siga estas instruções para adicionar esta forma de pagamento à sua loja VTEX.

  1. Na opção Configuração (Transações > Pagamentos > Configurações), selecione a guia Pagamentos customizados.

PrintScreen

  1. Nesta guia, você tem cinco (5) slots disponíveis para configurar cartões co-branded e bandeira própria. Neste exemplo, vamos configurar o cartão Colombian Codensa que é um cartão bandeira própria.
    Clique em qualquer uma das caixas disponíveis na seção CCartões da Loja (Bandeira Própria).

PrintScreen

  1. Insira as seguintes informações usando as letras maiúsculas e minúsculas mostradas.
  • Nome: Codensa.
  • Descrição: Codensa
  • Faixas de Bin: 590712-590712
  • Código de pagamento do adquirente: codensa

PrintScreen

Os valores restantes podem ser deixados como padrão. Use os seguintes valores para configurar cartões de marca compartilhada e de marca privada.

País Nome Descrição Faixas 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 informações sobre como configurar co-branded e bandeira própria, consulte a central de ajuda da VTEX.

  1. Clique em Salvar. Assim que o pagamento customizado for criado, você será redirecionado para a opção de criar um novo Condições de pagamento. Esta condição de pagamento é criada conforme explicado na seção Configurar cartões de crédito ou débito.
Configurar métodos de pagamento em dinheiro

Como as formas de pagamento à vista exigem que o cliente pague em escritórios físicos, você pode configurar essa forma de pagamento na VTEX como Notas Promissórias.

Ao configurar uma forma de pagamento em dinheiro, seus clientes são redirecionados para o checkout PayU para baixar o comprovante de pagamento e pagar no respectivo escritório físico. Siga as instruções abaixo para adicionar esta forma de pagamento à sua loja VTEX.

  1. Na opção Configuração (Transações > Pagamentos > Configurações), selecione a guia Pagamentos customizados.

PrintScreen

  1. Nesta guia, você tem cinco (5) slots disponíveis para configurar pagamentos em dinheiro. Neste exemplo, vamos configurar o OXXO, um método mexicano de pagamento em dinheiro.
    Clique em qualquer uma das caixas disponíveis na seção Promissórias.

PrintScreen

  1. Insira as seguintes informações para o método de pagamento em dinheiro.
  • Nome: neste parâmetro, você precisa usar o valor mostrado aqui na coluna Parâmetro paymentMethod. Para este exemplo, definimos OXXO.
  • Descrição: Insira a descrição que deseja exibir quando o cliente selecionar esta forma de pagamento. Este parâmetro é opcional.
  • Validade da promissória: Informe o número de dias antes do vencimento do pagamento em dinheiro. Por padrão, esse valor é atribuído a 7 dias. Tenha em mente que, para evitar problemas de processamento, este valor deve corresponder ao valor selecionado no campo Expiración pago (días) que você configurou na afiliação VTEX.

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

  1. Clique em Salvar. Assim que o pagamento customizado for criado, você será redirecionado para a opção de criar um novo Condições de pagamento. Esta condição de pagamento é criada conforme explicado na seção Configurar cartões de crédito ou débito.
Configure o PSE

Pré-requisitos:

  • Este método de pagamento se aplica apenas a comerciantes que processam transações na Colômbia.
  • Para oferecer o PSE como método de pagamento, primeiro certifique-se de instalar o aplicativo PSE desenvolvido pela VTEX. Se ainda não o fez, vá para Definições de conta > Aplicações > App Store e procure por Banks for PSE.
    Caso não encontre o aplicativo na loja, você pode solicitar sua instalação à equipe da VTEX por meio de um chamado no Suporte VTEX.
  • No caso de você ter uma integração legada da VTEX, observe que a VTEX deve realizar uma configuração adicional para que você possa configurar o método de pagamento. Entre em contato com seu agente VTEX ou solicite ajuda por meio do Suporte VTEX.
  1. Para configurar o PSE, acesse o painel de administração da sua plataforma VTEX e vá para Configurações da Loja > Pagamentos > Configurações > Condições de pagamento. Em seguida, siga estas etapas:
  • Clique no botão +.
  • Na categoria Outros, localize o PSE.
  • Preencha os campos exibidos na tela:
    • Insira um nome descritivo para a regra para identificar este método de pagamento.
    • Escolha a afiliação configurada para processar pagamentos com PayUV2 no menu suspenso Process with affiliation.
    • Ative a condição de pagamento no campo Status.
    • Clique em Salvar para aplicar as configurações.


  1. Configure o aplicativo Banks for PSE com suas credenciais PayU. Para isso, siga estas etapas:
  • Inicie sessão no painel de administração da sua plataforma VTEX e acesse Aplicações > Aplicações instaladas > Banks for PSE.
  • Preencha o formulário e clique em Salvar.
Campo Descrição
Connector Used to process the PSE: Selecione PayUv2 no menu suspenso.
Application Code Chave da API Privada da Unidade de Negócios. Lembre-se de que esses dados podem ser encontrados no Painel de Controle da PaymentsOS conforme explicado acima.
Nota: Este campo é equivalente ao Token de aplicação da afiliação VTEX.
Application Key ID da de aplicação da Unidade de Negócios.Lembre-se de que esses dados podem ser encontrados no Painel de Controle da PaymentsOS conforme explicado acima.
Nota: Este campo é equivalente à Chave de aplicação da afiliação VTEX.
  • Depois de concluir a configuração, você pode realizar transações em um ambiente produtivo com o PSE.

PrintScreen

Teste a integração

Depois de configurar as Condições de pagamento para seus métodos de pagamento, é recomendável testar a integração antes de começar a receber transações reais.

Pré-requisitos para testes bem-sucedidos:

  • Verifique se sua conta PaymentsOS está no modo TEST.
  • Verifique se o Seletor de Ambiente em sua Afiliação do Gateway VTEX está no modo TEST.
  • Certifique-se de usar as credenciais apropriadas para o ambiente de teste ao configurar a Afiliação do Gateway VTEX. Lembre-se de que você pode encontrar as credenciais de teste aqui.
  • Lembre-se de que, uma vez concluídos os seus testes, você deve modificar os pontos acima com as informações de produção (conta PaymentsOS, seletor de ambiente na afiliação VTEX e credenciais configuradas na afiliação VTEX).
  1. No VTEX admin, clique em VISIT A LOJA no painel superior.

PrintScreen

  1. A loja configurada para sua conta VTEX é aberta. Selecione qualquer produto e clique em comprar.

PrintScreen

  1. No carrinho de compras, clique no botão fechar pedido.

PrintScreen

  1. Na seção de pagamento, aparecem os meios de pagamento agrupados por tipo. Selecione aquele que você deseja testar e insira os dados do teste. Encontre aqui alguns números de cartões de teste e informações para testar os status.
    Finalmente, clique em Finalizar .

PrintScreen

Assim que a compra for aprovada, você poderá verificá-la em:

  • VTEX admin: Pagamentos > Transações.

PrintScreen

  • Painel de controle de PaymentsOS: Pagamentos > Buscar.

    PrintScreen
    O parâmetro ID de Transação Externa dentro de Atividade de Transação é o OrderID da PayU.

  • Módulo PayU: no Relatório de Vendas.

PrintScreen

  • Query API usando o parâmetro ID de Transação Externa como OrderID.

Probar flujos de dos pasos

Quando você configura sua Afiliação do Gatewa para processar transações em fluxos de duas etapas, os fundos autorizados do cartão de crédito não são capturados até que você solicite explicitamente a captura. Para solicitar a captura, você precisa faturar o pedido.

Para faturar um pedido, localize a transação no VTEX Admin (Pagamentos > Transações) e clique sobre ela. Em seguida, clique no botão Pedido no canto superior direito.

PrintScreen

Role para baixo até a seção Pacote e clique em Faturar pacote.

PrintScreen

Forneça as informações da sua fatura e clique em Enviar Nota na parte inferior do painel. Após o envio da fatura ao cliente, o valor autorizado é debitado no cartão do cliente.

PrintScreen

Última modificação 26 de fevereiro de 2024: VTEX updates (18bff8dde)