NAV Navbar

Guide d'intégration

Ce guide est à destination des marchands et développeurs souhaitant étudier ou implémenter le paiement en plusieurs fois avec Alma sur leur plateforme sans passer par l'une des intégrations fournies par Alma.

Il explique le fonctionnement général du système de paiement en plusieurs fois, et détaille l'implémentation attendue ainsi que les appels API nécessaires à celle-ci.

Compte Alma et Sandbox

Vous devez posséder un compte Alma activé pour utiliser notre API.

Vous pouvez créer votre compte Alma en 1 minute ici.
Nous mettons également à votre disposition un environnement de test (la "sandbox"), sur lequel vous pouvez créer un compte ici.
Les comptes de production et les comptes sandbox sont totalement indépendants.

Fonctionnement général

Parcours utilisateur

Parcours utilisateur

Jusqu'au choix du moyen de paiement, le parcours d'un utilisateur reste inchangé et propre à l'implémentation du tunnel d'achat faite par le marchand sur son site. Lorsque l'utilisateur choisit de payer en plusieurs fois avec Alma, il est redirigé vers une page de paiement hébergée par Alma qui reprend ses informations (nom, adresse, email…) et affiche un échéancier de paiement :

Échéancier de paiement

Si jamais des informations manquent, elles peuvent être remplies sur cette page avant de valider le paiement. Pour limiter les opportunités de fraude, toute information transmise par le marchand à Alma en amont de la redirection ne peut être modifiée par l'utilisateur.

Lorsque l'utilisateur valide son paiement par carte bancaire, Alma utilise ses propres algorithmes afin de détecter les risques de fraude, et valider ou non la mise en place de l'échéancier.

Deux issues sont alors possibles :

Paiement accepté

Paiement accepté

Le paiement a été accepté sans réserve et l'échéancier est installé.
L'utilisateur est redirigé vers le site marchand qui valide la commande, et il recevra rapidement un email avec tous les détails de son paiement échelonné.

Informations supplémentaires requises

Dans de rares cas, nous ne pouvons valider la demande de paiement en plusieurs fois pour certains clients.
Un parcours spécifique est mis en place dans cette situation, offrant au client différentes alternatives.
Ce parcours est décrit en annexe de ce document.

Intégrations et API

Alma travaille à fournir des intégrations prêtes à être utilisées pour les plateformes e-commerce les plus répandues, telles que PrestaShop, WooCommerce, Magento, Shopify, …

Si nous ne fournissons pas d'intégration pour votre plateforme ou que vous avez développé votre site de zéro, vous pouvez vous interfacer directement avec notre API pour intégrer Alma à vos options de paiement.

Clefs d'API

Dans les deux cas, vous aurez besoin d'une clef d'API pour identifier votre compte marchand auprès de l'API.

Ces clefs sont accessibles dans votre dashboard à l'adresse https://dashboard.getalma.eu/api (et https://dashboard.sandbox.getalma.eu/api pour la clef de test).

Clef d'API

Implémentation

Clients d'API

Nous fournissons un client d'API PHP sur Github : https://github.com/alma/alma-php-client
Celui-ci permet de suivre les détails d'implémentation ci-dessous de façon simplifiée en s'abstrayant des détails des requêtes HTTP.
Par exemple pour vérifier l'éligibilité d'une commande et créer le paiement correspondant chez Alma :

<?php
$alma = new Alma\API\Client($apiKey, ['mode' => Alma\API\TEST_MODE]);

// Fetch payment data from your backend
$paymentData = dataFromCart();
$eligibility = $alma->payments->eligibility($paymentData);

if($eligibility->isEligible) {
    $payment = $alma->payments->createPayment($paymentData);
    redirect_to($payment->url);    
}

Notez que $paymentData est un tableau associatif qui doit suivre le format JSON décrit dans Créer un Payment

Environnement de test

Nous mettons une "sandbox" à disposition pour vos tests et développements : https://dashboard.sandbox.getalma.eu.
Vous pouvez y créer votre compte de test et utiliser sa clef d'API pour le mode test de vos intégrations.

Authentification des appels API

Lorsqu'un appel à l'API doit être authentifié, il faut ajouter le header suivant à la requête HTTP:

Header Valeur
Authorization Alma-Auth <API key>

Tous les appels authentifiés doivent se faire depuis vos serveurs, afin d'assurer la sécurité de la clef d'API et ainsi d'éviter toute utilisation frauduleuse de votre accès à l'API Alma.
Si un appel authentifié échoue pour des raisons d'authentification, la réponse sera :

   
Code HTTP 401
{
  "message": "API key is invalid or not supplied"
}

Représentation des données

Généralités

Pour tous les appels à l'API effectués en POST, les paramètres de l'appel doivent être passés en JSON dans le corps de la requête.
Par exemple :

{
    "payment": {
        "amount": 34500
    }
}

Headers HTTP

Il est impératif de spécifier le header HTTP suivant dans vos requêtes :

Header Valeur
Content-type application/json

Types de données spécifiques

Montants

Tous les montants sont convertis en centimes et exprimés en entiers (int).
Ainsi, une commande de 199.90€ est représentée par la valeur 19990.

<?php
function price_to_cents($price)
{
    return (int)(round($price * 100));
}

Adresses

Toutes les adresses sont représentées par des objets avec leurs champs séparés.
Vous trouverez les attributs acceptés dans la représentation d'une adresse à la section Créer une Address

Client

Un objet client est généralement envoyé en même temps que les détails d'un paiement lors de la création de celui-ci, ainsi que sur les vérifications d'éligibilité.
L'objet reprend les détails classiques fournis par un client dans votre tunnel de paiement (Nom, prénom, adresse, ...).
Vous trouverez les attributs acceptés dans la représentation d'un client dans la section Créer un Payment.

Paiement

Un objet paiement contient les informations typiques d'un e-commerce (adresses de livraison et facturation, identité du client, ...), qui sont passées lors de la création de celui-ci, mais aussi les informations liées au système de paiement en plusieurs fois : échéancier, frais, etc.

Création d'un paiement

Les attributs d'un objet paiement à fournir sur les appels d'éligibilité et de création de paiement sont détaillés dans la référence de l'API à la section Créer un Payment.

Représentation complète

Lorsque vous récupérez un objet Payment via l'API, il contient plus d'attributs que ceux fournis lors de la création. La liste complète des attributs est décrite à la section Payment

Exemple d'un objet Payment complet :

{
    "id": "payment_11gJxYm2LM9Gt9VyWOaY4kWQ4eC4r2sHpU",
    "mode": "insured",
    "state": "in_progress",
    "created": 1547562399,
    "url": "https://pay.getalma.eu/11gJxYm...",
    "return_url": "https://myshop.com?pid=payment_11gJxYm...",
    "customer_cancel_url": "https://myshop.com/cart?pid=payment_11gJxYm...",
    "purchase_amount": 10000,
    "customer_fee": 0,
    "payment_plan": [
      {
          "customer_fee": 0,
          "due_date": 1547562399,
          "purchase_amount": 3333,
          "state": "paid"
      },
      {
          "customer_fee": 0,
          "due_date": 1550240799,
          "purchase_amount": 3333,
          "state": "pending"
      },
      {
          "customer_fee": 0,
          "due_date": 1552659999,
          "purchase_amount": 3333,
          "state": "pending"
      }
    ],
    "custom_data": { ... },
    "customer": { ... },
    "shipping_address": { ... },
    "billing_address": { ... }
  }

Intégration dans le tunnel d'achat

L'intégration d'Alma à un site marchand se passe en plusieurs étapes :

  • Vérification de l'éligibilité de la commande au paiement en plusieurs fois
  • Création du paiement chez Alma pour la commande en cours
  • Redirection vers la page de paiement
  • Vérification du paiement lors du retour depuis la page de paiement

Ces quatre étapes sont détaillées ci-après, avec le détail des appels API pertinents.

Éligibilité du paiement

Cette étape, bien que facultative, est fortement recommandée car elle permet de ne présenter le bouton de paiement en plusieurs fois que lorsqu'il est effectivement possible de proposer ce mode de paiement. Cela évitera notamment des frustrations aux clients, et donc potentiellement une perte de conversions.

Les cas de non-éligibilité sont :

  • Un problème avec le compte marchand (compte non activé, pièces manquantes, …)
  • Un montant inférieur/supérieur au minimum/maximum autorisé pour le paiement en plusieurs fois (contractualisé avec le marchand)
  • Une forte suspicion de fraude

L'appel à effectuer à l'API est décrit dans la référence de l'API à la section Vérifier l'éligibilité d'un achat.

Dans la plupart des cas, les contraintes renvoyées avec la réponse permettent d'identifier la raison de la non-éligibilité, et de l'indiquer au client.
Les codes d'erreur pour les différents champs sont donnés à titre indicatif ; pour des raisons de sécurité, nous déconseillons d'en afficher les valeurs au client final, ou d'adapter vos messages d'erreur en fonction de ces codes.

Création du paiement

Lorsque vous affichez un bouton de paiement en plusieurs fois et que l'utilisateur clique dessus, vous devez dans un premier temps créer un objet paiement via notre API, qui contiendra les informations de la commande et du client.
Si cet objet paiement est correctement créé vous pourrez alors exécuter l'étape suivante. Dans le cas contraire et en fonction de l'erreur rencontrée, vous devrez inviter l'utilisateur :

  • Soit à corriger ses informations
  • Soit à choisir un autre mode de paiement

Consulter la section Créer un Payment de la référence de l'API pour les détails de l'appel API à effectuer.

Redirection vers la page de paiement

Description

Dès que le paiement est créé (i.e. dans la même requête HTTP initiée par le clic sur le bouton de paiement), utilisez le champ url du JSON renvoyé par l'appel à l'API précédent pour renvoyer votre client vers notre page de paiement.

L'implémentation dépend du langage, du framework ou de la plateforme utilisés côté backend.
L'important est que la réponse finale au clic sur le bouton de paiement soit :

   
Code HTTP 302
Location (header) <payment.url>
Exemple Location: https://pay[.sandbox].getalma.eu/payment_11gJxYm2LM9Gt9VyWOaY4kWQ4eC4r2sHpU

Vérification du paiement

Description

Afin de s'assurer qu'il n'y a aucune tentative de fraude, il convient de vérifier que le montant total payé et le montant du panier en cours sur votre boutique correspondent bien avant de valider la commande définitivement.
À cette fin nous transmettons à vos serveurs l'ID du paiement validé à deux occasions une fois la carte bancaire du client débitée.

Callback IPN

Appel asynchrone

Si une URL de callback IPN a été fournie (configurée dans la dashboard ou dans les attributs du paiement), elle sera appelé de façon asynchrone juste après l'exécution du paiement par notre API :

   
Méthode GET
URL <ipn_callback_url>?pid=<pid>

L'ID du paiement est ajouté aux paramètres de l'URL afin que vous puissiez faire les vérifications nécessaires de votre côté.

Réponse à la callback

Votre serveur doit répondre à l'appel de la callback IPN selon deux cas de figure :

  1. Le paiement est valide et la commande peut être confirmée (ou bien la commande est déjà dans l'état souhaité de votre côté) : renvoyez un code HTTP 200 en réponse
  2. Une erreur est survenue de votre côté ou vous détectez une fraude potentielle : renvoyez un code HTTP d'erreur quelconque (entre 400 et 600 donc).

En cas d'erreur, vous pouvez inclure dans votre réponse un objet JSON décrivant le problème.
Par exemple :

{
  "error": "Database connection error"
}

Nouvelles tentatives

En cas de problèmes de connectivité (serveur KO, problème réseau, …) ou si votre serveur nous renvoie un code d'erreur en réponse à l'appel de la callback IPN, notre système planifiera automatiquement une nouvelle tentative d'appel de la callback dans les 30 secondes qui suivent.
En cas d'erreurs répétées, nous réessayons un maximum de 20 fois, avec un délai de plus en plus long entre chaque tentative.

Retour client

Une fois le paiement exécuté, nous redirigeons le client vers votre boutique en utilisant l'URL fournie dans return_url lors de la création du paiement :

   
Méthode GET
URL <return_url>?pid=<pid>

Validation du paiement

L'appel à la callback IPN étant asynchrone, nous vous encourageons à procéder à la vérification du paiement dès lors que l'URL de retour que vous avez choisie contient le paramètre pid que nous y ajoutons.

Il est tout à fait possible de n'afficher qu'un écran de confirmation de commande sans passer par cette validation, mais si le premier appel à la callback IPN devait tarder à arriver, vos clients pourraient trouver dans leur compte une commande encore non validée, alors que le paiement a été effectué et qu'ils viennent de voir une page de confirmation.
Valider la commande dès le retour client permet d'éviter cette situation, qui peut être anxiogène pour votre client.

La validation du paiement suit la même au retour du client et sur la callback IPN, et le code peut donc être partagé :

  • Si la commande est déjà validée : sortir immédiatement et afficher la confirmation de commande (ou renvoyer 200 OK dans le cas de la callback IPN)
  • Si la commande n'est pas encore validée : utiliser pid pour valider le paiement avant de continuer (détaillé ci-après)
  • Si la commande est dans un autre état (annulée, par exemple) : informer le client de l'erreur, ou renvoyer 200 OK dans le cas de la callback IPN (pour éviter de nouvelles tentatives inutiles)

Que ce soit au niveau de la callback IPN ou au retour du client, vous pouvez utiliser le paramètre pid pour récupérer l'objet Payment et procéder aux vérifications suivantes :

  • payment.state — vérifiez que la valeur soit bien "in_progress" ou "paid" (dans le cas où le client a finalement payé en une seule fois via Alma)
  • payment.purchase_amount — vérifiez que cette valeur corresponde à la valeur du panier (convertie en centimes). Si ce n'est pas le cas, vous êtes très probablement face à une tentative de fraude.
  • payment.payment_plan[0].state — vérifiez que la valeur soit bien "paid"

Annexe - clients non éligibles

Dans de rares cas, nous ne sommes pas en mesure d'accéder à la demande de certains clients de payer leur achat en plusieurs fois.
Nous avons mis en place un parcours spécifique pour permettre aux clients dans cette situation de :

  • Nous fournir plus d'informations qui permettraient de valider le paiement en plusieurs fois
  • Ou bien de payer en une seule fois leur commande

Informations supplémentaires requises

Informations supplémentaires requises

Nos algorithmes n'ont pas pu valider le paiement échelonné directement (les raisons peuvent varier et dépendre notamment de suspicions de fraude).
Nous proposons alors deux options à l'utilisateur :

  • Nous donner accès à ses mouvements bancaires des trois derniers mois via un partenaire sécurisé (Budget Insight) afin que nous puissions confirmer que ses ressources lui permettent de rembourser le paiement.
  • Payer la totalité de la somme en une seule fois s'il ne souhaite pas fournir ses informations bancaires. Dans ce cas, si le marchand avait décidé de faire porter une partie des frais de paiement sur ses clients, ceux-ci ne sont pas appliqués.

Si l'utilisateur choisit de fournir ses informations bancaires, nous lui fournissons un maximum d'éléments explicatifs quant à la finalité de ces informations et à la sécurité de l'opération : Détails Budget Insight

Le lien "Comment ça marche ?" apporte plus de détails : Comment ça marche

Le but étant de rassurer au maximum l'utilisateur afin de ne pas perdre une conversion à ce stade.
Si l'utilisateur choisit le paiement en une seule fois, nous prélevons le montant total (sans frais de paiement) sur sa carte bancaire puis il est redirigé vers le site marchand, où la commande est validée.
Si l'utilisateur choisit de fournir ses informations bancaires, nous le redirigeons vers la plateforme de notre partenaire Budget Insight, où il entre ses informations de façon sécurisée afin que nous récupérions son historique d'opérations bancaires sur les 3 derniers mois.

Budget Insight

Une fois cette opération effectuée, soit le paiement est finalement accepté, soit nous sommes contraints de le refuser face à un manque d'informations ou à des ressources insuffisantes.

Refus d'échelonnement

Si nous ne sommes pas en mesure d'accepter le paiement en plusieurs fois, l'utilisateur en est informé et peut une dernière fois choisir de payer en une seule fois :

Paiement refusé