Guide d'intégration de VTEX Headless

Intégrez Yuno SDK Web pour VTEX Headless afin de gérer efficacement les paiements en ligne. Ce guide couvre les étapes d'installation, de configuration et de mise en œuvre.

Intégration VTEXIO

Pour utiliser Yuno dans VTEXIO checkout, installez les applications suivantes :

• yunopartnerbr.yuno: Un connecteur VTEXIO PPF qui facilite l'intégration entre VTEX et l'infrastructure de paiement de Yuno.

• yunopartnerbr.yuno-app: Une application de paiement frontale VTEXIO est nécessaire pour utiliser la carte ou le Click to Pay comme méthode de paiement. Elle n'est pas nécessaire pour Pix, Boleto, et d'autres méthodes de paiement basées sur la redirection. yunopartnerbr.yuno-app présente les caractéristiques suivantes :

  • Exécute le Yuno Web SDK pour collecter les données du navigateur.
  • Exécute les SDK de détection des fraudes de tiers.
  • Traite les paiements directement dans Yuno.
  • Permet de payer avec deux cartes de crédit.

Installation

Pour intégrer Yuno à VTEX, vous devez installer deux applications :

• yunopartnerbr.yuno: Connecteur VTEX PPF pour la communication avec le backend.
• yunopartnerbr.yuno-app: Application de paiement frontale nécessaire pour les paiements par carte.

🚧

Autorisations administratives requises

Pour installer les deux applications, vous devez disposer de droits d'administrateur dans VTEX.

Installer yunopartnerbr.yuno

Suivez ces étapes pour installer yunopartnerbr.yuno dans les requêtes de  VTEX Admin:

1. Connectez-vous à votre compte de magasin VTEX.
2. Dans le tableau de bord de VTEX Admin, naviguez vers Paramètres du magasin > Fournisseurs et cliquez sur Nouveau fournisseur.
3. Recherchez Yuno dans la liste des fournisseurs disponibles.
4. Cliquez sur Installer et suivez les instructions d'installation.

Pour plus de détails, reportez-vous à la page Configurer Yuno en tant que fournisseur.

Installer yunopartnerbr.yuno-app

yunopartnerbr.yuno-app est nécessaire pour les paiements par carte ou par Click to Pay. Pour l'installer, suivez les étapes :

1. Dans VTEX Admin, allez dans Apps > App Management.
2. Recherche de Yuno.
3. Localisez et sélectionnez Yuno Payment App (la deuxième option dans la liste).
4. Cliquez sur Installer pour terminer l'installation.

Installez Yuno SDK Web pour VTEX (facultatif)

Si votre projet nécessite Yuno SDK Web VTEXinstallez-le à l'aide de la fonction npm:

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

Ce package simplifie l'intégration du SDK Web VTEX et inclut le support TypeScript.

Pour utiliser le SDK, importez initialize et initialize :

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

...

const yunoVTEX = await loadScript()

yunoVTEX.mount({...})

Pour plus d'informations, consultez @yuno-payments/sdk-web-vtex.

Flux de paiement

Les sections suivantes illustrent la manière dont les paiements sont traités dans VTEXIO et VTEX Headless en utilisant différentes méthodes de paiement :

• Flux de paiement par carte de crédit dans VTEXIO
• Pix (APMs) Flux de paiement dans VTEXIO
• Flux de paiement sans tête VTEX

Flux de paiement VTEXIO

VTEXIO permet un traitement fluide des paiements pour divers modes de paiement, notamment les cartes de crédit et les modes de paiement alternatifs (APM) tels que Pix. Vous trouverez ci-dessous une description détaillée du fonctionnement de ces flux de paiement.

Processus de paiement par carte bancaire dans VTEXIO

Ce flux détaille le traitement des paiements par carte de crédit dans VTEXIO, depuis l'interaction avec l'utilisateur jusqu'à la fin de la transaction.

1. L'utilisateur clique sur le bouton de paiement dans le frontend de VTEXIO.
2. Le backend de VTEX envoie les informations relatives au paiement au yunopartnerbr.yuno connecteur.
3. Le connecteur Yuno envoie les informations relatives à la carte de crédit à l'API Yuno.
4. L'API Yuno renvoie un token à usage unique token le paiement.
5. Le connecteur Yuno informe VTEX que l'application de paiement doit être ouverte et fournit le token à usage unique.
6. VTEXIO ouvre l'application de paiement Yuno avec les données du connecteur Yuno.
7. L'utilisateur saisit les données de sa carte de crédit dans l'application de paiement Yuno.
8. Les détails du paiement, les informations sur le navigateur et les données de détection de la fraude sont renvoyés au connecteur Yuno.
9. Le paiement est créé dans Yuno et traité.
10. L'utilisateur reçoit une confirmation de l'état du paiement de la part de VTEX.

Flux de paiement Pix (APM) dans VTEXIO

Ce flux explique comment Pix et d'autres APM sont gérés dans VTEXIO, y compris la création et la redirection des paiements.

1. L'utilisateur clique sur le bouton de paiement dans le frontend de VTEXIO.
2. Le backend de VTEX envoie les informations relatives au paiement au yunopartnerbr.yuno connecteur.
3. Le connecteur Yuno crée le paiement dans le système de Yuno.
4. Yuno génère un code QR et des données de paiement supplémentaires et les renvoie à VTEX.
5. VTEXIO ouvre l'application Pix ou redirige l'utilisateur pour compléter le paiement.

VTEX sans interface utilisateur

Pour utiliser Yuno dans la caisse de VTEX Headless, installez :

• yunopartnerbr.yuno: Un connecteur VTEXIO PPF qui s'exécute sur le serveur VTEXIO.

En outre, le SDK Web VTEX doit être mis en œuvre. Ce SDK prend en charge les paiements avec deux cartes de crédit.

Flux de paiement sans interface VTEX

VTEX Headless nécessite une approche différente du traitement des paiements. Vous trouverez ci-dessous les étapes à suivre pour traiter les transactions par carte de crédit dans VTEX Headless.

1. L'utilisateur clique sur le bouton de paiement dans le frontend personnalisé du commerçant.
2. Le backend de VTEX envoie les informations relatives au paiement au yunopartnerbr.yuno connecteur.
3. Le connecteur Yuno envoie les informations relatives à la carte de crédit à l'API Yuno.
4. L'API Yuno renvoie un token à usage unique token le paiement.
5. Le connecteur Yuno informe VTEX que l'application de paiement doit être ouverte et fournit le token à usage unique.
6. Le frontend du commerçant ouvre le Yuno SDK Web VTEX en utilisant les données fournies.
7. Les détails du paiement, les informations relatives au navigateur et les données de détection de la fraude sont envoyés au connecteur Yuno.
8. Le connecteur Yuno traite le paiement en appelant la fonction{{merchant’s domain}}/_v/yunopartnerbr.yuno/v4/payments/yuno.
9. L'utilisateur reçoit une confirmation de l'état du paiement de la part de VTEX.

Installation et utilisation du SDK Web VTEX

Le SDK Yuno Web VTEX permet une intégration transparente avec l'infrastructure de paiement de VTEX, permettant aux marchands de gérer les paiements directement dans leur interface.

Pour intégrer Yuno SDK Web for VTEX, incluez le script dans votre fichier HTML et configurez les paramètres nécessaires :

<!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>

Le tableau suivant décrit les paramètres que vous pouvez utiliser.

Pour obtenir les types TypeScript, installez le module npm l'emballage :

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

Charges utiles de réponse de paiement

Lors du traitement des paiements via Yuno et VTEX, la fonction yunopartnerbr.yuno génère une charge utile structurée contenant tous les détails nécessaires à la transaction. Nous présentons ci-dessous des exemples de payloads pour les paiements par carte de crédit et les paiements Pix (APM).

📘

Génération et structure de la charge utile

• Génération automatisée : Les commerçants n'ont pas besoin de modifier ou de formater manuellement les données utiles.
• Structure dynamique : Le format de la charge utile s'adapte en fonction de la méthode de paiement sélectionnée (carte de crédit, Pix, etc.).
• Intégration transparente : les données sont récupérées automatiquement depuis le connecteur Yuno lors du traitement des transactions dans VTEX.

Pour plus de détails, consultez la référence de l'API.

Charge utile pour paiement par carte de crédit

La réponse JSON suivante représente une autorisation de paiement par carte de crédit traitée par 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\"}"
  }
}

Charge utile de paiement Pix

Cet exemple montre une réponse de paiement Pix, où Yuno génère un code QR à la fois au format texte et au format image 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"
}

Métadonnées de paiement

Lors du traitement des paiements via le connecteur VTEX, Yuno inclut des métadonnées à la fois dans la session de paiement et dans la création du paiement. Ces métadonnées fournissent des informations supplémentaires sur la transaction.

Identifiant vendeur (code d'affiliation)

Le connecteur VTEX capture le sellerId (Code d'affiliation) des commandes VTEX et l'inclut dans la session de paiement et les métadonnées de paiement. Cela permet le suivi du marché et la fonctionnalité du mode d'affiliation, permettant aux commerçants de suivre l'attribution entre leurs propres magasins et les marchés partenaires.

Le champ sellerId est automatiquement inclus dans les métadonnées lors du traitement des paiements :

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

Cette fonctionnalité est particulièrement utile pour les marchands qui utilisent le mode Affilié de VTEX pour participer à des places de marché. Pour plus d'informations sur la configuration des affiliés dans VTEX, consultez la documentation VTEX sur la configuration des affiliés.