Lite SDK (Paiement Web)

Suivez ce guide étape par étape pour implémenter et activer la fonctionnalité du Lite Web SDK de Yuno dans votre application.

Étape 1 : Inclure la bibliothèque dans votre projet

Assurez-vous que le fichier SDK Yuno est inclus dans votre page web avant de fermer la balise </body> . Voir l'exemple ci-dessous :

<script src="https://sdk-web.y.uno/v1.5/main.js"></script>

📘

Support TypeScript

Si vous utilisez TypeScript, Yuno fournit une bibliothèque que vous pouvez utiliser pour voir toutes les méthodes disponibles dans le SDK Web de Yuno.

Étape 2 : Initialiser le SDK avec la clé publique

Dans votre application JavaScript, créez une instance de la classe Yuno en fournissant une PUBLIC_API_KEY valide. Voir le guide  Obtenir vos identifiants API valide.

Comme dans l'exemple ci-dessous, utilisez la classe initialisée attribuée à la constante yuno.

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Étape 3 : Démarrer le processus de paiement

Vous allez démarrer le processus de paiement. Pour ce faire, utilisez la fonction yuno.startCheckout et fournissez les paramètres nécessaires.

Le tableau suivant répertorie tous les paramètres requis et leurs descriptions. Pour les paramètres facultatifs, consultez les Fonctionnalités Complémentaires.

yuno.startCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "FR",
  language: "fr-FR",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  card: {
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
  onLoading: (args) => {
    console.log(args);
  },
  async yunoCreatePayment(oneTimeToken) {
    /**
     * The createPayment function calls the backend to create a payment in Yuno.
     * It uses the following endpoint https://docs.y.uno/reference/create-payment
     */
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Types de Transaction

Les paiements peuvent être initiés par le client (CIT) ou par le marchand (MIT). Vous trouverez plus d'informations sur leurs caractéristiques dans Identifiants enregistrés.

Le guide étape par étape présenté sur cette page fait référence à une transaction initiée par le client sans l'option de récurrence. Elle est généralement utilisée pour les achats en ligne uniques, les achats en magasin, les retraits aux guichets automatiques, etc.

Étape 4 : Monter le SDK

Ensuite, vous devez monter le SDK, présentant le paiement en fonction de la méthode de paiement sélectionnée par votre client. Rappelez-vous, lors de l'utilisation du Lite SDK, vous êtes responsable de l'affichage des méthodes de paiement et de la capture de la sélection du client. Accédez à Lite SDK (Paiement) pour des informations supplémentaires.

Utilisez l'endpoint  yuno.mountCheckoutLite() en sélectionnant un élément HTML et en utilisant un sélecteur CSS valide (#, ., [data-*]) pour afficher le paiement des méthodes de paiement sélectionnées.

yuno.mountCheckoutLite({
  /**
   * can be one of 'PAYPAL' | 'PIX' | CARD
   */
  paymentMethodType: PAYMENT_METHOD_TYPE,
  /**
   * Vaulted token related to payment method type.
   * Only if you already have it
   * @optional
   */
  vaultedToken: VAULTED_TOKEN,
});

Après le montage du SDK, le flux de la méthode de paiement sélectionnée démarre automatiquement.

Pour PayPal, la page de paiement PayPal s'ouvre désormais immédiatement après que l'acheteur a sélectionné PayPal, sans qu'il soit nécessaire de cliquer pour confirmer.

📘

Google Pay et Apple Pay dans Lite SDK

Google Pay et Apple Pay ne sont pas disponibles en tant qu'options de paiement intégrées dans le Lite SDK. Pour utiliser ces méthodes de paiement, vous devez utiliser le mountExternalButtons méthode. Voir Monter les boutons externes  pour plus d'informations.

Étape 5 : Installez les boutons externes (facultatif)

Si vous souhaitez utiliser Google Pay ou Apple Pay dans le Lite SDK, vous pouvez monter ces boutons de paiement en externe à l'aide de la fonction mountExternalButtons méthode. Cette méthode vous permet de choisir l'emplacement d'affichage de chaque bouton dans votre interface utilisateur.

// Mount external buttons
await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

Le champ mountExternalButtons La méthode accepte un tableau d'objets, chacun contenant :

• paymentMethodType: Soit 'APPLE_PAY' ou 'GOOGLE_PAY'
• elementSelector: Sélecteur CSS pour l'élément HTML où le bouton doit être affiché.

Démontage des boutons externes

Vous pouvez démonter un seul bouton externe :

yuno.unmountExternalButton('APPLE_PAY');

Ou démontez tous les boutons externes en même temps :

yuno.démonterTousLesBoutonsExternes();

Étape 6 : Initier le processus de paiement

Une fois que l'utilisateur a choisi une méthode de paiement , n'oubliez pas d'appeler yuno.startPayment() pour lancer le flux de paiement. Vous trouverez ci-dessous un exemple où yuno.startPayment() est appelé lorsque l'utilisateur clique sur le boutton button-pay:

const PayButton = document.querySelector("#button-pay");

PayButton.addEventListener("click", () => {
  yuno.startPayment();
});

Étape 7 : Obtenir le token à usage unique (OTT)

Une fois que le client a rempli les données demandées dans les formulaires de paiement de Yuno, le SDK fournit le token à usage unique. La fonction de configuration yunoCreatePayment(oneTimeToken) est ensuite déclenchée avec le token à usage unique.

yunoCreatePayment(oneTimeToken) ;

Vous pouvez également utiliser tokenWithInformation pour recevoir toutes les informations supplémentaires fournies par le client lors du paiement, telles que les versements ou le type/numéro de document.

yunoCreatePayment(oneTimeToken, jetonAvecInformations) ;

📘

Gestion du Loader

Le commerçant est responsable de la gestion du loader (indicateur de chargement). Yuno fournit une option de loader par défaut, mais les commerçants peuvent implémenter leur propre loader si désiré. Dans ce cas, ils sont responsables des configurations nécessaires.

Étape 8 : Créer le paiement

Une fois que vous avez terminé les étapes décrites précédemment, vous pouvez créer un paiement. La création d'un paiement back-to-back doit être effectuée à l'aide du l'endpoint Créer un paiement. Le commerçant doit appeler son backend pour créer le paiement dans Yuno, en utilisant le token à usage unique et la session de paiement.

📘

Méthode ContinuePayment

Yuno recommande d'intégrer la méthode continuePayment du SDK après la création du paiement. En effet, certaines méthodes de paiement asynchrones nécessitent une action supplémentaire de la part du client pour finaliser le paiement. L'API vous informera de ce scénario via le champ sdk_action_required de la réponse, qui sera retourné comme true. La fonction yuno.continuePayment() affichera des écrans supplémentaires aux clients, où ils pourront effectuer les actions nécessaires pour finaliser le paiement. Si sdk_action_required est faux, cette étape n'est pas nécessaire.

Fonctionnalités Complémentaires

Le SDK Web Yuno offre des services et des configurations supplémentaires que vous pouvez utiliser pour améliorer l'expérience client :

• Monter les boutons externes
• Loader de formulaire
• Liste des émetteurs bancaires
• Mode de rendu
• Configurations du formulaire de carte
  • Sauvegarde de carte pour les futurs paiements
  • Mode de rendu
  • Textes des Boutons de Formulaire de Paiement
  • Persistance du formulaire de carte de crédit pour réessayer les paiements
  • Masquer le bouton Payer

Monter les boutons externes

Utilisez l'endpoint  mountExternalButtons méthode pour afficher les boutons Google Pay et Apple Pay dans votre interface utilisateur personnalisée. Cette méthode est nécessaire si vous souhaitez utiliser ces modes de paiement dans le Lite SDK, car ils ne sont pas disponibles en tant qu'options de paiement intégrées.

await yuno.mountExternalButtons([
  {
    paymentMethodType: 'APPLE_PAY',
    elementSelector: '#apple-pay',
  },
  {
    paymentMethodType: 'GOOGLE_PAY',
    elementSelector: '#google-pay',
  },
]);

Paramètres

Boutons de démontage

Vous pouvez désactiver un seul bouton externe par type de mode de paiement :

yuno.unmountExternalButton('APPLE_PAY');

Ou démontez tous les boutons externes en même temps :

yuno.démonterTousLesBoutonsExternes();

Loader

Contrôlez l'utilisation du loader.

yuno.startCheckout({
  showLoading: true,
});

Formulaire de l'émetteur

yuno.startCheckout({
  issuersFormEnable: true,
});

Mode de rendu du formulaire

📘

Mode de rendu amélioré dans Lite SDK .0

Le Lite SDK v2.0 amélioré offre des capacités de mode de rendu avancées qui intègrent les formulaires de paiement de Yuno directement dans votre interface. Cela vous donne un contrôle complet sur le parcours de paiement, y compris les écrans de chargement, de statut et de saisie de paiement, avec une personnalisation visuelle complète et une intégration UX transparente.

yuno.startCheckout({
  renderMode:

Configurations du formulaire de carte

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    cardSaveEnable: false,
    texts: {},
    cardNumberPlaceholder: "Enter card number", // Optional: Custom placeholder text
    hideCardholderName: false, // Optional: Set to true to hide cardholder name field
    isCreditCardProcessingOnly: true,
    onChange: ({ error, data }) => {
      if (error) {
        console.log('Card form error:', error);
      } else {
        console.log('Card form data:', data);
      }
    },
  },
});

Sauvegarde de carte pour les futurs paiements

De plus, vous pouvez afficher une case à cocher pour sauvegarder ou enregistrer des cartes en utilisant cardSaveEnable: true. Vous trouverez ci-dessous des exemples de la case à cocher pour les deux rendus de formulaire de carte.

Modes de rendu

Ci-dessous, vous trouverez des captures d'écran présentant la différence entre :

• Modes de rendu modal  et  elements pour la liste des méthodes de paiement
• Modes de rendu step  et  extends pour le formulaire de carte de crédit

Vous pouvez également choisir l'une des options de rendu pour le formulaire de la carte, step  et  extends:

Textes des Boutons de Formulaire de Paiement

yuno.startCheckout({
  texts: {
    customerForm?: {
      submitButton?: string;
    }
    paymentOtp?: {
      sendOtpButton?: string;
    }
  }
})

Persistance du formulaire de carte de crédit pour réessayer les paiements

Si une transaction est rejetée, vous pouvez utiliser le formulaire de carte de crédit pour réessayer un paiement après que le client a saisi les détails de la carte de crédit. Pour ce faire, vous devrez :

1. Ajouter le paramètre suivant lors de l'initialisation du SDK pour persister le formulaire de carte de crédit après la création du token à usage unique :
   JavaScript

   yuno.startCheckout({
     automaticallyUnmount: false,
   });

2. En cas de rejet de la transaction, vous devrez :
   1. Exécutez la méthode yuno.notifyError() pour supprimer le CVV précédemment saisi pour la première transaction.
   2. Créez une nouvelle session de paiement et mettez à jour le SDK avec la nouvelle en exécutant yuno.updateCheckoutSession(checkoutsession)
3. Poursuivez avec la nouvelle session de paiement et le token à usage unique avec le flux de paiement régulier.

Masquer le bouton Payer

Vous pouvez masquer le Payer bouton lors de la présentation de la carte ou des formulaires de données client. Pour contrôler cette fonctionnalité, vous devez définir showPayButton à false lors du démarrage du paiement avec la fonction startCheckout . Le bloc de code ci-dessous présente un exemple de masquage du bouton de paiement :

yuno.startCheckout({
  /**
   * Hide (false) or show (true) the customer or card form pay button
   * @default true
   * @optional
   */
  showPayButton: false,
});

Les images suivantes présentent des exemples du Formulaire de Données Client avec et sans le Bouton de Paiement :

Les images suivantes présentent des exemples du formulaire de carte avec et sans bouton « Payer »:

Si vous masquez le Payer bouton, vous devrez lancer token à usage unique via votre code. Pour créer le token à usage unique token poursuivre le paiement dans votre backend, appelez la fonction submitOneTimeTokenForm . le bloc de code ci-dessous présente comment utiliser la fonction submitOneTimeTokenForm .

/**
 * Cette fonction déclenche la même fonctionnalité que celle appelée lorsque le client clique sur le bouton du formulaire de paiement. Cette approche ne fonctionne pas si vous avez choisi le mode de rendu step.
 */
yuno.submitOneTimeTokenForm() ;

Restez informé

Visitez le journal des modifications pour les dernières mises à jour du SDK et l'historique des versions.