Référence API

Intégration In-Page

Intégrez notre solution de paiement directement depuis votre page de paiement

Suggest Edits

Qu'est-ce que In-Page

In-Page est notre solution pour proposer l'expérience Alma depuis votre site marchand.

Concrètement, cela va afficher un premier élément qui va contenir l'échéancier puis au clic sur le bouton "Payer" cela ouvrira une fenêtre modale qui va permettre à vos clients de remplir les différents prérequis Alma pour valider le paiement.

Une fois le paiement terminé, le comportement par défaut est de ramener vers votre page de succès.

Ci-dessous, vous trouverez la documentation technique pour l'installation d'In-Page.

❗️

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

🚧

In-Page supporte les paiements jusqu'à 4 fois, les crédits ne sont pas disponibles.

Installer In-Page

Ajouter ce script qui va utiliser la version 2.x de notre librairie. Cela signifie que vous bénéficierez de nos bugfix automatiquement, mais que si nous créons une version majeure de notre librairie, il faudra remplacer le 2 par un 3. Nous vous préviendrons lorsque cela se produira.

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

Ajouter ensuite l'élément du DOM dans votre HTML qui contiendra notre iframe.

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

Enfin, suivez les étapes suivantes pour afficher l'échéancier du paiement de 210€ en 3 fois : 

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

Avec cette méthode, vous devriez avoir ce rendu :

Puis au clic sur le bouton Payer de votre site, appelez l'api d'Alma pour créer un paiement et au succès de cet appel, ajouter ceci : 

 inPage.startPayment({paymentId: paymentID});

Si vous n'avez pas de bouton "Payer" ou que vous souhaitez configurer la solution différemment, nous allons vous présenter tous les paramètres. Vous trouverez l'exemple avec toutes les options possibles en toute fin de page.

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

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 payer, vous arriverez à l'intérieur de cette méthode, à vous de créer le payement 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"
      //si l'api retourne un code de succès :
      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, vous pourrez appeler notre API qui génère un paiement puis utiliser le payment ID généré pour appeler startPayement

Voici un exemple d'utilisation

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

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

Paramètres optionnels

onPaymentSucceeded: function, optionnel

Cette méthode sera appelée quand le client aura finalisé le 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 spécifiez pas cette méthode, l'utilisateur sera redirigé avec l'URL spécifié dans return_url, que vous avez spécifié lors de la création du paiement.

onPaymentRejected: function, optionnel

Cette méthode fonctionne de la même manière que celle du dessus, seulement celle-ci est appliquée lorsque le paiement a rencontré une erreur. Si vous ne spécifiez pas cette méthode, l'utilisateur sera redirigé vers failure_return_url, que vous avez spécifié lors de la création du paiement.

onUserCloseModal: function, optionnel

Cette fonction sera appelée lorsque l'utilisateur ferme manuellement la modale. Si vous ne le spécifiez pas, aucun comportement par défaut n'est attribué, l'utilisateur pourra de nouveau cliquer sur payer et revenir à l'étape où il était.

unmount

Cette méthode va supprimer tout le contenu relatif à Alma de votre page, il va supprimer 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 le div contenant l'iframe injectée. Autrement, notre iframe prendra toute la taille nécessaire (et pas plus) pour l'affichage de notre site.

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

Cela forcera l'affichage et évitera que notre iframe 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, ajouter la clef style dans la méthode initialize puis la clef embedded, 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",

    // 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, si l'api retourne un code de succès :
      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 : 
  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