SDK Web

Utilisez le DEUNA Web SDK pour afficher le widget de paiement, le coffre-fort de paiement, Click to Pay, les portefeuilles natifs, les codes promotionnels et les actions suivantes dans une fenêtre modale ou à l'intérieur d'une page. Le SDK pour navigateur est distribué sous forme de script classique via le CDN de DEUNA.

Charger le SDK#

Fixez la version du SDK utilisée par votre intégration. Testez une version plus récente dans un environnement de test avant de modifier cette URL en production.

<script
  crossorigin
  src="https://cdn.deuna.io/web-sdk/v1.7/index.js">
</script>

Le script expose le singleton window.DeunaSDK. Il prend également en charge DeunaSDK.newInstance() lorsqu'une page nécessite des instances SDK isolées.

Initialisation#

Initialisez une seule fois avec la clé API publique pour l'environnement sélectionné. Définissez explicitement l'environnement ; le SDK utilise par défaut la production lorsque env est omis.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
});

Ouvrir le widget de paiement#

Créez la commande sur votre backend, renvoyez son jeton au navigateur, puis ouvrez Payment Widget :

await DeunaSDK.initPaymentWidget({
  orderToken,
  language: 'en',
  callbacks: {
    onSuccess: async (order) => {
      await DeunaSDK.close();
      showConfirmation(order);
    },
    onError: (error) => showRetry(error),
    onClosed: (action, metadata) => {
      console.log('Widget closed', action, metadata);
    },
    onEventDispatch: (event, payload) => {
      analytics.track(event, payload);
    },
  },
});

Utilisez le callback pour mettre à jour l'interface. Confirmez et finalisez la commande finale à partir d'un webhook vérifié plutôt que de vous fier uniquement à l'état du navigateur.

Choisissez un mode de présentation#

La fenêtre modale est la valeur par défaut. Le SDK gère l'overlay et close() le ferme.

Pour un widget intégré, utilisez à la fois mode: 'target' et un sélecteur CSS. Ajustez la hauteur du conteneur à partir de onResize pour éviter que le contenu ne soit coupé.

<div id="payment-widget"></div>

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#payment-widget',
  callbacks: {
    onResize: ({height}) => {
      document.querySelector('#payment-widget').style.height = `${height}px`;
    },
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
  },
});

Contrôlez la soumission depuis votre page.#

Masquez le bouton de paiement du widget lorsque votre page effectue l'appel final. Validez avant de soumettre et désactivez votre bouton pendant que la promesse est en attente.

await DeunaSDK.initPaymentWidget({
  orderToken,
  hidePayButton: true,
  callbacks,
});

payButton.addEventListener('click', async () => {
  if (!(await DeunaSDK.isValid())) return;

  payButton.disabled = true;
  const result = await DeunaSDK.submit();
  payButton.disabled = false;

  if (result.status === 'error') showRetry(result);
});

Le widget actif expose également getWidgetState(), refetchOrder()et setCustomStyles(...). Appelez setCustomStyles uniquement depuis les callbacks BIN de la carte ou les callbacks d'installation pour le flux de paiement.

Expériences disponibles#

Coffre-fort de paiement et Paiement en un clic

initElements ouvre le Payment Vault par défaut. Fournissez types pour sélectionner une expérience Elements différente.

await DeunaSDK.initElements({
  orderToken,
  userInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    email: 'ada@example.com',
  },
  types: [{name: 'vault'}],
  callbacks: {
    onSuccess: (credential) => useSavedCredential(credential),
    onError: (error) => showRetry(error),
    onClosed: (action) => console.log(action),
  },
});

Utilisation {name: 'click_to_pay'} pour Click to Pay. Lorsque vous disposez déjà d'un utilisateur DEUNA authentifié, passez userToken au lieu de userInfo.

Apple Pay et Google Pay

Lorsque vous affichez un bouton de portefeuille de propriété du commerçant, vérifiez la disponibilité avant de l'afficher. Effectuez cette étape avant le clic afin que Apple Pay puisse s'ouvrir directement à partir de la geste de l'utilisateur.

const userInfo = {email: 'ada@example.com'};
const availableWallets = await DeunaSDK.getWalletsAvailable({
  orderToken,
  userInfo,
});

applePayButton.hidden = !availableWallets.includes('APPLE_PAY');

applePayButton.addEventListener('click', () => {
  DeunaSDK.initElements({
    orderToken,
    userInfo,
    types: [{name: 'APPLE_PAY'}],
    callbacks: {
      onSuccess: (credential) => useSavedCredential(credential),
      onError: (error) => showRetry(error),
      onClosed: () => showPaymentMethods(),
    },
  });
});

Utilisation GOOGLE_PAY pour le flux Google Pay équivalent. Consultez les guides Apple Pay et Google Pay pour les prérequis pour le commerçant et le navigateur.

Poursuivre une action en attente

Ouvrez la prochaine étape uniquement lorsque la réponse de la commande indique qu'une action du client est toujours requise, telle qu'un défi 3DS ou un redirigement.

await DeunaSDK.initNextAction({
  orderToken,
  callbacks: {
    onSuccess: (order) => showConfirmation(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Ne créez pas une deuxième commande pour cette étape. Réutilisez le jeton pour la commande qui nécessite la prochaine étape.

Ouvrir un bon de réduction

Utilisez l'expérience de la carte cadeau pour les méthodes de paiement en espèces ou par carte cadeau prises en charge.

await DeunaSDK.initVoucherWidget({
  orderToken,
  callbacks: {
    onSuccess: (order) => showVoucherInstructions(order),
    onError: (error) => showRetry(error),
    onClosed: () => showPaymentMethods(),
  },
});

Préparez un widget#

Le widget de paiement et Elements peuvent être créés hors écran lors de l'initialisation et affichés plus tard. Le préchargement réduit le temps perçu de chargement, mais utilise les ressources réseau et du navigateur plus tôt.

await DeunaSDK.initialize({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  env: 'sandbox',
  preloadWidgets: [
    {
      widget: 'payment',
      params: {language: 'en'},
    },
  ],
});

// After the backend returns the order token:
await DeunaSDK.initPaymentWidget({orderToken});

Préparez uniquement l'expérience que le client est susceptible d'ouvrir. L'appel ultérieur initPaymentWidget ou initElements fournit le jeton de commande ou d'utilisateur et révèle le widget préparé.

Données des appareils frauduleux#

Le widget de paiement démarre la collecte de données de l'appareil DEUNA lorsqu'il est ouvert. Si votre flux nécessite l'identifiant avant l'ouverture d'un widget, appelez generateFraudId(...) et envoyez la valeur retournée uniquement via la commande ou le flux de risque documenté.

const fraudId = await DeunaSDK.generateFraudId();

Le comportement spécifique au fournisseur et les versions sont documentés dans Intégrer l'empreinte digitale de l'appareil.

Référence des callbacks et du cycle de vie#

Guides et code associés#