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.
Language