Seamless SDK (paiement en ligne)

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

👍
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.

📘
Devrais-je utiliser le Lite ou le Full Seamless SDK ?
Utilisez le Full Seamless SDK pour le listage automatique des méthodes de paiement et l'affichage séparé des boutons de paiement (comme PayPal). Le Lite Seamless SDK vous donne plus de contrôle sur la manière dont les méthodes de paiement sont affichées et organisées.

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

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

Inclusion directe du script HTML
Injection dynamique en JavaScript
Installation du module NPM

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

📘
Bibliothèque TypeScript
Si vous utilisez TypeScript, Yuno propose une bibliothèque qui donne accès à toutes les méthodes disponibles dans le SDK Web de Yuno.

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

Initialisez le SDK Yuno dans votre application JavaScript en fournissant une PUBLIC_API_KEY:

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

📘
Identifiants
Pour plus d'informations, Consultez la page des identifiants : https://docs.y.uno/reference/authentication

Étape 3 : Créer une session de paiement

📘
Si votre flux de travail nécessite l'envoi du additional_data objet, il peut être envoyé dans le cadre de la session de paiement.

Pour initialiser le flux de paiement, créez une nouvelle checkout_session à l'aide du endpoint Créer une session de paiement .

Tout d'abord, créez un client ou récupérez un ID client existant.
Incluez-le lors de la création de la checkout_session

💳
Pour contrôler l'autorisation et la capture avec les cartes, inclure payment_method.detail.card.capture dans la session de paiement : définir false autoriser uniquement, true à capturer immédiatement.

Paramètres clés

Paramètres	Requis	Description
`amount`	Oui	L'objet montant de la transaction principale contenant la `currency` (code ISO 4217) et la `value` (montant numérique dans cette devise).
`alternative_amount`	Non	Une représentation de la devise alternative du montant de la transaction avec la même structure que `amount` (`currency` et `value`). Utile pour les scénarios multi-devises, comme l'affichage des prix aux clients dans leur devise préférée (par exemple, USD) tout en traitant le paiement dans la devise locale (par exemple, COP).

📘
onPaymentMethodSelect É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 startSeamlessCheckout avant mountSeamlessCheckout.

📘
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 : Démarrer le processus de paiement

Utilisez la configuration ci-dessous pour offrir une expérience de paiement transparente et conviviale à vos clients :

yuno.startSeamlessCheckout({
  checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
  elementSelector: "#root",
  countryCode: "US",
  language: "en-US",
  showLoading: true,
  issuersFormEnable: true,
  showPaymentStatus: true,
  onLoading: (args) => console.log(args),
  renderMode: {
    type: "modal",
    elementSelector: {
      apmForm: "#form-element",
      actionForm: "#action-form-element",
    },
  },
  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
  },
  texts: {},
  async yunoCreatePayment(oneTimeToken, tokenWithInformation) {
    await createPayment({ 
      oneTimeToken, 
      checkoutSession,
      vault_on_success: true 
    });
    yuno.continuePayment({ showPaymentStatus: true });
  },
  yunoPaymentMethodSelected(data) {
    console.log("Payment method selected:", data);
  },
  yunoPaymentResult(data) {
    console.log("Payment result:", data);
    yuno.hideLoader();
  },
  yunoError(error, data) {
    console.error("An error occurred:", error);
    yuno.hideLoader();
  },
});

Lors de l'utilisation de startSeamlessCheckout, spécifiez les rappels pour gérer les paiements. Vous pouvez également personnaliser l'interface de paiement à l'aide des objets texts .

Paramètres

Configurez le paiement transparent avec les options suivantes :

Paramètres	Description
`checkoutSession`	Fait référence à la session de paiement. Exemple : `438413b7-4921-41e4-b8f3-28a5a0141638`.
`elementSelector`	L'élément HTML où le paiement sera rendu.
`countryCode`	Ce paramètre indique le pays pour lequel le processus de paiement est configuré. Utilisez une valeur `ENUM` représentant le code pays souhaité. Vous trouverez la liste complète des pays pris en charge et de leurs codes correspondants sur la page Couverture par Pays .
`language`	Langue pour les formulaires de paiement. Utilisez n'importe quel code répertorié dans Langues prises en charge. Exemple : `en-US`. La langue du navigateur est utilisée par défaut lorsqu'elle est disponible.
`showLoading`	Contrôle la visibilité de la page de chargement/spinner de Yuno pendant le processus de paiement. Valeur par défaut : `true`.
`onLoading`	Nécessaire pour recevoir des notifications sur les appels au serveur ou les événements de chargement pendant la procédure de paiement.
`issuersFormEnable`	Active le formulaire de l'émetteur (par exemple, une liste de banques). Par défaut : `true`.
`showPaymentStatus`	Affiche la page de statut de paiement Yuno, utile lors de la continuation d'un paiement. Par défaut : `true`.
`showPayButton`	Contrôle la visibilité du bouton de paiement dans le formulaire du client ou de la carte. Par défaut : `true`.
`renderMode`	Spécifie comment et où les formulaires seront rendus. Les options disponibles sont les suivantes :
	▪️ `type: modal` (par défaut)
	▪️ `type: element` - Si vous sélectionnez `element`vous devez informer le `elementSelector` pour spécifier l'endroit où le formulaire doit être rendu.
`card`	Définit la configuration du formulaire de la carte. Il contient des paramètres tels que le mode de rendu, les styles personnalisés, l'option d'enregistrement de la carte, facultatif. `cardNumberPlaceholder` pour personnaliser le texte de remplacement du champ du numéro de carte, et facultatif `hideCardholderName` pour masquer le champ du nom du titulaire de la carte. Le `cardNumberPlaceholder` prend en charge les caractères alphanumériques, les espaces et les caractères UTF-8 pour la localisation. Si ce n'est pas fourni, le SDK utilise le paramètre de remplacement anglais par défaut (« Numéro de carte »). Lorsque `hideCardholderName` est fixé à `true`, le champ du nom du titulaire de la carte n'est pas affiché. Lorsqu'il n'est pas spécifié ou défini sur `false`, le champ du nom du titulaire de la carte s'affiche (comportement par défaut). Le fait de masquer ce champ n'a aucune incidence sur le PAN, la date d'expiration, la collecte du CVV, la logique BIN ou les validations 3DS/fournisseur.
`texts`	Permet de définir des textes de boutons personnalisés pour les formulaires de paiement par carte et sans carte.
`yunoCreatePayment`	Fonction de remplacement pour créer un paiement. Cette fonction ne sera pas appelée, mais doit être implémentée. Lors de la création du paiement, vous pouvez inclure `vault_on_success: true` pour enregistrer le mode de paiement après un paiement réussi. Voir Enregistrement des modes de paiement pour plus de détails.
`yunoPaymentMethodSelected`	Rappel invoqué lorsqu'une méthode de paiement est sélectionnée, ainsi que le type et le nom de la méthode.
`yunoPaymentResult`	Rappel appelé une fois le paiement effectué, avec le statut du paiement (par exemple, `SUCCEEDED`, `ERROR`).
`yunoError`	Rappel invoqué en cas d'erreur dans le processus de paiement. Reçoit le type d'erreur et des données supplémentaires facultatives.

📘
Transactions initiées par le client et par le commerçant
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 sur cette page fait référence à une transaction initiée par le client sans option de récurrence. Typiquement, il est utilisé pour les achats uniques en ligne, les achats en magasin, les retraits aux guichets automatiques, etc.

Étape 5 : Monter le SDK

Pour présenter le processus de paiement basé sur la méthode de paiement sélectionnée, utilisez la fonction yuno.mountSeamlessCheckout() . Cette étape garantit que le SDK est correctement monté sur l'élément HTML choisi.

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

Consultez la page Type de paiement pour voir la liste complète des types de méthodes de paiement que vous pouvez utiliser lors du montage du SDK.

Le champ vaultedToken est facultatif. Il représente une méthode de paiement précédemment enregistré. Si vous fournissez le vaultedToken, l'utilisateur n'aura pas besoin de fournir à nouveau les informations de paiement puisqu'elles ont été fournies lors d'une transaction précédente.

Après le montage, vous devez démarrer le flux de paiement en appelant yuno.startPayment(). Si vous ignorez cet appel, le formulaire de paiement ne s'ouvrira pas.

Étape 6 : Démarrer le flux de paiement (Requis)

Appelez yuno.startPayment() immédiatement après yuno.mountSeamlessCheckout() pour ouvrir l'interface utilisateur de la méthode de paiement sélectionnée :

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

yuno.startPayment();

Alternativement, vous pouvez déclencher le démarrage à partir d'une action utilisateur, telle qu'un clic sur un bouton :

const payButton = document.querySelector('#button-pay');
payButton.addEventListener('click', () => {
  yuno.startPayment();
});

📘
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.

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

Paramètres	Description
`paymentMethodType`	Le type de mode de paiement. Doit être soit `'APPLE_PAY'` ou `'GOOGLE_PAY'`.
`elementSelector`	Le sélecteur CSS pour l'élément HTML où le bouton doit être affiché (par exemple, `'#apple-pay'`, `'.button'`).

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();

Enregistrement des modes de paiement dans un flux transparent

Vous pouvez enregistrer des modes de paiement (cartes de magasin pour une utilisation future) directement pendant le processus de paiement fluide en définissant payment_method.vault_on_success = true dans le paramètre Création d'une session de paiement.

Lorsque vault_on_success est fixé à true:

Le mode de paiement sera automatiquement enregistré si le statut du paiement est SUCCEEDED
Si le paiement échoue, aucun transfert ne sera effectué.
La réponse de paiement comprendra un vaulted_token que vous pouvez utiliser pour de futures transactions

Exemple :

{
    "account_id": "...",
    ...
    "payment_method": {
        "vault_on_success": true
    }
}

📘
Exigences en matière de saut
Pour générer et recevoir un vaulted_token quand vault_on_success = true, le paiement doit faire référence à un client Yuno existant via customer_payer.id dans la session de paiement. La création ou l'envoi des données client en ligne dans la demande de paiement ne crée pas le client de notre côté, donc aucun stockage ne sera effectué.

Pour plus d'informations sur l'enregistrement des modes de paiement, consultez la section Enregistrer les modes de paiement.

Restez informé

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

SDK recommandé

Devrais-je utiliser le Lite ou le Full Seamless SDK ?

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

Bibliothèque TypeScript

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

Identifiants

Étape 3 : Créer une session de paiement

Paramètres clés

onPaymentMethodSelect Événement

Affichage Google Pay et Apple Pay

Étape 4 : Démarrer le processus de paiement

Paramètres

Transactions initiées par le client et par le commerçant

Étape 5 : Monter le SDK

Étape 6 : Démarrer le flux de paiement (Requis)

Application Démo

Monter les boutons externes

Paramètres

Boutons de démontage

Enregistrement des modes de paiement dans un flux transparent

Exigences en matière de saut

Restez informé

`onPaymentMethodSelect` Événement