Guides
Référence API

Intégration In-Page

Intégrez le paiement Alma sans redirection

Suggest Edits

Qu'est-ce que In-Page

In-Page est une solution d'intégration Alma conçue pour embarquer l’expérience de paiement directement au sein de votre parcours d’achat, sans redirection.

Lors de l'affichage du paiement, un encart présente le détail des mensualités. En cliquant sur "Payer", une fenêtre modale s’ouvre au sein de la page pour permettre au client de finaliser son achat en toute sécurité.

Une fois le paiement validé, le client est automatiquement redirigé vers votre page de confirmation.

La documentation technique ci-dessous détaille les étapes d'installation, les paramètres disponibles, ainsi que les méthodes pour interagir avec le widget In-Page via votre front-end.

❗️

Lors de la création du paiement, il est obligatoire de définir l'origine du paiement (dans la clé payment) comme online_in_page (i.e. origin: "online_in_page"). Voir la documentation sur l'API

Installer In-Page

Intégrez le script suivant dans votre code pour utiliser la version 2.x de notre librairie. Cette version inclut automatiquement toutes les corrections de bugs publiées.
En cas de mise à jour vers une version majeure (par exemple, la version 3.x), il sera nécessaire de remplacer le 2 par un 3 dans l'URL du script. Vous serez informé à l'avance lorsque cette mise à jour devra être effectuée.

<script src="https://cdn.jsdelivr.net/npm/@alma/[email protected]/dist/index.umd.js"></script>

Insérez un élément div dans votre code HTML qui contiendra l'iframe In-Page.

<div id="alma-in-page"></div>

Ensuite, configurez l'échéancier de paiement sur l'exemple du code suivant, ici un paiement de 210€ en 3 fois : 

const inPage = Alma.InPage.initialize({
    merchantId: "VOTRE ID DE MARCHAND",
    amountInCents: 21000,
    installmentsCount: 3,
    selector: "#alma-in-page",
  });

Une fois cette configuration en place, le widget d'échéancier devrait être affiché à l'endroit défini par votre sélecteur :

Lorsque l'utilisateur clique sur le bouton "Payer" de votre site, appelez l'API d'Alma pour créer un paiement. Après la validation du paiement, utilisez la méthode suivante pour démarrer le processus de paiement In-Page :

 inPage.startPayment({paymentId: paymentID});

Lorsque startPayment est appelé, une modale doit s'ouvrir :

Si vous n'avez pas de bouton "Payer" ou que vous souhaitez configurer la solution différemment, référez-vous aux paramètres détaillés dans la section suivante. Vous trouverez l'exemple avec toutes les options possibles ici.

Alma.InPage

In-Page est composé de 3 méthodes différentes que vous pouvez utiliser.

Initialize

Cette méthode utilise votre marchand ID pour afficher l'échéancier et retourne une variable qui va être utilisé par les autres méthodes.

const inPage = Alma.InPage.initialize({
    merchantId: "VOTRE ID DE MARCHAND",
    amountInCents: 21000,
    installmentsCount: 3,
    selector: "#alma-in-page",
  });

<div id="alma-inpage"></div>

Cette méthode accepte 1 paramètre avec plusieurs attributs :

merchantId: string, requis

amountInCents: number, requis

installmentsCount: number, requis

selector: number, requis

Paramètres optionnels

environment: chaine de caractère (défaut: LIVE ), optionnel

Valeurs :

locale : chaine de caractère (défautFR), optionnel

Pour traduire le contenu de l'iframe dans une autre langue, vous pouvez spécifier une valeur différente ici, voici la liste des valeurs possibles :IT, ES, DE, EN, NL, PT, FR

captureMethod (défaut automatic, optionnel (disponible depuis la version 2.1.0)

Vous trouverez les explications sur cette option sur cette page

Les valeurs possibles sont :automaticet manual

deferredDays (défaut 0, optionnel (disponible depuis la version 2.3.0)

Vous pouvez définir le nombre de jours auquel le client sera prélevé, pour un paiement différé.

Il faut que vous ayez configuré un plan qui corresponde dans votre dashboard

deferredMonths (défaut 0, optionnel (disponible depuis la version 2.3.0)

Vous pouvez définir le nombre de mois auquel le client sera prélevé, pour un paiement différé.

Il faut que vous ayez configuré un plan qui corresponde dans votre dashboard

onIntegratedPayButtonClicked: function de callback, optionnel

Affiche le bouton "Payer" en bas de l'iframe In-Page. Vous pouvez ajouter cette option si vous ne disposez pas de bouton "Payer". Lorsque le client clique sur le bouton, cette méthode est appelée : à vous de créer le paiement puis d'appeler startPayment à l'intérieur de ce callback.

Voici comment utiliser cette option :

const inPage = Alma.InPage.initialize({
    merchantId: "Votre id marchand",
    amountInCents: 20000,  // 200 euros
    installmentsCount: 3, // En 3 fois
    selector: "#alma-in-page",
  
    captureMethod: "manual", // Since 2.1.0
    deferredDays: 0, // Since 2.3.0
    deferredMonths: 0, // Since 2.3.0

    // Je n'ai pas de bouton payer sur mon site : 
    onIntegratedPayButtonClicked: () => {
      // J'appelle l'API pour créer le paiement, n'oubliez pas de précisez origin: "online_in_page"
      // vérifiez que le paymentId existe bien avant d'appeler le startPayment
      if(MON_PAYMENT_ID) {
      	inPage.startPayment({
        	paymentId: MON_PAYMENT_ID, // J'utilise le payment ID généré par l'api au dessus.
      	});
      }
    },
  });

startPayment

Lorsque le client clique sur le bouton "Payer", appelez notre API de création de paiement puis utilisez le payment ID généré dans l'appel à startPayment.

Voici un exemple d'utilisation :

document.getElementById("my-pay-button").addEventListener("click", () => {
  // Appelez l'api de création de paiement.
  // vérifiez que le paymentId existe bien avant d'appeler le startPayment
      if(paymentID) {
      	inPage.startPayment({
        	paymentId: paymentID, // J'utilise le payment ID généré par l'api au dessus.
      	});
      }
});

<button id="my-pay-button">Payer</button>

Paramètres optionnels

onPaymentSucceeded: function, optionnel

Cette méthode est appelée lorsque le client finalise son paiement et que celui-ci s'est bien passé. Vous pouvez surcharger la logique que vous voulez effectuer après le paiement : attention, cela supprimera le comportement par défaut.
Si vous ne définissez pas cette méthode, l'utilisateur sera redirigé avec l'URL spécifié dans return_url, que vous avez renseigné lors de la création du paiement.

onPaymentRejected: function, optionnel

Cette méthode est appelée lorsque le client lorsque le paiement a rencontré une erreur.
Si vous ne définissez pas cette méthode, l'utilisateur sera redirigé vers failure_return_url, que vous avez renseigné lors de la création du paiement.

onUserCloseModal: function, optionnel

Cette méthode sera appelée lorsque l'utilisateur ferme manuellement la modale.
Si vous ne la définissez pas, aucun comportement par défaut n'est attribué : l'utilisateur pourra à nouveau cliquer sur "Payer".

unmount

Cette méthode supprime tout le contenu relatif à Alma de votre page, incluant l'iframe présente sur votre page, la modale ainsi que son contenu et les écouteurs d'événements.

inPage.unmount();

Customiser In-Page

Si vous souhaitez changer la taille de la fenêtre qui apparait sur votre page, vous pouvez définir du CSS sur la div contenant l'iframe injectée.
Autrement, l'iframe prend toute la taille nécessaire (et pas plus) pour l'affichage de notre site.

#alma-in-page {
  height: 400px;
  overflow: auto;
}

Par exemple, ce CSS évite que notre iframe ne se redimensionne en fonction de son contenu.

Vous pouvez également modifier l'apparence de l'échéancier qui apparaît sur votre page (depuis la version 2.3.7).

Pour ce faire, ajoutez la clé style dans la méthode initialize puis la clef embedded :

const inPage = Alma.InPage.initialize({
    merchantId: "Votre id marchand",
    amountInCents: 20000,  // 200 euros
    installmentsCount: 3, // En 3 fois
    selector: "#alma-in-page",

    // Optionnels
  	style: {
    	embedded: {
      	backgroundColor: "red"
    	}
  	}
  // ...
});

Vous pouvez également modifier l'apparence du bouton "Payer" si vous utilisez l'option onIntegratedPayButtonClicked. Voici un exemple : 

const inPage = Alma.InPage.initialize({
    merchantId: "Votre id marchand",
    amountInCents: 20000,  // 200 euros
    installmentsCount: 3, // En 3 fois
    selector: "#alma-in-page",
  
    // I don't have a pay button on my website : 
    onIntegratedPayButtonClicked: () => {
      // see code elsewhere for this
    },
  	style: {
    	embeddedButton: {
      	backgroundColor: "red"
    	}
  	}
});

Exemple détaillé

Voici un exemple avec toutes les options possibles :

const inPage = Alma.InPage.initialize({
    merchantId: "Votre id marchand",
    amountInCents: 20000,  // 200 euros
    installmentsCount: 3, // En 3 fois
    selector: "#alma-in-page",

    // Optionnels
    environment: "PROD",
    locale: 'FR',
  
    // Je n'ai pas de bouton payer sur mon site : 
    onIntegratedPayButtonClicked: () => {
      // J'appelle l'API pour créer le paiement
      if(MON_PAYMENT_ID) {
        inPage.startPayment({
          paymentId: MON_PAYMENT_ID, // J'utilise le payment ID généré au dessus.
          onPaymentSucceeded: () => {
            console.log("succeeded");
          },
          onPaymentRejected: () => {
            console.log("rejected");
          },
          onUserCloseModal: () => {
            console.log("user closed modal");
          },
      	});
      }
    },
  });

  //J'ai un bouton payer sur mon site et l'utilisateur clique dessus
  document.getElementById("pay").addEventListener("click", () => {
    // J'appelle l'API pour créer le paiement, si l'api retourne un code de succès :
    inPage.startPayment({
      paymentId: MON_PAYMENT_ID,
      onPaymentSucceeded: () => {
        console.log("succeeded");
      },
      onPaymentRejected: () => {
        console.log("rejected");
      },
      onUserCloseModal: () => {
        console.log("user closed modal");
      },
    });
  });

Integration custom: Migrer de Fragments à In-Page

1. Remplacer le script de Fragments par celui d’In-page

<script src="https://unpkg.com/@alma/[email protected]/dist/alma-fragments.umd.js"></script>
⬇️
<script src="https://cdn.jsdelivr.net/npm/@alma/[email protected]/dist/index.umd.js"></script>

2. Mise à jour du code

<script>
  const fragments = new Alma.Fragments('<YOUR_MERCHANT_ID>', {
    mode: Alma.ApiMode.TEST,
  })
  const paymentData = getPaymentData()

  fragments.createPaymentForm(paymentData).mount('#alma-payment')
</script>

⬇️

<script>
	const inPage = Alma.InPage.initialize({
	    merchantId: "<YOUR_MERCHANT_ID>",
	    amountInCents: 21000,
	    installmentsCount: 3,
	    selector: "#alma-payment",
			environment: "TEST",
	  });
</script>

Cette fonction permet d’afficher l’échéancier dans l’élément du DOM renseigné dans l’attribut selector.

Vous pouvez trouver votre ID de marchand sur le dashboard.

3. Création du paiement

La différence principale entre Fragments et In-page est ce que Fragments gère la création du paiement, tandis qu’avec In-Page c’est à vous de le créer côté serveur en utilisant l’API de création de paiement. Il faudra ensuite donner à In-page l’ID du paiement créé dans l’étape suivante.

❗️

Il est important de préciser l’origine avec comme valeur online_in_page.

Documentation de création de paiement

Documentation des origines de paiement

4. Affichage du paiement

En utilisant votre propre bouton

document.getElementById('my-pay-button').addEventListener('click', async () => {
		paymentForm.pay()
})
⬇️
document.getElementById("my-pay-button").addEventListener("click", () => {
  // Appelez l'api de création de payement, si l'api retourne un code de succès : 
  if(paymentID) { 
  	inPage.startPayment({paymentId: paymentID});
  }
});

En utilisant le bouton intégré dans l’iframe

Utiliser l’option onIntegratedPayButtonClicked comme défini dans cet example.

Updated about 1 month ago