Lite SDK (Inscription Web)

👍

SDK recommandé

Nous recommandons d'utiliser le Seamless Web SDK pour une expérience d'intégration fluide. Cette option offre une solution de paiement flexible avec des composants d'interface utilisateur (UI) pré-intégrés et des options de personnalisation.

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

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

Avant de procéder à l'implémentation du Lite SDK, veuillez consulter la Vue d'ensemble de l'intégration du SDK pour des instructions détaillées sur l'intégration du SDK dans votre projet.

Le guide d'intégration propose trois méthodes flexibles :

• Méthode 1 (HTML): Ajoutez une seule balise de script à votre fichier HTML. Il s'agit de la méthode la plus simple, idéale pour les implémentations de base et les prototypes rapides.
• Méthode 2 (JavaScript dynamique): Chargez le SDK par programmation avec gestion des erreurs et états de chargement personnalisés. Cette méthode est idéale pour les applications nécessitant plus de contrôle sur l'intégration.
• Méthode 3 (NPM): Utilisez notre package NPM dans les applications JavaScript modernes. C'est l'approche que nous recommandons, avec la gestion des dépendances, le tree-shaking et la prise en charge de TypeScript.

1. Ajouter le script SDK directement en HTML

La manière la plus simple d'intégrer le SDK Yuno est d'ajouter une balise <script> à votre fichier HTML. Cette méthode offre une implémentation rapide tout en assurant un chargement asynchrone correct. Le SDK expose un événement qui signale quand il est complètement chargé, vous permettant d'initialiser et d'utiliser ses fonctionnalités en toute sécurité au bon moment.

Commencez par configurer l'écouteur d'événement, puis chargez le SDK :

<script>
  window.addEventListener('yuno-sdk-ready', () => {
    console.log('SDK loaded');
    const yuno = await Yuno.initialize(PUBLIC_API_KEY);
  });
</script>

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

2. Injecter le SDK dynamiquement à l'aide de JavaScript

La méthode d'injection JavaScript dynamique offre un contrôle accru sur le chargement et l'initialisation du SDK. Cette approche vous permet de :

• Charger le SDK par programmation lorsque cela est nécessaire
• Implémenter des états de chargement et une gestion des erreurs personnalisés
• Contrôler précisément le moment où le SDK devient disponible
• Synchroniser l'initialisation du SDK avec la logique de votre application
• Créer une gestion des erreurs sur mesure pour votre cas d'utilisation

Cette méthode est idéale lorsque vous avez besoin d'un contrôle granulaire sur le processus de chargement du SDK et que vous souhaitez gérer divers scénarios avec précision.

Créez une fonction pour injecter le SDK dynamiquement :

export const injectScript = async (): Promise<boolean> => {
  const head = document.getElementsByTagName('head')[0];
  const js = document.createElement('script');
  js.src = "https://sdk-web.y.uno/v1.5/main.js";
  js.defer = true;

  return new Promise((resolve, reject) => {
    window.addEventListener('yuno-sdk-ready', () => {
      resolve(true);
    });

    js.onerror = (error) => {
      const event = new CustomEvent('yuno-sdk-error', { detail: error });
      window.dispatchEvent(event);
      reject(new Error(`Failed to load script: ${js.src} - ${error.message}`));
    };

    head.appendChild(js);
  });
};

Utilisez la fonction pour injecter le SDK :

await injectScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

3. Utiliser le module NPM

Pour les projets utilisant la gestion de packages NPM, vous pouvez installer le SDK en tant que module via NPM. Cette approche offre une meilleure gestion des dépendances, un meilleur contrôle de version et une intégration transparente avec les outils et frameworks de construction JavaScript modernes. Elle est particulièrement bénéfique pour les applications utilisant des bundlers comme webpack, Rollup ou Vite.

npm install @yuno-payments/sdk-web

Ensuite, chargez et initialisez le SDK comme suit :

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

await loadScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Choisissez la méthode d'intégration qui convient le mieux à votre flux de développement et à vos exigences techniques. Après avoir terminé l'intégration, vous pouvez procéder aux étapes suivantes pour implémenter la fonctionnalité d'inscription lite.

📘

Bibliothèque 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 si vous ne les avez pas. Dans l'exemple ci-dessous, la classe initialisée est attribuée à la constante yuno.

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Étape 3 : Créer une session client et un objet de méthode de paiement pour l'inscription

Avant de poursuivre le processus, vous devrez créer une session client et un objet de mode de paiement à utiliser dans la configuration de votre intégration SDK Lite pour l'inscription. Lors de la création de l'objet de mode de paiement, vous devrez définir quel mode de paiement sera disponible pour l'inscription de votre client.

📘

Important

La session client et l'objet de mode de paiement d'inscription doivent être créés côté serveur afin de garantir la sécurité de vos clés API privées. Le type de mode de paiement est défini côté serveur, contrairement à d'autres intégrations où il peut être défini côté client.

Exemple côté serveur

Créez une session client et un mode de paiement pour l'inscription dans votre backend. Cela permet de sécuriser vos clés API privées.

// 1. Create customer session
const customerSession = await fetch(
  "https://api-sandbox.y.uno/v1/customers/sessions",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      customer_id: "your-customer-id",
      country: "US",
    }),
  }
).then((res) => res.json());

// 2. Create enrollment payment method
const enrollment = await fetch(
  `https://api-sandbox.y.uno/v1/customers/sessions/${customerSession.id}/payment-methods`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${PRIVATE_SECRET_KEY}`,
    },
    body: JSON.stringify({
      type: "CARD",
    }),
  }
).then((res) => res.json());

// Return customerSession to your client
return customerSession;

Exemple côté client

Après avoir reçu le customerSession Depuis votre serveur, initialize SDK Yuno et installez le formulaire d'inscription côté client.

// Initialize Yuno SDK
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

// Mount the enrollment form
yuno.mountEnrollmentLite({
  customerSession, // Received from your server
  countryCode: "US",
  language: "en",
  showLoading: true,
  onLoading: (args) => {
    console.log(args);
  },
});

📘

Vérification

Si vous souhaitez vérifier les cartes (autorisation de valeur zéro) avant l'inscription, vous pouvez remplir la structure verify lors de la définition de l'objet de méthode de paiement pour la session client.

Étape 4 : Monter l'inscription lite

La configuration et le montage sont effectués dans la même étape pour l'inscription Lite. Pour ce faire, utilisez la fonction yuno.mountEnrollmentLite et fournissez les paramètres nécessaires. Le tableau suivant énumère tous les paramètres et leur description.

Le bloc de code suivant présente un exemple de configuration et de montage des paramètres de l'inscription Lite.

yuno.mountEnrollmentLite({
  customerSession: 'e15648b0-fcd5-4799-a14c-cc463ae8a133',
  /**
   * The complete list of country codes is available on https://docs.y.uno/docs/country-coverage-yuno-sdk
   */
  country_code: country,
  /**
  * Language for payment forms (see Supported languages)
  * Defaults to browser language when available
  */
  language: 'en-US',
  /**
   * Hide or show the Yuno loading/spinner page
   * Default is true
   * @optional
   */
  showLoading: true,
  /**
   * Required if you'd like to be informed if there is a server call
   * @param { isLoading: boolean, type: 'DOCUMENT' | 'ONE_TIME_TOKEN'  } data
   * @optional
   */
  onLoading: (args) => {
    console.log(args);
  }
  /**
   *  API card
   *  @optional
   */
  card: {
    /**
     * Mode render card can be step or extends
     * Default extends
     */
    type: "extends",
    /**
     * Write custom CSS to style the card form. Your CSS will be injected into the iframe.
     * Example:
     * `@import url('https://fonts.googleapis.com/css2?family=Luckiest+Guy&display=swap');
     *  .Yuno-front-side-card__name-label {
     *    color: red !important;
     *    font-family: 'Luckiest Guy' !important;
     *   }`
     */
    styles: '',
    /**
     * Show checkbox for save/enroll card
     * Default is false
     */
    cardSaveEnable: false,
    /**
     * Custom texts in Card forms buttons
     * Example:
     *
     *  texts: {
     *    cardForm?: {
     *      enrollmentSubmitButton?: string;
     *       paymentSubmitButton?: string;
     *     }
     *     cardStepper?: {
     *       numberCardStep?: {
     *         nextButton?: string;
     *       },
     *       cardHolderNameStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       expirationDateStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       },
     *       cvvStep?: {
     *         prevButton?: string;
     *         nextButton?: string;
     *       }
     *     }
     *  }
     */
    texts: {},
    /**
     * Hide or show the document fields into card form
     * Default is true
     * @optional
     */
    documentEnable: true,
  },
  /**
   * Call back is called with the following object
   * @param {{
   *  status: 'CREATED'
   *    | 'EXPIRED',
   *    | 'REJECTED',
   *    | 'READY_TO_ENROLL',
   *    | 'ENROLL_IN_PROCESS',
   *    | 'UNENROLL_IN_PROCESS',
   *    | 'ENROLLED',
   *    | 'DECLINED',
   *    | 'CANCELED',
   *    | 'ERROR',
   *    | 'UNENROLLED',
   *  vaultedToken: string,
   * }}
   */
  yunoEnrollmentStatus: ({ status, vaultedToken}) => {
    console.log('status', { status, vaultedToken})
  },
  /**
   * If this is called the SDK should be mounted again
   * @param { error: 'CANCELED_BY_USER' | any }
   * @optional
   */
  yunoError: (error) => {
    console.log('There was an error', error)
  },
});

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

Si un objet est retourné, vous pouvez gérer les flux de paiement de votre application nécessitant une gestion de redirection personnalisée. Si null est retourné, aucune action supplémentaire côté commerçant n'est requise.

📘

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 :

• Loader
• Mode de rendu du formulaire
• Configuration du formulaire de carte
  • Texte des boutons de formulaire de paiement
• Personnalisation du SDK

Loader

Contrôlez l'utilisation du loader.

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

Mode de rendu du formulaire

yuno.startCheckout({
  renderMode: {
    /**
     * Type can be one of `modal` or `element`
     * By default the system uses 'modal'
     * It is optional
     */
    type: "modal",
    /**
     * Element where the form will be rendered.
     * It is optional
     * Can be a string (deprecated) or an object with the following structure:
     * {
     *   apmForm: "#form-element",
     *   actionForm: "#action-form-element"
     * }
     */
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
});

Vous trouverez ci-dessous des captures d'écran présentant la différence entre les modes de rendu modal  et  elements pour la liste des méthodes de paiement.

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

Configurations du formulaire de carte

yuno.startCheckout({
  card: {
    type: "extends",
    styles: "",
    texts: {},
  },
});

Textes des Boutons de Formulaire de Paiement

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

Personnalisations du SDK

Utilisez les Personnalisations du SDK pour modifier l'apparence du SDK afin qu'il corresponde à votre marque.

Restez informé

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