Vérifier l'éligibilité d'un achat

Présentation

Ce endpoint permet d'obtenir les différents produits Alma éligibles à un montant d'achat donné.

Il y a deux façons de l'utiliser :

Requêtes : l'attribut queries permet de spécifier les produits Alma à évaluer, en précisant leurs caractéristiques pour chaque requête. L'API répond alors avec le résultat d'éligibilité pour chaque requête, et exclusivement pour les requêtes envoyées.
"Découverte" : sans fournir de requête, l'API répond alors avec tous les produits Alma éligibles (et uniquement ceux éligibles) pour le montant donné et éventuellement l'origine spécifiée, le pays de l'adresse de facturation ou livraison, etc.

Le mode "découverte" permet de construire une page ou un module de paiement dynamique, capable de s'adapter aux produits Alma effectivement activés sur le compte marchand.
C'est une fonctionnalité régulièrement utilisée dans les intégrations aux logiciels de caisse.

Requêtes

"Découverte"

Toute requête à cette API qui ne contient pas d'objet "queries" correspond à une requête de découverte des produits Alma disponibles pour les paramètres donnés.

Sont alors pris en compte le montant de l'achat, son origine (en ligne ou en magasin), les adresses de facturation/livraison etc. La réponse contiendra l'ensemble des produits Alma éligibles (et uniquement ceux-ci) activés sur le compte.

Requêtes spécifiques

La plupart du temps, l'objectif est d'obtenir une réponse d'éligibilité pour un ou plusieurs produits Alma spécifiques, en fonction des règles métiers du marchand et de ses choix en matière de modes de paiement proposés aux clients.

Il convient alors d'utiliser l'attribut "queries" pour obtenir spécifiquement le résultat d'éligibilité de ces produits.

Dans ce cas, la réponse contient le même nombre d'objets de résultat d'éligibilité qu'il y a d'objets de requêtes, et dans le même ordre.

Voici un exemple de requêtes pour évaluer l'éligibilité du paiement en 3x, 4x et différé de 15 jours :

{
    "purchase_amount": 81700,
    "queries": [
        {
            "installments_count": 3,
        },
        {
            "installments_count": 4,
        },
        {
            "installments_count": 1,
            "deferred_days": 15
        }
    ]
}

Réponse

La réponse de l'API est une liste de résultats d'éligibilité pour chacun des produits Alma requêtés ou disponibles.

Chaque résultat d'éligibilité reprend les caractéristiques du produit concerné, un flag "eligible" indiquant l'éligibilité ou non, et un ensemble d'informations en fonction de cette éligibilité, comme décrit ci-dessous :

Champ	Type	Description	Valeur du champ eligible si concerné
eligible	boolean	Indique si le plan trouvé est eligible ou non.	NC
deferred_days	integer	Nombre de jours de décalage pour du paiement différé.	NC
deferred_months	integer	Nombre de mois de décalage pour du paiement différé.	NC
installments_count	integer	Nombre d'échéances dans l'échéancier (3 par défaut).	NC
customer_total_cost_amount	integer	Montant total des frais et intérêts payés par le client en centimes. Les intérêts sont calculés à partir d'un échéancier commençant à la date de l'appel à eligibility.	`true`
customer_total_cost_bps	integer	Pourcentage en bps de la part de frais et intérêts payés par le client. Les intérêts sont calculés à partir d'un échéancier commençant à la date de l'appel à eligibility. Dans le cas du p3x et p4x cela correspond le plus souvent au customer_fee_variable. Pour du crédit (plus de 4 fois) cette valeur change en fonction du calcul des intérêts et donc de la date de début de l'échéancier. Elle a alors une valeur pédagogique mais n'est pas contractuelle. Il n'est donc pas recommandé de l'afficher dans le parcours de paiement.	`true`
payment_plan	Array of Objects	Liste des échéances pour cet achat. Ce champ est disponible uniquement si eligible est à true.	`true`
payment_plan.purchase_amount	integer	Montant de la part de capital remboursé par l'échéance, en centimes.	`true`
payment_plan.customer_fee	integer	Éventuels frais de paiement appliqués au client sur cette échéance, en centimes.	`true`
payment_plan.customer_interest	integer	Éventuels intérêts appliqués au client sur cette échéance, en centimes. Les intérêts sont calculés à partir d'un échéancier commençant à la date de l'appel à eligibility.	`true`
payment_plan.total_amount	integer	Montant de l'échéance total en centimes. Cela inclus le capital remboursé, les frais et les intérêts de l'échéance.	`true`
payment_plan.due_date	timestamp	Date à laquelle le paiement de cette échéance est dû.	`true`
constraints	Dict[str, Dict[str, integer]]	Contraintes que la requête à manquer de satisfaire, cause de l'inéligibilité (voir ci-dessous)	`false`
reasons	Dict[str, str]	Raison de l'inéligibilité (voir ci-dessous)	`false`

Contraintes et raisons d'inéligibilité

Lorsqu'un résultat d'éligibilité est négatif, l'objet portant ce résultat contient notamment deux attributs :

constraints
reasons

Ces deux attributs permettent de déterminer la raison de l'inégibilité et, la plupart du temps, d'informer précisément le client de cette raison.

reasons
Cet objet renseigne l'attribut qui a provoqué l'inéligibilité (en clef) et le code d'erreur associé (en valeur) :

Attribut	Erreur	Signification
`merchant`	`merchant_cant_create_payments`	L'acceptation des paiements a été désactivée sur votre compte. Contactez le support.
`installments_count`	`invalid_value`	Le nombre d'échéances demandé dans la requête d'éligibilité n'est pas activé/autorisé sur le compte.
`purchase_amount`	`invalid_value`	Le montant demandé n'est pas éligible. L'objet "constraints" contient les montants minimum et maximum valides pour le nombre d'échéances et de jours ou mois différés demandés.

constraints
Comme expliqué dans le tableau ci-dessus, cet objet est renseigné lorsque le montant en requête n'est pas dans les limites configurées sur le compte. Dans ce cas, l'objet "constraints" prend la forme suivante :

{
  ...
  "constraints": {
    "purchase_amount": {
      "minimum": 5000,
      "maximum": 200000
    }
  }
}

Cela permet d'afficher un message le plus informatif possible au client, tel que :

"Paiement en 3x à partir de 50€"
"Plus que 18,40€ pour bénéficier du paiement en 3x"
"Paiement en 4x disponible jusqu'à 2000€"
etc.