Champs Sécurisés (Paiement)

Suivez ce guide étape par étape pour implémenter et activer les fonctionnalités de paiement avec Champs Sécurisés de Yuno dans votre application.

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

Avant de procéder à l'implémentation des Champs Sécurisés, consultez l'Aperçu de l'intégration du SDK pour des instructions détaillées sur la manière d'intégrer correctement le SDK dans votre projet.

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

1. Inclusion directe du script HTML
2. Injection dynamique en JavaScript
3. Installation du module NPM

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 du SDK, vous pouvez passer aux étapes suivantes pour implémenter la fonctionnalité des champs sécurisés.

📘

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 les champs sécurisés avec la clé publique

Dans votre application JavaScript, créez une instance de la classe Yuno 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 : Démarrer le processus de paiement

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

Les paramètres essentiels sont le countrycode, qui détermine le pays pour lequel le processus de paiement est configuré, et la checkoutSession, qui fait référence à la session de paiement actuelle.

Paramètres

Configurez les champs sécurisés avec les options suivantes :

const secureFields = yuno.secureFields({
  countrycode: country,
  checkoutSession,
  installmentEnable: false
});

📘

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 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 les Champs Sécurisés

Après avoir défini les paramètres, vous allez définir, configurer et monter les Champs Sécurisés. Pour chaque Champ Sécurisé, vous devez définir le name  et  options lors de sa création avec la fonction secureFields.create .

Le tableau suivant présente toutes les configurations disponibles :

Une fois que vous avez défini le paramètre, vous afficherez le Champ Sécurisé créé avec la fonction render en sélectionnant un élément HTML à l'aide d'un sélecteur CSS valide (#, ., [data-*]).

Le bloc de code suivant montre un exemple de la configuration des paramètres pour trois Champs Sécurisés, et comment ils sont montés, les champs sont présentés à l'utilisateur :

Paramètres des Champs Sécurisés

Données disponibles dans le rappel onChange

Lorsque le rappel onChange est déclenché, le paramètre data contient :

• Informations IIN de la carte: Détails de l'émetteur de la carte, y compris le schéma, la marque, le type et les informations sur l'émetteur
• Plans de versement: Options de versement disponibles pour le compte si configurées
• États de chargement: isCardIINLoading  et  isInstallmentLoading .

const secureNumber = secureFields.create({
    name: 'pan',
    options: {
      placeholder: '0000 0000 0000 0000',
      styles: ``,
      label: 'Card Number',
      showError: true,
      errorMessage: "Custom Error",
      validateOnBlur: false,
      onChange: ({ error,data }) => {
        if (error) {
          console.log('error_pan')
        } else {
          console.log('not_error_pan')
        }
      },
      onBlur() {
        console.log('blur_pan')
      },
      onFocus: () => {
        console.log('focus_pan')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureNumber.render('#pan')

  const secureExpiration = secureFields.create({
    name: 'expiration',
    options: {
      placeholder: 'MM / YY',
      styles: ``,
      label: 'Card Expiration',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_expiration')
        } else {
          console.log('not_error_expiration')
        }
      },
      onBlur() {
        console.log('blur_expiration')
      },
      onFocus: () => {
        console.log('focus_expiration')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureExpiration.render('#expiration')


  const secureCvv = secureFields.create({
    name: 'cvv',
    options: {
      placeholder: 'CVV',
      styles: ``,
      label: 'CVV',
      showError: true,
      errorMessage: "Custom Error",
      onChange: ({ error }) => {
        if (error) {
          console.log('error_cvv')
        } else {
          console.log('not_error_cvv')
        }
      },
      onBlur() {
        console.log('blur_cvv')
      },
      onFocus: () => {
        console.log('focus_cvv')
      },
      onRenderedSecureField: ()=> {
        console.log('render completed')
      }
    },
  })

  secureCvv.render('#cvv')

Ci-dessous, vous pouvez voir un GIF montrant comment vous pouvez configurer les champs sécurisés :

Étape 5 : Générer un token à usage unique (OTT)

Avec toutes les informations utilisateur en main, vous pouvez démarrer le paiement. Tout d'abord, vous devez créer un Token à Usage Unique en utilisant la fonction secureFields.generateToken. Comme il s'agit d'une fonction asynchrone, vous pouvez utiliser try/catch pour vous assurer que vous gérerez correctement les erreurs déclenchées. L'exemple suivant montre comment créer un token à usage unique à l'aide des informations  vaultedToken  :

📘

Avantages d'utiliser un Token Sécurisé

Lorsque vous utilisez un token sécurisé avec le SDK, toutes les informations de fraude des fournisseurs que vous avez configurés dans votre routage de carte sont collectées et attachées au token à usage unique. De plus, vous pouvez ajouter des informations de versement et un code de sécurité si le fournisseur l'exige.

Paramètres de génération de token

const oneTimeToken = await secureFields.generateToken({
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

Vous pouvez également utiliser secureFields.generateTokenWithInformation 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.

Create a one-time token with error handling:
const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
  cardHolderName: 'John Deer',
  saveCard: true,
  vaultedToken: "aad8578e-ac2f-40a0-8065-25b5957f6555",
  installment: {
            id: string,
            value: number,
            amount: {
                currency: string,
                value: string,
                total_value: string,
            },
        },
  customer: {
    document: {
      document_number: '1090209924',
      document_type: 'CC',
    },
  },
  cardType: 'DEBIT'
})

Étape 6 : Créer le paiement

Après avoir reçu le token à usage unique, vous pouvez créer le paiement en utilisant l'une des options suivantes :

• Créer le paiement à l'aide du endpoint Créer un paiement.
• Utilisez l'endpoint  createPayment .

Les deux options vous obligent à fournir le oneTimeToken  et  checkoutSession. Étant donné que la création du paiement peut générer des erreurs, Yuno vous recommande d'utiliser une fonction try/catch ici.

Ensuite, vous pouvez vérifier le statut du paiement à l'aide de la fonction yuno.mountStatusPayment . L'exemple suivant utilise la fonction createPayment pour créer le paiement et la fonction mountStatusPayment pour afficher le statut du paiement :

Flux de création de paiement

1. Créer le Paiement: Utilisez la fonction createPayment avec le token à usage unique et la session de paiement
2. Vérifier l'action SDK: Si sdk_action_required est true, appeler yuno.continuePayment() pour des actions client supplémentaires.
3. Monter le StatutSi aucune action SDK n'est requise, utilisez yuno.mountStatusPayment() pour afficher le statut du paiement

Paramètres de mountStatusPayment

const payment = await createPayment({ oneTimeToken, checkoutSession })

if (payment.checkout.sdk_action_required) {
      yuno.continuePayment()
} else {
  yuno.mountStatusPayment({
    checkoutSession: checkoutSession,
    countrycode: 'US',
    language: 'en',
    yunoPaymentResult(data) {
      console.log('yunoPaymentResult', data)
    },
  })
}

📘

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

Les Champs Sécurisés de Yuno offrent des services et configurations supplémentaires que vous pouvez utiliser pour améliorer l'expérience client :

• Configurer et utiliser TypeScript
• Conserver les informations de carte de crédit pour réessayer les paiements
• Effacer les valeurs saisies dans les champs de carte
• Focus de saisie
• Forcer la validation
• Définir un message d'erreur personnalisé
• Définir le type de carte

Configurer et utiliser TypeScript

Pour utiliser TypeScript avec le SDK des Champs Sécurisés Yuno, commencez par installer les définitions de types via npm :

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

Après avoir terminé l'installation, incluez les définitions de types dans votre configuration TypeScript. Mettez à jour le fichier tsconfig.json pour inclure @yuno-payments/sdk-web-types dans le tableau des types, comme dans l'exemple suivant :

{
  "compilerOptions": {
    "types": ["@yuno-payments/sdk-web-types"]
  }
}

Une fois les définitions de types installées et configurées, vous pouvez maintenant les utiliser dans votre code. Le bloc de code suivant montre un exemple de la façon d'initialiser Yuno et de créer une instance :

import { YunoInstance } from '@yuno-payments/sdk-web-types/dist/types';

const yunoInstance: YunoInstance = await Yuno.initialize('yourPublicApiKey');

N'oubliez pas de remplacer yourPublicApiKey par votre véritable clé API publique.

Conserver les informations de carte de crédit pour réessayer les paiements

Si une transaction est rejetée, vous pouvez conserver les données de carte de crédit pour réessayer un paiement après que le client ait saisi les détails de la carte de crédit. Pour ce faire, vous devez suivre les étapes ci-dessous :

1. Ajoutez le paramètre présenté dans le bloc de code suivant lors de la création du token à usage unique à l'étape 5. Cela vous permettra de recevoir toute information supplémentaire fournie par le client au moment du paiement, telle que les versements, le type de document ou le numéro de document.

const oneTimeTokenWithInformation = await secureFields.generateTokenWithInformation({ 
  checkoutSession: '{{the checkout session id}}',
})

2. En cas de rejet de la transaction, vous devrez : i. Créer une nouvelle session de paiement. ii. Générer un nouveau token à usage unique. Lors de la génération du token à usage unique, envoyez la nouvelle session de paiement dans le paramètre checkoutSession .
3. Continuez avec la nouvelle session de paiement et le token à usage unique avec le flux de paiement habituel.

Effacer les valeurs saisies dans les champs de carte

En relation avec la fonctionnalité précédente, le commerçant peut configurer pour effacer les informations saisies dans n'importe quel champ de carte. Pour ce faire, il est nécessaire d'exécuter la méthode secureFieldInstance.clearValue(), pour chaque champ que vous souhaitez effacer ou supprimer. L'exemple suivant montre comment :

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.clearValue()

Focus de saisie

Le commerçant peut définir le focus sur une saisie particulière. Pour ce faire, il est nécessaire d'exécuter la méthode secureFieldInstance.focus()pour chaque champ sur lequel vous souhaitez mettre le focus. Le bloc de code suivant montre un exemple :

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.focus()

Forcer la validation

Le commerçant peut forcer la validation d'une saisie particulière. Pour ce faire, il est nécessaire d'exécuter la méthode secureFieldInstance.validate()pour chaque champ que vous souhaitez valider. Le bloc de code suivant montre un exemple :

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.validate()

Définir un message d'erreur personnalisé

peut définir un message d'erreur personnalisé après la validation d'une saisie. Pour ce faire, il est nécessaire d'exécuter la méthode secureFieldInstance.setError()pour chaque champ pour lequel vous souhaitez définir un message d'erreur personnalisé. Le bloc de code suivant montre un exemple :

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.setError('Erreur personnalisée')

Définir le type de carte

Le commerçant  peut définir le type de carte que le client utilise pour le paiement. Pour ce faire, vous devez exécuter la méthode secureFieldInstance.setCardType() et envoyer soit "DEBIT" soit "CREDIT" pour chaque scénario. our chaque scénario. Ceci est utile pour les cartes duales, où la même carte peut être utilisée comme crédit ou débit, comme au Brésil. Le bloc de code suivant montre un exemple :

const secureFieldInstance = secureFields.create({...})
secureFieldInstance.setCardType('CREDIT')

Et après ?

Vous pouvez accéder à d'autres fonctions disponibles sur le SDK Web Yuno :

• Personnalisation du SDK: Modifiez l'apparence du SDK pour qu'il corresponde à votre marque.
• Statut du paiement: Informez l'utilisateur du processus de paiement.

Restez informé

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