Implémentation du Full SDK (Web)

Cette page propose un guide étape par étape pour implémenter et activer la fonctionnalité du Full Web SDK de Yuno dans votre application.

📘

Référence du journal des modifications :

Ce guide couvre la version actuelle du SDK. Pour les détails sur les versions précédentes, consultez le journal des modifications.

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

Ajoutez la balise script suivante à votre fichier HTML pour inclure le SDK Web de Yuno :

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

Alternativement, vous pouvez l'installer via npm :

npm install @yuno-payments/sdk-web

Après avoir terminé l'intégration du SDK, passez aux étapes suivantes pour implémenter la fonctionnalité complète de paiement.

📘

Bibliothèque TypeScript

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

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

Créez une instance de la classe Yuno en fournissant une PUBLIC_API_KEYvalide. Consultez la page des identifiants pour plus d'informations.

Initialisez le SDK avec votre clé API publique :

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Étape 3 : Démarrer le processus de paiement

Utilisez l'endpoint  yuno.startCheckout pour démarrer le processus de paiement avec les paramètres nécessaires.

Consultez le Tableau des paramètres ci-dessous pour toutes les options que vous pouvez utiliser avec startCheckout.

Pour une personnalisation supplémentaire ou des paramètres avancés/facultatifs, consultez la section Fonctionnalités complémentaires.

Paramètres

Le tableau suivant répertorie tous les paramètres disponibles pour la méthode startCheckout avec des descriptions :

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);
  },
  yunoPaymentMethodSelected: () => {
    console.log("Payment method selected");
  },
  yunoPaymentResult: (status) => {
    console.log("Payment result:", status);
  },
  yunoError: (message, data) => {
    console.error("Payment error:", message, data);
  },
  async yunoCreatePayment(oneTimeToken) {
    await createPayment({ oneTimeToken, checkoutSession });
    yuno.continuePayment({ showPaymentStatus: true });
  },
});

📘

Mode de rendu

Par défaut, le SDK Yuno s'affiche sous forme de modale. Cependant, vous pouvez spécifier l'élément où le SDK sera rendu. Pour plus d'informations, accédez au Mode de rendu sous les fonctionnalités complémentaires.

📘

onPaymentMethodSelected Événement

Pour toutes les méthodes de paiement alternatives (APM), y compris Google Pay, Apple Pay et PayPal, l'événement onPaymentMethodSelected est déclenché dès que le client choisit la méthode de paiement (avant que le flux de paiement ne commence). Définissez onPaymentMethodSelected dans les requêtes de  startCheckout avant mountCheckout.

Pour PayPal, la page de paiement s'ouvre désormais immédiatement après que l'acheteur a sélectionné PayPal, sans qu'aucun clic de confirmation supplémentaire ne soit nécessaire.

📘

Affichage Google Pay et Apple Pay

À partir de la version 1.5 du SDK, Google Pay et Apple Pay apparaissent sous forme de boutons directs plutôt que de boutons radio dans la liste des modes de paiement. Ils sont affichés séparément des autres modes de paiement.

Étape 4 : Monter le SDK

Affichez les méthodes de paiement :

yuno.mountCheckout();

Monter avec une méthode de paiement par défaut sélectionnée :

yuno.mountCheckout({
  paymentMethodType: PAYMENT_METHOD_TYPE,
  vaultedToken: VAULTED_TOKEN,
});

Étape 5 : Lancer le processus de paiement

Appelez  yuno.startPayment() pour lancer le flux de paiement après que l'utilisateur a sélectionné une méthode de paiement :

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

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

Étape 6 : Obtenir le token usage unique (OTT)

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

yunoCreatePayment(oneTimeToken) ;

Vous pouvez également utiliser tokenWithInformation pour recevoir des informations supplémentaires fournies par le client (comme 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 7 : Créer le paiement

Après avoir terminé les étapes précédentes, passez à la création du paiement. La création de paiement doit être effectuée en utilisant le endpoint Créer un paiement. Le backend du commerçant doit appeler ce endpoint pour créer le paiement chez Yuno en utilisant le token à usage unique et la session de paiement.

📘

Finaliser l'Intégration

Après l'Étape 7, vous avez implémenté avec succès le flux de paiement de base. Pour tester votre intégration, créez un paiement de test en utilisant la session de paiement et le token à usage unique. Pour des fonctionnalités supplémentaires et des configurations avancées, consultez la section Fonctionnalités complémentaires ci-dessous.

❗️

Méthode ContinuePayment

Après la création d'un paiement, Yuno demande que vous intégriez la méthode continuePayment du SDK. Ceci est nécessaire car certaines méthodes de paiement asynchrones requièrent des actions client supplémentaires pour finaliser le processus. La réponse de l'API indiquera ce scénario en définissant le champ sdk_action_required à true. Lorsque cela se produit, vous devez appeler yuno.continuePayment(), qui présentera automatiquement les écrans nécessaires au client, lui permettant de finaliser le flux de paiement sans que vous ayez à gérer chaque cas manuellement.

continuePayment valeur de retour ou null

Pour les méthodes de paiement qui nécessitent une action côté commerçant (par exemple, lorsque le fournisseur de paiement requiert une URL de redirection dans une webview), la méthode await yuno.continuePayment() retourne soit un objet avec la structure suivante, soit null :

{
  action: 'REDIRECT_URL'
  type: string
  redirect: {
    init_url: string
    success_url: string
    error_url: string
  }
} | null

Lorsque la méthode retourne un objet, vous pouvez gérer les flux de paiement de votre application qui nécessitent une gestion de redirection personnalisée. Lorsqu'elle retourne null, aucune action supplémentaire côté commerçant n'est nécessaire.

📘

Application Démo

En plus des exemples de code fournis, vous pouvez accéder à l'Application Démo pour une implémentation complète des SDK Yuno. L'application démo comprend des exemples fonctionnels de tous les SDK Yuno et peut être clonée depuis le répertoire GitHub.

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
• Mode de rendu
• Configurations du formulaire de carte
  • Sauvegarde de carte pour les futurs paiements
  • Modes 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

Vous pouvez utiliser la  mountExternalButtons méthode permettant d'afficher les boutons Google Pay et Apple Pay à des emplacements personnalisés dans votre interface utilisateur. Cela vous permet de contrôler l'emplacement d'affichage de ces boutons.

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 de formulaire

Contrôlez l'utilisation du loader :

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

Formulaire de l'Émetteur

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

Mode de rendu

yuno.startCheckout({
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

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

Vous pouvez afficher une case à cocher pour sauvegarder ou enregistrer des cartes en utilisant cardSaveEnable: true. Les exemples suivants montrent la case à cocher pour les deux rendus de formulaire de carte :

Modes de rendu

Les captures d'écran suivantes montrent 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 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. Pour ce faire :

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. Si la transaction est rejetée :
   1. Exécutez la méthode yuno.notifyError() pour supprimer le CVV précédemment entré 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 de paiement

Vous pouvez masquer le bouton de paiement lorsque vous présentez le formulaire de données client ou de carte. Définissez showPayButton à false lors du démarrage du paiement avec la fonction startCheckout :

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

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

Les images suivantes montrent des exemples du Formulaire de Carte avec et sans le Bouton de Paiement :

Si vous masquez le Bouton de Paiement, vous devez déclencher la création du token à usage unique via votre code. Pour créer le token à usage unique et continuer le paiement dans votre backend, appelez la fonction submitOneTimeTokenForm :

yuno.submitOneTimeTokenForm() ;

Paramètre d' options d'initialisation facultatif

Cette fonctionnalité facultative est destinée aux cas d'utilisation avancés où vous devez personnaliser la manière dont l'identification de l'appareil est gérée via les cookies.

À partir du SDK Yuno v1.2, la fonction Yuno.initialize prend en charge un nouveau paramètre facultatif appelé options. Cela permet une configuration avancée telle que la personnalisation du nom du cookie utilisé pour l'identification de l'appareil.

Options d'initialisation

La signature de fonction mise à jour est :

const yuno = await Yuno.initialize(publicApiKey, applicationSession, options);

• publicApiKey (string) : Votre clé API publique.
• applicationSession (string | undefined) : ID de session facultatif.

  Recommandation : Laissez ceci undefined pour que le SDK génère et gère sa propre session en interne. Ne le définissez que si vous avez besoin d'une stratégie de gestion de session personnalisée.

• options (object | undefined) : Objet facultatif pour la configuration avancée.

Structure des options

Le champ options prend en charge la structure suivante :

const options = {
  cookies: {
    deviceId: {
      name: "customCookieName",
    },
  },
};

Si deviceId.name n'est pas spécifié, le SDK utilise par défaut "yuno" comme nom de cookie.

Exemple d'Implémentation

const publicApiKey = "your-public-api-key";
const options = {
  cookies: {
    deviceId: {
      name: "custom-device-id",
    },
  },
};

const yuno = await Yuno.initialize(publicApiKey, undefined, options);

Et après ?

Apprenez-en davantage sur les configurations supplémentaires du Full SDK en accédant aux Fonctionnalités Complémentaires. Vous pouvez également accéder à d'autres fonctions disponibles sur le SDK Web de Yuno :

• Personnalisations du SDK: Modifiez l'apparence du SDK pour correspondre à votre marque
• Statut de Paiement : Informez l'utilisateur sur le processus de paiement
• Configuration 3DS du SDK: Intégrez la 3DS dans votre flux de paiement

Restez informé

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