Configure o Yuno como provedor

Para oferecer mais métodos de pagamento aos seus clientes usando o Yuno como provedor, você precisa seguir as etapas abaixo para conectar sua conta VTEX ao Yuno e configurar os métodos de pagamento que deseja oferecer.

1. Faça login em sua conta da loja VTEX.

2. No painel de controle do VTEX Admin, navegue até Store Settings > Providers e clique em New Provider.

3. Pesquise Yuno na caixa de diálogo e selecione a opção Yuno nos resultados.

4. Preencha o formulário com as informações necessárias. A seguir, você encontrará uma descrição para cada campo que precisa ser preenchido:

📘

Campos da conta de franquia

Preencha os campos "Conta principal..." somente se o seu ambiente VTEX usar o modelo de franquia. Para contas Standard ou Seller Portal, deixe-os em branco.

🚧

Aviso do modo de teste

A VTEX recomenda que você não ative o modo de teste em ambientes de produção, pois as opções de pagamento de teste estarão disponíveis para os clientes em sua loja.

❗️

Aviso de liquidação automática

Há um problema conhecido que afeta a opção Agendada: Agendar a captura automática. Você pode encontrar mais detalhes aqui.

Antes de executar a atualização (PUT), a afiliação primeiro faz um GET para recuperar a configuração atual.

5. Depois de preencher todos os campos, clique em Save (Salvar).
6. Navegue até Store Settings > Settings e clique no botão + (botão verde no canto superior direito) para adicionar uma nova opção de pagamento.

7. Selecione o método de pagamento que você deseja fornecer ao seu cliente. Você precisa configurar o provedor para cada método de pagamento que deseja disponibilizar, incluindo marcas de cartão (Visa, Mastercard, etc.), métodos de pagamento alternativos (PIX, Boleto, Mercado Pago Wallet, etc.) e outros tipos de pagamento.

8. Depois de selecionar o método de pagamento, uma nova caixa de diálogo é exibida, na qual você precisa configurar o provedor de pagamento:
   1. Em Process with provider, selecione Yuno.
   2. Adicione condições especiais, se necessário. Para obter informações adicionais sobre a configuração das condições especiais, acesse Configurando condições especiais de pagamento. Para obter mais informações sobre a configuração das condições de pagamento considerando parcelas com ou sem juros, consulte a página VTEX.
   3. Clique em Salvar.
   4. Altere o status para Ativo.

📘

Adição de vários métodos de pagamento

Se quiser adicionar mais de um método de pagamento para oferecer aos seus clientes, você precisará repetir as etapas 7 e 8 para cada método de pagamento. Por exemplo:

• Para oferecer Visa e Mastercard, repita as etapas 7 e 8 duas vezes, uma para Visa e outra para Mastercard.
• Para oferecer cartões e métodos de pagamento alternativos, como Mercado Pago Wallet ou PIX, configure cada método de pagamento separadamente.

9. Como última etapa, você deve configurar o URL do webhook para receber as atualizações dos pagamentos.
   1. Acesse o Yuno Dashboard e selecione Developers.
   2. Selecione a guia Webhooks.
   3. Clique em adicionar webhook. O formulário do webhook será exibido, no qual você deverá fornecer as seguintes informações:
      1. Nome: Defina um nome para o webhook VTEX.
      2. URL Endpoint: Você deve informar o seguinte URL https://{store_name}.myvtex.com/_v/yunopartnerbr.yuno/v4/webhook (substituir {store_name} com o nome real de sua loja).
      3. x-api-key e x-secret: você pode definir qualquer informação aqui. Por exemplo, você pode adicionar VTEX para ambos os campos.
   4. Em Trigger on, marque todos os eventos que devem notificá-lo por meio dos webhooks. A Yuno recomenda marcar todas as opções.
   5. Clique em Add.

Gerenciamento de vencimento de pagamentos PIX

Ao configurar pagamentos PIX com a VTEX, a Yuno oferece tratamento automático de vencimento para evitar problemas de reconciliação de pedidos:

• Rastreamento de expiração personalizado (nível de conexão): A Yuno monitora a expiração do pagamento do PIX com base no expiration_date definidos na conexão VTEX-Yuno, sem depender exclusivamente dos webhooks do provedor
• Verificação proativa: Antes do vencimento, a Yuno faz uma solicitação ao provedor para confirmar se o pagamento foi concluído
• Cancelamento automático de pedidos: Se um código QR PIX expirar sem ser pago, o Yuno marca o pagamento como expirado e notifica imediatamente a VTEX via webhook para que o pedido possa ser cancelado automaticamente
• Consistência de reconciliação: Isso garante que os status de pagamento permaneçam sincronizados entre a VTEX, a Yuno e o provedor de pagamento

Esse recurso é particularmente útil para evitar que a VTEX continue a tentar novamente pagamentos de PIX expirados, eliminando incompatibilidades de status e reduzindo a sobrecarga de reconciliação.

📘

Importante

Para integrações VTEX, o expiration_date é configurado no nível de conexão no Yuno. Esse tratamento aprimorado da expiração só se aplica quando um tempo de expiração personalizado é definido na conexão, e não quando se usa a expiração padrão do provedor.

Depois de concluir as etapas acima, seus clientes podem acessar um novo método de pagamento no checkout. Por exemplo, se você configurar o Visa, quando seus clientes selecionarem o cartão de crédito no checkout, o checkout do Yuno reunirá todas as informações necessárias para a triagem de fraude e os serviços 3DS em segundo plano enquanto usa o formulário de cartão de crédito da VTEX.

Depois de começar a receber pagamentos na VTEX com o Yuno, você poderá ver todas as informações relacionadas às transações em seu painel do Yuno como um pagamento regular.

• Como informação adicional nos detalhes do pagamento, especialmente dentro da estrutura de metadados, você também poderá identificar a conta VTEX relacionada à criação do pagamento.

  JSON

  "metadata": [
      {
        "key": "vtex_account",
        "value": "[your_vtex_subaccount]"
      }
    ]

• Quando um cliente tenta fazer vários pagamentos e esses pagamentos são recusados, a VTEX ativa Modo de defesa. Durante esse período, a VTEX não executa nosso aplicativo de pagamento, o que significa que os recursos de detecção de fraude do Yuno estão desativados. O processo de pagamento é atrasado pela VTEX e encaminhado para o conector PPF da Yuno. Uma vez recebido, o conector Yuno PPF enviará o pagamento junto com os metadados defense_mode=true.

  A Yuno recomenda a configuração de uma rota que ignore a validação de fraude sempre que o defense_mode Os metadados são definidos como true.

  JSON

  "metadata": [
    {
      "key": "defense_mode",
      "value": "[true/false]"
    }
  ]

• O conector VTEX captura o sellerId (Código de afiliado) dos pedidos da VTEX e o inclui na sessão de checkout e nos metadados de pagamento. Isso possibilita o rastreamento do marketplace e a funcionalidade do modo afiliado, permitindo que os comerciantes rastreiem a atribuição entre suas próprias lojas e os marketplaces parceiros.

  JSON

  "metadata": [
    {
      "key": "sellerId",
      "value": "[affiliate_code_from_vtex_order]"
    }
  ]

  Para obter mais informações sobre o modo VTEX Affiliate, consulte a documentação da VTEX sobre a configuração de afiliados.

Criação automática de clientes para o Click to Pay

Quando os clientes optam por pagar via Click to Pay em comerciantes VTEX, o conector VTEX cria automaticamente o registro de cliente VTEX correspondente no Yuno durante a inicialização do fluxo de checkout. Isso garante uma experiência de pagamento simplificada, eliminando a entrada de dados redundantes.

Como funciona:

• Criação automática: Quando um comprador inicia uma transação Click to Pay, o cliente VTEX é criado automaticamente no Yuno, caso ainda não exista
• Mapeamento de dados: Todos os dados do cliente disponíveis no perfil VTEX são automaticamente mapeados para o Yuno e incluídos na sessão de checkout
• Campos pré-preenchidos: O SDK preenche automaticamente as informações do cliente (CVV, email, endereço) a partir do perfil da VTEX, eliminando a necessidade de os clientes inserirem essas informações novamente
• Melhoria da experiência do usuário: O fluxo Click to Pay corresponde à experiência simplificada para comerciantes que não são da VTEX, sem etapas de entrada desnecessárias

Esse recurso requer que o campo Criar cliente seja definido como Sim na configuração do provedor VTEX (consulte a etapa 4 no processo de configuração acima).

📘

Importante

A criação automática de clientes só se aplica quando se usa o Click to Pay como método de pagamento. Para outros métodos de pagamento, a criação de clientes segue o fluxo padrão com base na definição de configuração "Criar cliente".

Personalizações

Se você quiser adicionar ou alterar determinados aspectos de experiência do usuário no checkout, a VTEX permite que os comerciantes modifiquem alguns aspectos:

• Personalizações da página de checkout
• Altere os nomes dos métodos de pagamento no Checkout.

Opções disponíveis

Para obter mais informações sobre o recurso de captura automática personalizada, consulte a documentação da VTEX.

Mapeamentos de campos ClearSale

Ao usar a detecção de fraudes da ClearSale com o conector VTEX, o Yuno mapeia automaticamente os dados dos pedidos da VTEX para os campos obrigatórios da ClearSale. Isso garante que todas as informações necessárias sejam corretamente transmitidas à ClearSale para análise de fraudes.

Mapeamento do tipo de entrega

O deliveryType O campo das encomendas VTEX é automaticamente extraído e mapeado para a ClearSale. Este campo é obrigatório para os comerciantes que utilizam o produto Garantia de Estorno da ClearSale.

Mapeamento da VTEX para a ClearSale:

O conector VTEX extrai o deliveryType valor dos registros de pedidos da VTEX (disponível em AdditionalData.Order.Shipping.Type) e o mapeia corretamente para o ClearSale. Os valores comuns do tipo de entrega incluem:

• Normal → Mapeado como NORMAL
• ECONOMY → Mapeado como ECONOMY
• Outros tipos de entrega são mapeados de acordo com os requisitos de campo da ClearSale.

O tipo de entrega é automaticamente incluído na carga útil enviada para a ClearSale, garantindo a conformidade com os requisitos de campos obrigatórios da ClearSale para produtos com Garantia de Estorno.

📘

Integração ClearSale

Para comerciantes que utilizam o produto Garantia de Estorno da ClearSale, o deliveryType O campo é obrigatório. O conector VTEX garante que este campo seja extraído corretamente dos pedidos VTEX e formatado adequadamente para o ClearSale.