Accepter un paiement avec Alma

Découvrez comment configurer votre intégration avec Alma.

Web

Mobile

Utilisez le composant Payment Elements pour intégrer un formulaire de paiement Stripe personnalisé à votre site Web ou application. Payment Elements vous permet de prendre en charge Alma et d’autres moyens de paiement automatiquement. Pour les configurations et personnalisations avancées, consultez le guide d’intégration Accepter un Paiement.

Configurer Stripe
Côté serveur

Pour commencer, créez un Compte Stripe.

Utilisez nos bibliothèques officielles pour accéder à l’API Stripe depuis votre application :

Créer un PaymentIntent
Côté serveur

Pour représenter votre intention d’encaisser le paiement d’un client, Stripe utilise un objet PaymentIntent qui suit vos tentatives de débit et les changements d’état du paiement tout au long du processus.

Créez un PaymentIntent sur votre serveur avec un montant et une devise. Dans la dernière version de l’API, le paramètre automatic_payment_methods est facultatif, car Stripe active déjà cette fonctionnalité par défaut. Vous pouvez gérer les moyens de paiement depuis le Dashboard. Stripe gère le renvoi des moyens de paiement admissibles en fonction de facteurs tels que le montant de la transaction, la devise et le tunnel de paiement. Assurez-vous qu’Alma est activé sur la page des paramètres des moyens de paiement.

Définissez toujours le montant à débiter côté serveur car il s’agit d’un environnement sécurisé, contrairement à l’environnement client. De cette façon un client malveillant ne pourra pas fixer son propre tarif.

Dans la dernière version de l’API, la spécification du paramètre automatic_payment_methods est facultative, car Stripe active sa fonctionnalité par défaut.

Récupérer la clé secrète du client

Le PaymentIntent contient une clé secrète à utiliser côté client pour finaliser le processus de paiement en toute sécurité. Vous pouvez adopter différentes approches pour transmettre cette clé secrète côté client.

Récupérez la clé secrète du client à partir d’un endpoint sur votre serveur, à l’aide de la fonction fetch du navigateur. Cette approche est recommandée si votre côté client est une application d’une seule page, en particulier si elle repose sur un framework front-end moderne tel que React. Créez l’endpoint de serveur qui gère la clé secrète du client :

Récupérez ensuite la clé secrète du client à l’aide JavaScript côté client :

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collecter les informations de paiement
Côté client

Collectez les informations de paiement du client avec le Payment Element. Le Payment Element est un composant d’interface utilisateur préconfiguré qui simplifie la collecte des informations pour de nombreux moyens de paiement.

Le Payment Element contient un iframe qui envoie les informations de paiement à Stripe de manière sécurisée via une connexion HTTPS. Évitez de placer le Payment Element dans un autre iframe, car certains moyens de paiement nécessitent une redirection vers une autre page pour la confirmation du paiement.

Pour que votre intégration fonctionne, l’adresse de la page de paiement doit commencer par https:// et non par http://. Vous pouvez tester votre intégration sans utiliser le protocole HTTPS, mais n’oubliez pas de l’activer lorsque vous souhaitez commencer à accepter des paiements réels.

Configurer Stripe.js

Le composant Element Payment est automatiquement disponible en tant que fonctionnalité de Stripe.js. Intégrez le script Stripe.js à votre page de paiement en l’ajoutant entre les balises head de votre fichier HTML. Chargez toujours Stripe.js directement à partir de js.stripe.com pour maintenir votre conformité PCI. Vous ne devez pas inclure le script dans une offre groupée ni en héberger de copie.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Créez une instance de Stripe avec le code JavaScript suivant sur votre page de paiement :

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Ajouter le Payment Element à votre page de paiement

Le composant Element Payment doit avoir un emplacement dédié dans votre page de paiement. Créez un nœud DOM (conteneur) vide doté d’un ID unique dans votre formulaire de paiement :

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

Lors du chargement du formulaire précédent, créez une instance du composant Payment Element et intégrez-la au nœud DOM conteneur. Lorsque vous créez l’instance Elements, transmettez la clé secrète du client définie à l’étape précédente dans les options :

Utilisez la clé secrète du client avec prudence, car elle peut servir à finaliser le paiement. Ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne la dévoilez à personne d’autre que votre client.

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);
// Optional: Autofill user's saved payment methods. If the customer's
// email is known when the page is loaded, you can pass the email
// to the linkAuthenticationElement on mount:
//
//   linkAuthenticationElement.mount("#link-authentication-element",  {
//     defaultValues: {
//       email: 'jenny.rosen@example.com',
//     }
//   })

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Envoyer le paiement à Stripe
Côté client

Utilisez stripe.confirmPayment pour effectuer le paiement à l’aide des informations du composant Payment Element. Ajoutez un paramètre return_url à cette fonction pour indiquer la page vers laquelle Stripe doit rediriger l’utilisateur à l’issue du paiement. Votre utilisateur peut être redirigé en premier lieu vers un site intermédiaire, comme une page d’autorisation bancaire, avant d’être redirigé vers la page spécifiée par le paramètre return_url. L’utilisateur sera immédiatement redirigé vers la page return_url après un paiement réussi par carte.

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Veillez à ce que le paramètre return_url corresponde à une page de votre site web qui indique l’état du paiement. Lorsque Stripe redirige le client vers la page return_url, nous fournissons les paramètres de requête d’URL suivants :

Paramètre	Description
`payment_intent`	L’identifiant unique du `PaymentIntent`.
`payment_intent_client_secret`	La clé secrète du client de l’objet `PaymentIntent`.

Mise en garde

Si vous disposez d’outils qui assurent le suivi de la session navigateur du client, vous devrez peut-être ajouter le domaine stripe.com à la liste d’exclusion des sites référents. Les redirections font que certains outils créent de nouvelles sessions, ce qui empêche le suivi de la session dans son ensemble.

Utilisez l’un des paramètres de requête pour récupérer le PaymentIntent. Consultez l’état du PaymentIntent pour déterminer les informations à présenter à vos clients. Vous pouvez également ajouter vos propres paramètres de requête lorsque vous ajoutez l’URL return_url ; ils seront conservés tout au long du processus de redirection.

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

Rediriger et authentifier des transactions

Les clients peuvent authentifier les transactions Alma avec des applications mobiles ou de bureau. Le client utilisé par l’objet Customer détermine la méthode d’authentification après l’appel de confirmPayment.

Après avoir appelé confirmPayment, les clients sont redirigés vers Alma pour autoriser ou refuser le paiement. Une fois qu’ils ont autorisé le paiement, Stripe les redirige vers la return_url du Payment Intent. Stripe ajoute payment_intent, payment_intent_client_secret, redirect_pm_type et redirect_status comme paramètres de requête d’URL (ainsi que tous les paramètres de requête existants dans la return_url).

Une session d’authentification expire au bout d’une heure, et l’état du PaymentIntent repasse à require_payment_method. Après le changement d’état, le client voit s’afficher une erreur de paiement et doit recommencer le processus de paiement.

FacultatifAutorisation et capture distinctes

FacultatifGérer les événements post-paiement

Tester votre intégration

Pour tester votre intégration, choisissez Alma comme moyen de paiement et appuyez sur Payer. Dans un environnement de test, cette action vous redirige vers une page de paiement test où vous pouvez autoriser ou refuser le paiement.

En mode production, le fait d’appuyer sur Payer vous redirige vers le site Web d’Alma. Vous n’avez pas la possibilité d’autoriser ou de refuser le paiement avec Alma.

Échecs de paiement

Alma utilise plusieurs données pour décider du refus d’une transaction (par exemple, si son modèle d’IA a détecté un risque élevé de fraude pour la transaction, ou si le client a révoqué votre autorisation de débit dans Alma).

Dans ce cas, le PaymentMethod est détaché et le statut de l’objet PaymentIntent passe automatiquement à requires_payment_method.

Hormis le refus d’un paiement, dans le cas d’un PaymentIntent Alma à l’état requires_action, les clients doivent effectuent le paiement sous 1 heure une fois qu’ils ont été redirigés vers Alma. En l’absence d’action sous 1 heure, le PaymentMethod est détaché et l’état de l’objet PaymentIntent passe automatiquement à requires_payment_method.

Dans ce cas, le composant Payment Element affiche des messages d’erreur et demande à votre client de réessayer avec un autre moyen de paiement.

Codes d’erreur

Le tableau suivant détaille les codes d’erreur courants et les actions recommandées :

Code d’erreur	Action recommandée
`payment_intent_invalid_currency`	Saisissez la devise appropriée. Alma prend uniquement en charge `eur`.
`missing_required_parameter`	Consultez le message d’erreur pour en savoir plus sur le paramètre requis.
`payment_intent_payment_attempt_failed`	Ce code peut apparaître dans le champ last_payment_error.code d’un PaymentIntent. Consultez le message d’erreur pour connaître la raison détaillée de l’échec et obtenir une suggestion de traitement de l’erreur.
`payment_intent_redirect_confirmation_without_return_url`	Spécifiez une URL de retour `return_url` lors de la confirmation d’un PaymentIntent avec Alma.