Guia de integração do VTEX Headless

Integre o Yuno SDK Web for VTEX Headless para lidar com pagamentos on-line de forma eficiente. Este guia aborda as etapas de instalação, configuração e implementação.

Integração com VTEXIO

Para usar o Yuno no checkout da VTEXIO, instale os seguintes aplicativos:

yunopartnerbr.yuno: Um conector VTEXIO PPF que facilita a integração entre a VTEX e a infraestrutura de pagamento da Yuno.
yunopartnerbr.yuno-app: É necessário um aplicativo de pagamento front-end da VTEXIO ao usar Cartão ou Click to Pay como método de pagamento. Não é necessário para Pix, Boleto e outros métodos de pagamento baseados em redirecionamento. yunopartnerbr.yuno-app possui os seguintes recursos principais:
- Executa o Yuno Web SDK para coletar dados do navegador.
- Executa SDKs de detecção de fraude de terceiros.
- Processa pagamentos diretamente no Yuno.
- Suporta pagamentos com dois cartões de crédito.

Instalação

Para integrar o Yuno à VTEX, é necessário instalar dois aplicativos:

yunopartnerbr.yuno: Conector VTEX PPF para comunicação de back-end.
yunopartnerbr.yuno-app: Aplicativo de pagamento front-end necessário para pagamentos baseados em cartão.

🚧
Permissões de administrador necessárias
Para instalar os dois aplicativos, você precisa de permissões de administrador na VTEX.

Instalar `yunopartnerbr.yuno`

Siga estas etapas para instalar yunopartnerbr.yuno em Administrador da VTEX:

Faça login em sua conta da loja VTEX.
No painel de controle do VTEX Admin, navegue até Store Settings > Providers e clique em New Provider.
Procure a Yuno na lista de provedores disponíveis.
Clique em Install (Instalar ) e siga as instruções de configuração.

Para obter mais detalhes, consulte a página Configurar Yuno como provedor.

Instalar `yunopartnerbr.yuno-app`

yunopartnerbr.yuno-app é necessário para pagamentos com cartão ou Click to Pay. Para instalá-lo, siga as etapas:

No VTEX Admin, vá para Apps > App Management.
Procurar por Yuno.
Localize e selecione o aplicativo de pagamento Yuno (a segunda opção na lista).
Clique em Install (Instalar ) para concluir a configuração.

Instale o Yuno SDK Web para VTEX (opcional)

Se seu projeto exigir Yuno SDK Web VTEX, instale-o usando npm:

npm install @yuno-payments/sdk-web-vtex

Esse pacote simplifica a integração do SDK Web VTEX e inclui suporte a TypeScript.

Para usar o SDK, importe-o e initialize :

import { loadScript } from '@yuno-payments/sdk-web-vtex'

...

const yunoVTEX = await loadScript()

yunoVTEX.mount({...})

Para obter mais informações, acesse @yuno-payments/sdk-web-vtex.

Fluxos de pagamento

As seções a seguir ilustram como os pagamentos são processados na VTEXIO e no VTEX Headless usando diferentes métodos de pagamento:

Fluxo de pagamento com cartão de crédito na VTEXIO
Fluxo de pagamento do Pix (APMs) na VTEXIO
Fluxo de pagamento headless da VTEX

Fluxos de pagamento VTEXIO

A VTEXIO permite o processamento contínuo de pagamentos por vários métodos, incluindo cartões de crédito e métodos de pagamento alternativos (APMs) como o Pix. Veja abaixo um detalhamento passo a passo de como esses fluxos de pagamento funcionam.

Fluxo de pagamento com cartão de crédito na VTEXIO

Esse fluxo detalha como os pagamentos com cartão de crédito são processados na VTEXIO, desde a interação do usuário até a conclusão da transação.

O usuário clica no botão de pagamento no frontend da VTEXIO.
O backend da VTEX envia as informações de pagamento para o yunopartnerbr.yuno conector.
O conector Yuno envia as informações do cartão de crédito para a API Yuno.
A API da Yuno retorna um token único para o pagamento.
O conector Yuno informa à VTEX que o aplicativo de pagamento deve ser aberto e fornece o token de uso único.
A VTEXIO abre o aplicativo de pagamento Yuno com os dados do conector Yuno.
O usuário insere os detalhes do cartão de crédito no aplicativo de pagamento Yuno.
Os detalhes do pagamento, as informações do navegador e os dados de detecção de fraude são enviados de volta ao conector Yuno.
O pagamento é criado na Yuno e processado.
O usuário recebe da VTEX a confirmação do status do pagamento.

Fluxo de pagamento Pix (APMs) na VTEXIO

Este fluxo explica como o Pix e outros APMs são tratados na VTEXIO, incluindo a criação e o redirecionamento de pagamentos.

O usuário clica no botão de pagamento no frontend da VTEXIO.
O backend da VTEX envia as informações de pagamento para o yunopartnerbr.yuno conector.
O conector da Yuno cria o pagamento no sistema da Yuno.
O Yuno gera um código QR e detalhes adicionais de pagamento e os devolve à VTEX.
A VTEXIO abre o aplicativo Pix ou redireciona o usuário para concluir o pagamento.

VTEX headless

Para usar o Yuno no checkout do VTEX Headless, instale:

yunopartnerbr.yuno: Um conector VTEXIO PPF que é executado no lado do servidor VTEXIO.

Além disso, o SDK Web VTEX deve ser implementado. Esse SDK suporta pagamentos com dois cartões de crédito.

Fluxo de pagamento headless da VTEX

O VTEX Headless requer uma abordagem diferente para o processamento de pagamentos. Abaixo estão as etapas para lidar com transações de cartão de crédito no VTEX Headless.

O usuário clica no botão de pagamento no frontend personalizado do comerciante.
O backend da VTEX envia as informações de pagamento para o yunopartnerbr.yuno conector.
O conector Yuno envia as informações do cartão de crédito para a API Yuno.
A API da Yuno retorna um token único para o pagamento.
O conector Yuno informa à VTEX que o aplicativo de pagamento deve ser aberto e fornece o token de uso único.
O front-end do comerciante abre o Yuno SDK Web VTEX usando os dados fornecidos.
Os detalhes do pagamento, as informações do navegador e os dados de detecção de fraude são enviados para o conector Yuno.
O conector Yuno processa o pagamento chamando a função{{merchant’s domain}}/_v/yunopartnerbr.yuno/v4/payments/yuno.
O usuário recebe da VTEX a confirmação do status do pagamento.

Instalando e usando o SDK Web VTEX

O Yuno SDK Web VTEX permite uma integração perfeita com a infraestrutura de pagamento da VTEX, possibilitando que os comerciantes lidem com pagamentos diretamente em seu front-end.

Para integrar o Yuno SDK Web for VTEX, inclua o script em seu arquivo HTML e configure os parâmetros necessários:

<!DOCTYPE html>
<html>
<head>
  <script src="https://sdk-web-vtex.y.uno/v1/main.js"></script>
</head>
<body>
  <div id="root-container"></div>
  <script>
    window.YunoVTEX.mount({  
      elementRoot: "root-container",  
      payload: '{}',  
      language: 'pt',
      domainVTEX: 'https://myvtex.yunopartnerbr.com',
      onPaymentDone: (paymentData) => { console.log(paymentData); },
      onError: (message, error) => { console.log(message, error); },
      onLoading: (loading) => { console.log(loading); }
    });
  </script>
</body>
</html>

A tabela a seguir descreve os parâmetros que você pode usar.

Propriedade	Tipo	Descrição	Necessário	Exemplo
`elementRoot`	Cordas	ID do elemento HTML	Verdadeiro	`"root-container"`
`payload`	Cordas	Vem de nossa resposta do conector	Verdadeiro	`{"isVTEXCard":true, "checkoutSessions":["id"], "paymentIds":["id"], "orderId":"id"}`
`language`	Cordas	Código de idioma ISO 639-1	Verdadeiro	`"pt"`
`domainVTEX`	Cordas	Domínio VTEX do comerciante (se diferente do VTEX)	Falso	`"https://myvtex.yunopartnerbr.com"`
`onLoading`	Função	Chamado quando o SDK processa um pagamento	Falso	`function(loading) { console.log(loading); }`
`onPaymentDone`	Função	Chamado quando o pagamento é concluído	Falso	`function(paymentResponse) { console.log(paymentResponse); }`
`onError`	Função	Chamado se ocorrer um erro	Falso	`function(message, error) { console.log(error); }`

Para obter os tipos do TypeScript, instale o npm pacote:

npm install @yuno-payments/sdk-web-vtex

Cargas úteis de resposta de pagamento

Ao processar pagamentos por meio de Yuno e VTEX, o yunopartnerbr.yuno gera uma carga estruturada que contém todos os detalhes necessários da transação. Abaixo, fornecemos exemplos de cargas úteis para pagamentos com cartão de crédito e pagamentos Pix (APMs).

📘
Geração e estrutura da carga útil

Geração automatizada: Os comerciantes não precisam modificar ou formatar o payload manualmente.

Estrutura dinâmica: O formato do payload se adapta com base no método de pagamento selecionado (cartão de crédito, Pix, etc.).

Integração perfeita: Os dados são recuperados automaticamente do conector do Yuno ao processar transações na VTEX.

Para obter mais detalhes, acesse a referência da API.

Carga útil do pagamento com cartão de crédito

A resposta JSON a seguir representa uma autorização de pagamento com cartão de crédito processada pelo Yuno.

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": "{\"isVTEXCard\":true,\"checkoutSessions\":[\"acd5c64e-f4c6-4cde-a24d-840e2d7ed78c\"],\"paymentIds\":[\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\"],\"orderId\":\"1510060504991\",\"publicApiKeys\":[\"sandbox_gAAAAABmq_lv7XP4nR-1Wey4rNuph3vWrCxxDwXYB9_V28t2ZGiAJPBAiWRKUxCu1siekHoTkSTNWaUoi2kjfyVJHdPbqZ3mrKwwXHtwkEeOBYqiAGmGQ2-RXJT3-ay-XUrnRbAWwz_tnwU-CHrb1_Mh6GkBzWCvMaZqeGwjF3xVRCeGfrlZopW9mmB7G93d-Q7UBTIcQNIQi-llGl8VHR396GKiwZT8XGC0wYh5ZYzotUWs9KZ1PZkH1d-ow-Zw2tmsv8cuc3HJ\"],\"country_code\":\"BR\",\"paymentMethod\":\"Visa\",\"authorizations\":[{\"reference\":\"504991\",\"orderId\":\"1510060504991\",\"shopperInteraction\":\"ecommerce\",\"paymentMethod\":\"Visa\",\"value\":0,\"referenceValue\":148,\"currency\":\"BRL\",\"installments\":1,\"installmentsInterestRate\":0,\"installmentsValue\":148,\"ipAddress\":\"185.239.149.42\",\"miniCart\":{\"buyer\":{\"email\":\"[email protected]\",\"firstName\":\"Camilo\",\"lastName\":\"Segura\",\"document\":\"02678175928\",\"phone\":\"+5511912345678\"},\"shippingAddress\":{\"receiverName\":\"Camilo Segura\",\"postalCode\":\"89220555\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"street\":\"Rua São Matias\",\"number\":\"1\"},\"billingAddress\":{\"postalCode\":\"89220555\",\"street\":\"Rua São Matias\",\"neighborhood\":\"Costa e Silva\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"number\":\"1\"},\"items\":[{\"id\":\"17\",\"name\":\"BLACK + DECKER 20V Max Cordless Motosserra, 10 polegadas, ferramenta somente (LCS1020B)\",\"price\":138,\"quantity\":1}],\"shippingValue\":10,\"taxValue\":0},\"paymentId\":\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\",\"transactionId\":\"A09E2F38DD524C64B92CD5019D9A41E7\",\"callbackUrl\":\"https://yunopartnerbr.vtexpayments.com.br/payment-provider/transactions/A09E2F38DD524C64B92CD5019D9A41E7/payments/6BB2F575BB1B493A9D3A3EBD8D8AA8D8/retry\"}],\"sessions\":[\"ZjgyMzRmZTZmMDVkMzBkNTg2YjY5NzZjNDA2YTY0NTJmNTE2NWJiYTIyZjI3NjU2ZjRiNjg0YzNhZGZkZGQ5NTVjMzFhYWNkNDU1NzFlNTU1ZmQ1MmQ0MWQyYzdlZDM4MDNmNTQ4OTZhN2FiMmYyNTJhYzI4YzZkYzkxNTlmNDAzMmYwNmIyY2E1ZmM1OWE2OWZhOTUyNDY3NjI3YTM0OTQ5NmEyYTQwNzgzMTVhYmU2YTkzNDBhMTc2ZmFjNzY0NWU0ZjU3ZjBmNDIzNDVjNDJjM2MyNjBlZGIwMmQ2ZjkyMzc4OGEzODEzMjE0N2NhN2M0MTM4Y2RkMDAwNjRkYjkwNmQxMjAzZTdiNGNjODJlMjEzZjczZDliZDg3NTMxYjQzZjQ0ZmFiNDJlMmQ4M2UwYTg2YjJhZWNmMmNmYTYzNDY4ZDExZGE2YjAyZTMyYTA2MmI3ZWJlMzIyNjRkYWFlM2JjMTczNThiYmEyNzZkMGUzMzIzMDFlYjk4NTA4NzJjNTIwZjIxOWI5OWY3YTE3ZWJhNWFiMGI0YzYzNWEwNTMwMmQ4YzlmMmVhZGJiOTBlNmY1YTZjMzk3ZTU4M2E4NGU3YzMzMDI2YTczNzdmM2Y5ZWQwOWE3MGFiZjlmMDk4NzkwY2U5YTQ3MTQ1ZTY1MzhjYjU0N2ZhNjY4MDY2NDIxMjA5MWM3MDdhYzc4MDYwMzg0YzA4ODg2NzM0YzRjNzMwNzAyMGNiNWQxOTVlZTAxOWZiZWJhOTg4MWJhMTY2ODY1NDFjOWExMTdlM2M2OGJmMmE5OGI4OTBjYTBkYWIxZjI2ZDc5NDdmYzc2NDE0YjBmODNlNWFkM2RlYTFkNzM1ZmQzMGMxNTlmNTY5YTZmZTYwNGMxMjViMzY0ZTNkN2JmYTk0NWFmN2I2Y2ZiNTRjN2Y3Y2EwMzJjZGY1NDM4MTlhNTIwMTQ4MzY2YzI1YmUyYTk1M2VlYjFhZGE2YmQ5MWYxYjUxZGIwYjE1MWJhYmZmZmFjODgzMDNjNmY4OTBiMWMxZWViMzUwMmQ3NGIwZTljNDZlY2ZlMTkyNTgwZjYwNDcxZjQ5ZWEzMTEyODQyMjE2NDYxYzI0MzM5NjQ3MjU3NGQ5NTE2MGJiMDBhMjQxYThlNmM1ZDEwZDQ3NzFlNDM4YjNhNzZhMzkzNTIyZDNkNmE1YWQyNGY3MTc5ZGJjOWM4OGEzNmVhNjgzYmZiMGQ2YThjNDY4M2ZiNDRkNGJmODVmNzIyYThhMmNhZjY0NzRlMmYxYzYzMTFjNWQ1N2RhOWM3NmFhNmU5ZjJmZmEwODUxMDZmNDA4ZjJlMjkyN2VkZjRiMjRiYzk0ZGMxZTJiMzlhMzk5YjE4ZTUzNjYwZjhmMDJmNTVlZWVhYzdhOWE0MjIyMjBjOWM0NzQ1YTliOWQ0MjYxZmE0YjliMDcxNjhhM2NmZjA2NDRjNWEyZTQ1NWU5YjViMjAyY2NmNDI5MmU4OWEwNjgyZjdkODZkYTc3ZWE4YzEzYjVhODI3YzhjMmI0MWNiNTc1MjMwZTQzZjUzZjhlMTdmOTVjOTkxNmE0MWIwNmMzZDZkNjc2YTgxOTk2ZjZlMGEwNGZiZTMyYTIxMzk3YTdjYjhmNTRjYjJhZTNlYmNkYmI3Njc4ZTdiOWVjZDU3ZTkxZWI4NGY2MWUzNjQ0N2I1YzY4ODhmODVlYmQzY2Q4YjExY2E2M2RkNmUzOTAyZjgyNTRkMjcxZGU0MzI1YzUxMmViMTBkYTM4YTk3ZTMwMzM1N2ZkZmVkNDlkYTQ0MzQ1NjczZTJlNTljZDdkMmFlZGNjMWVlYjM4NWE3NjMyYjZkZjIxZDQ3M2I0ZTdmMzNhNTI3MDg1Y2M0OWEyYzVhZTRiZmVhYjg2MDVhZTQzZWIwY2ExM2RkMzc1MWE1MzQyMDMwMzc4ODI0YTZiMDQ4MjA0NjYwMmZmNmQ2ZDIwYTk4NGI1NWQ5MGU3ODBmODM2MGI5NGU4ZjNhNjYwNDlkZDZkNjBmN2NkMzAyOTZjNDczYjQwNTcyMjkyNWZh\"],
    \"account\":\"yunopartnerbr\"}"
  }
}

Carga útil do pagamento Pix

Este exemplo mostra uma resposta de pagamento Pix, em que o Yuno gera um código QR no formato de texto e no formato de imagem base64.

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": {
      "code": "00020126830014br.gov.bcb.pix2561qr-code-h.picpay.com/pix/624ea025-9bb0-47ae-a620-6f2b9ba048815204000053039865802BR5912p2bpix teste6009Sao Paulo62070503***6304535D",
      "qrCodeBase64Image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABWQAAAVkCAYAAABTjRaxAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2ltu5TqWQMFmw/OfMuvz3vyoBFyil7YPIwZwsCU+bCxo7b33/wEAAAAA8OP+/+0BAAAAAABuIcgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAA**TRUNCATED**"
    }
  },
  "paymentId": "C9B4F5750BD24EF084E0C7EC0DB7AD16",
  "code": "UNDEFINED",
  "message": "Payment session started by Yuno"
}

Metadados de pagamento

Ao processar pagamentos por meio do conector VTEX, o Yuno inclui metadados tanto na sessão de checkout quanto na criação do pagamento. Esses metadados fornecem contexto adicional sobre a transação.

ID do vendedor (código de afiliado)

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.

O sellerId é automaticamente incluído nos metadados durante o processamento dos pagamentos:

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

Esse recurso é particularmente útil para comerciantes que utilizam o modo Afiliado da VTEX para participar de marketplaces. Para obter mais informações sobre como configurar afiliados na VTEX, consulte a documentação da VTEX sobre configuração de afiliados.

Integração com VTEXIO

Instalação

Permissões de administrador necessárias

Instalar yunopartnerbr.yuno

Instalar yunopartnerbr.yuno-app

Instale o Yuno SDK Web para VTEX (opcional)

Fluxos de pagamento

Fluxos de pagamento VTEXIO

Fluxo de pagamento com cartão de crédito na VTEXIO

Fluxo de pagamento Pix (APMs) na VTEXIO

VTEX headless

Fluxo de pagamento headless da VTEX

Instalando e usando o SDK Web VTEX

Cargas úteis de resposta de pagamento

Geração e estrutura da carga útil

Carga útil do pagamento com cartão de crédito

Carga útil do pagamento Pix

Metadados de pagamento

ID do vendedor (código de afiliado)

Instalar `yunopartnerbr.yuno`

Instalar `yunopartnerbr.yuno-app`