NAV Navbar
shell

Introduction

L'API Alma est une API REST qui accepte et retourne du JSON. Vous pouvez utiliser des requêtes HTTP pour communiquer avec l'API mais nous proposons également des clients PHP et Python, que nous vous conseillons d'utiliser.

Si vous utilisez une plateforme e-commerce, intégrez Alma avec l'un de nos modules.

L'url de l'API est https://api.getalma.eu/v1/

L'url de l'API sandbox est https://api.sandbox.getalma.eu/v1/

Compte Alma et sandbox

Vous pouvez créer votre compte Alma en 1 minute ici.

Nous mettons également à votre disposition un environnement de test (la "sandbox") qui vous permet de tester votre intégration de bout en bout avant de passer en production.
Votre dashboard principal vous donne accès à vos clefs d'API de production et de test, mais si vous souhaitez consulter vos données de test ou paramétrer votre compte de test, vous devez vous rendre sur le dashboard sandbox : https://dashboard.sandbox.getalma.eu.

Votre compte sandbox est créé automatiquement avec les mêmes identifiant et mot de passe que votre compte principal, mais les données et configurations sont ensuite totalement indépendantes et non synchronisées entre les deux comptes.

La clef live peut être utilisée avec le mode "live" des clients d'API, ou bien en ciblant le domaine principal de notre API si vous n'utilisez pas l'un de nos clients d'API : https://api.getalma.eu.
La clef de test peut être utilisée avec le mode "test" des clients d'API, ou bien en ciblant le domaine de sandbox si vous n'utilisez pas l'un de nos clients d'API : https://api.sandbox.getalma.eu.

Une fois votre intégration testée et votre compte de production activé, vous pouvez passer live : il vous suffit de cibler le domaine de production de l'API (ou de changer du mode "test" au mode "live" avec nos clients d'API), et de remplacer la clé d'API de test par celle de production.

Authentification

curl "api_endpoint_here"
  -H "Authorization: Alma-Auth <API key>"
$alma = new Alma\API\Client(<API key>, ['mode' => Alma\API\TEST_MODE]);
import alma

alma.set_api_key(<API key>)

Pour authentifier vos appels à l'API, il vous faut une clé d'API, que vous pouvez récupérer sur votre Dashboard Alma. Nous vous conseillons d'effectuer tous vos tests avec la clé d'API de test, puis de changer pour la clé API de production une fois que votre intégration est prête.

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

Header Value
Authorization Alma-Auth <API key>

Si l'authentification d'un appel échoue, l'API renverra une erreur 401 incluant les raisons de l'échec.

Erreurs

L'API Alma utilise les codes d'erreur suivants :

Code d'erreur Sens
400 Bad Request - Un paramètre est manquant ou invalide.
401 Unauthorized - La clé d'API est invalide.
402 Payment Required - Requête valide mais problème au niveau du paiement, le plus souvent dû à un refus de la banque du client.
404 Not Found - La ressource demandée n'existe pas. Etes-vous certain d'utiliser la bonne clé d'API et la bonne méthode HTTP ?
429 Too Many Requests - Trop de requêtes sur une courte période, indiquant souvent un problème d'implémentation côté client.
500, 502 Internal Server Error - Il y a un problème côté Alma, et nous avons été avertis. Arrive rarement !

Erreurs 400

Exemple d'erreur 400 (cas d'une url invalide)

{
  "error_code": "validation_error",
  "errors": [
    {
      "error_code": "invalid_value",
      "field": "website",
      "message": "Site web doit être une addresse Web valide",
      "value": "google"
    }
  ]
}

Les erreurs 400 sont aussi appelées erreurs de validation et indiquent que les données envoyées lors d'un call API ne sont pas valides. Cela peut être dû à une url invalide, une chaîne de caractères trop longue, un champ booléen là où un nombre est attendu etc.

Champ Description
error_code string Egal à "validation_error"
errors list Liste des erreurs de validation, dont le format est :
fieldstring Champ erroné
error_codestring Code d'erreur, parmi missing_field, invalid_type, invalid_value, too_short, too_long, unique_violated, merchant_cant_create_payments, incompatible_parameters, unauthorized, generic_error,
value* (optionel) Valeur erronée
messagestring (optionel) Message explicatif

Erreurs 402

Exemple d'erreur 402 (paiement rejetté par la banque)

{
  "class": "payment_error",
  "error_code": "insufficient_funds",
  "message": "Card rejected by the bank"
}

Une erreur 402 indique un problème avec le paiement lui-même, le plus souvent un rejet de la banque. Les autres causes possibles sont une erreur sur la carte entrée (par exemple mauvaise date d'expiration) ou une erreur lors de la vérification 3D secure.

Champ Description
class string Egal à "payment_error"
error_code string Code d'erreur, parmi card_declined, invalid_amount, three_d_s_impossible, incorrect_cvc, incorrect_expiration_date, incorrect_number, insufficient_funds, expired_card, missing_field, invalid_value
message string (optionel) Message explicatif

Erreurs 404

{
  "message": "Not found"
}

Une erreur 404 indique que la ressource demandée n'existe pas. Il est à noter que si l'objet que vous cherchez existe mais est demandé par un autre marchand que son propriétaire, une erreur 404 est renvoyée. Ainsi, si vous êtes étonné de recevoir une erreur 404, pensez à vérifier que vous effectuez vos requêtes sur le bon environnement (production vs sandbox).

Identifiants

Chaque objet possède un identifiant unique, composé d'un préfixe et d'une chaîne de caractère base 62 (a-zA-Z0-9) partiellement aléatoire. Le préfixe permet de comprendre d'un coup d'oeil quel est le type de l'objet, par exemple payment_ pour un objet Payment, customer_ pour un objet customer etc. La chaîne de caractère suivant le préfixe est partiellement aléatoire (i.e. l'identifiant suivant ne peux pas être deviné) mais les identifiants sont ordonnés par ordre lexicographique.

Format des données

Listes

{
    "data": [
        {"id": "object_1"},
        {"id": "object_2"},
    ],
    "has_more": true
}

Les listes d'objets ont toutes le même format : un dictionnaire avec deux champs. Le champ data est la liste des objets (par exemple un liste d'objets Payment). Le champ has_more est un booléen indiquant s'il y a d'autres objets dans la page suivante de résultats.

La liste d'objets retournée est triée par ordre chronologique inversé (objets les plus récents retournés en premier). Les identifiants sont ordonnés dans le même sens que les dates de création, ce qui permet de les utiliser pour la pagination (voir paramètre starting_after plus bas) : si l'objet a a été créé après l'objet b, alors a.id > b.id dans l'ordre lexicographique.

Les requêtes de listes d'objets passent leurs paramètres dans la querystring. Les paramètres suivants peuvent être passés pour tous les types d'objets :

Certains paramètres sont des énumérations et ne peuvent recevoir que des éléments de l'énumération, séparés par des virgules. Par exemple pour un objet avec un champ enum pouvant prendre les valeurs val1, val2 et val3, la querystring enum=val1,val3 permettra de ne retourner que les éléments dont le champ enum est égal à val1 et val3. Il est aussi possible d'exclure certaines valeurs en les préfixant par __not__, par exemple enum=__not__val2 renverra les mêmes résultats que la querystring plus haut.

Webhooks

L'API Alma renvoie un webhook appellé "callback IPN" (pour Instant Payment Notification) lorsqu'un paiement est effectué (c'est à dire que le paiement a été accepté par Alma et la commande validée). Ce webhook est indispensable pour les intégrations "redirect" où le client est redirigé vers une page de paiement herbergée par Alma, pour s'assurer que même s'il ferme la page de paiement juste avant de retourner sur votre site, la commande est tout de même validée.

Ce webhook est envoyé de manière asynchrone après le succès d'un paiement, et renvoyé jusqu'à 20 fois en cas de non-réponse de votre serveur ou de réponse autre que 200. Le webhook n'est pas signé ; afin de vérifier son authenticité il vous suffit de rappeler l'API Alma avec votre clé privée afin de récupérer la payload complet

Pour une description détaillée, vous pouvez consulter le guide d'intégration.

Address

L'objet Address décrit une adresse, notamment une addresse de livraison ou une addresse de facturation.

Objet Address au format JSON

{
    "id": "address_11h3ch94QEYlpeX7w0I8MIkog4YK5F1ySa",
    "created": 1552378923,
    "first_name": null,
    "last_name": null,
    "company": null,
    "line1": "1 rue de Rivoli",
    "line2": null,
    "city": "Paris",
    "postal_code": "75004",
    "country": "France",
    "email": null,
    "phone": "06 12 34 56 78",
}
Champ Description
id string Identifiant de l'addresse
created timestamp Date de création de l'addresse
first_name string Prénom
last_name string Nom
company string Entreprise
line1 string Ligne principale, par exemple "1 rue de Rivoli"
line2 string Complément d'addresse
city string Ville
postal_code string Code postal
country string Pays
email string Email associé à l'adresse
phone string Téléphone associé à l'adresse - par exemple téléphone du contact qui récupère la livraison

Créer une Address

L'objet Address ne peut pas être créé ou récupéré directement, seulement via l'objet Payment. Les champs utilisés pour la création de l'objet Address sont :

Champ Description
first_name string Prénom
last_name string Nom
company string Entreprise
line1 string Ligne principale, par exemple "1 rue de Rivoli"
line2 string Complément d'addresse
city string Ville
postal_code string Code postal
country string Pays
email string Email associé à l'adresse
phone string Téléphone associé à l'adresse - par exemple téléphone du contact qui récupère la livraison

Card

L'objet Card représente les informations d'une carte utilisée par un paiement. Seules les informations non sensibles sont incluses dans l'objet. Il ne peut être créé ou récupéré directement, seulement via l'objet Payment.

Objet Card au format JSON

{
    "id": "card_11h3cnA3x6oSqamXY0EmGGaiwu0kVhauep",
    "created": 1552379299,
    "exp_month": 11,
    "exp_year": 2019,
    "last4": "4242",
    "country": "FR",
    "funding": "debit",
    "brand": "visa",
    "three_d_secure_possible": true,
    "verified": true,
    "psp_representations": {
        "stripe": {
            "customer_id": "cus_EgSusITxQmwGI8",
            "original_source_id": "src_1ED5yCKi1KnRqlDtIF87iILn"
        }
    }
}
Champ Description
id string Identifiant de la carte
created timestamp Date de création de la carte
exp_month integer Date d'expiration - mois
exp_year integer Date d'expiration - année
last4 string Quatre derniers chiffres de la carte utilisée
country string Pays de la carte
funding string Type de carte : debit, credit ou unknown
brand string Marque de la carte : visa, mastercard ou american express
three_d_secure_possible boolean True si la carte permet une authentification 3D secure
verified boolean True si la carte a été vérifiée avec 3D secure
psp_representations object Représentation de la carte chez nos partenaires PSP. Format : {"psp": {<card_data>}, ...}

Customer

L'objet Customer représente les informations personnelles d'un client. Il ne peut être créé ou récupéré directement, seulement via l'objet Payment.

Objet Customer au format JSON

{
    "id": "customer_11h3ch7UDyyCiuHCKy02y4EeWkwd3JuHUb",
    "created": 1552378923,
    "first_name": "Martin",
    "last_name": "Dupont",
    "addresses": [],
    "email": "martin.dupont@gmail.com",
    "phone": "06 12 34 56 78",
    "birth_date": null,
    "card": {
        "id": "card_11h3cnA3x6oSqamXY0EmGGaiwu0kVhauep",
        "created": 1552379299,
        "exp_month": 11,
        "exp_year": 2019,
        "last4": "4242",
        "country": "FR",
        "funding": "debit",
        "brand": "visa",
        "three_d_secure_possible": true,
        "verified": true,
        "psp_representations": {
            "stripe": {
                "customer_id": "cus_EgSusITxQmwGI8",
                "original_source_id": "src_1ED5yCKi1KnRqlDtIF87iILn"
            }
        }
    },
    "banking_data_collected": false
},
Champ Description
id string Identifiant du client
created timestamp Date de création du client
first_name string Prénom
last_name string Nom de famille
addresses list of Address Liste des adresses liées à ce client
email string Email du client
phone string Téléphone du client
birth_date string Date de naissance du client
card Card Objet Card
banking_data_collected boolean True si les données bancaires de ce client ont été collectées. Les données bancaires des clients ne sont jamais accessibles et sont supprimées une fois qu'elles ne sont plus utilisées dans le cadre du paiement

Eligibilité

Toutes les commandes n'étant pas éligibles au paiement en plusieurs fois, il est nécessaire de vérifier l'éligibilité d'un achat avant de proposer Alma comme méthode de paiement, et d'adapter le message affiché au client aux différentes étapes du tunnel d'achat (fiche produit, panier, ...).

Le endpoint /eligibility permet de déterminer si un achat est éligible.
En cas d'éligibilité, l'API renvoie les détails de l'échéancier qui serait appliqué à la création du paiement correspondant. Autrement, des informations sur la raison de la non éligibilité sont renvoyés.

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

curl -X POST https://api.getalma.eu/v1/payments/eligibility \
-H "Authorization: Alma-Auth <API key>" \
-H "Content-Type: application/json" \
-d '{ "purchase_amount": 20000 }' \

Paramètres

La donnée attendue est la même que lors de la création d'un paiement, mais le seul attribut obligatoire est payment[purchase_amount].

Éligibilité pour plusieurs échéanciers

Il est possible de demander l'éligibilité et les échéanciers pour différents nombres d'échéances. Pour cela, il faut passer la liste des nombres d'échéances voulus dans le paramètre installments_count:

curl -X POST https://api.getalma.eu/v1/payments/eligibility \
-H "Authorization: Alma-Auth <API key>" \
-H "Content-Type: application/json" \
-d '{ "purchase_amount": 20000, "installments_count": [3, 4] }' \

Réponse

Si jamais le compte marchand rattaché à la clef d'API utilisée n'est pas encore activé, cet appel renverra une erreur 400.
Sinon, le code HTTP renvoyé est 200 et la réponse dépend du résultat d'éligibilité.

Achat éligible

Si l'achat est éligible au paiement en plusieurs fois, la réponse contient l'échéancier qui serait appliqué au client (dates d'échéances, montants et frais appliqués au client) :

{
  "eligible": true,
  "installments_count": 3,
  "payment_plan": [
    {
      "due_date": 1547562399,
      "purchase_amount": 6664,
      "customer_fee": 0
    },
    {
      "due_date": 1550240799,
      "purchase_amount": 6663,
      "customer_fee": 0
    },
    {
      "due_date": 1552659999,
      "purchase_amount": 6663,
      "customer_fee": 0
    }
  ]
}
Champ Description
eligible boolean true
installments_count integer Nombre d'échéances dans l'échéancier (3 par défaut)
payment_plan object Liste des échéances pour cet achat :
purchase_amountinteger Montant hors frais de l'échéance, en centimes
customer_feeinteger Éventuels frais de paiement appliqués au client sur cette échéance, en centimes
due_datetimestamp Date à laquelle le paiement de cette échéance est dû

Si, dans la requête, installments_count a été passé comme un tableau (même avec un seul élément), alors la réponse est un tableau de ces objets, un par nombre d'échéances, dans le même ordre que la liste fournie en entrée.

Note: il est tout à fait possible que eligible soit true pour certains échéanciers et false pour d'autres. Il convient donc de toujours vérifier la réponse pour chaque échéancier afin de ne présenter à l'utilisateur que les échéanciers auxquels il est éligible.

Achat non éligible

Dans le cas où l'achat n'est pas éligible, la réponse contient :

{
  "eligible": false,
  "installments_count": 3,
  "reasons": {
    "purchase_amount": "invalid_value"
  },
  "constraints": {
    "purchase_amount": {
      "minimum": 10000,
      "maximum": 100000
    }
  }
}
Champ Description
eligible boolean false
installments_count integer Nombre d'échéances demandées (3 par défaut)
reasons object Attributs en cause de l'échec d'éligibilité
<attribut>string Raison du rejet pour l'attribut nommé en clef
constraints object Contraintes que l'achat doit respecter :
purchase_amountobject Contraintes sur le montant d'achat
minimuminteger Montant minimum éligible, en centimes
maximuminteger Montant maximum éligible, en centimes

Si, dans la requête, installments_count a été passé comme un tableau (même avec un seul élément), alors la réponse est un tableau de ces objets, un par nombre d'échéances, dans le même ordre que la liste fournie en entrée.

Order

L'objet Order représente les informations d'une commande, généralement la commande liée à un Payment.

Objet Order au format JSON

{
    "id": "order_11h4MCc4atnjecmoK6GU6UYGo6qMK6RMLw",
    "created": 1552553941,
    "merchant_reference": "ref-9676683702228572",
    "merchant_url": "https://backoffice.merchant.com/orders/ref-9676683702228572",
    "payment": "payment_11h4MEW6jokMbn3ya4sI0scgeauAm41CO4",
    "data": {}
}
Champ Description
id string Identifiant Alma de la commande
created timestamp Date de création de la commande sur Alma
merchant_reference string Référence marchand de la commande, permettant de faire le lien entre une commande et un paiement sur Alma
merchant_url string Url de la page du backoffice marchand pour cette commande
customer_url string Url de la page de suivi de la commande destinée au client
payment string Identifiant Alma du paiement correspondant à cette commande
data object Dictionnaire contenant des données arbitraires entrées par le marchand

Créer un Order

Les objets Order ne peuvent être créés directement mais le sont lors de la création d'un Payment. Les données utilisées pour la création d'un Order sont :

Champ Description
merchant_reference string Référence marchand de la commande, permettant de faire le lien entre une commande et un paiement sur Alma
merchant_url string Url de la page du backoffice marchand correspondant à la commande
data object Dictionnaire contenant des données arbitraires entrées par le marchand

Payment

L'objet Payment décrit un achat en plusieurs fois dans sa totalité : montant et date de l'achat, informations client et échéancier.

Objet Payment au format JSON

{
    "id": "payment_11h3ch442l36V9P4aASCwi4kwAgYkhkSiw",
    "merchant_name": "The Alma Shop",
    "state": "scored_yes",
    "created": 1552378923,
    "url": "https://pay.getalma.eu/11h3ch442l36V9P4aASCwi4kwAgYkhkSiw",
    "return_url": "https://merchant.com/after_payment.html?pid=payment_11h3ch442l36V9P4aASCwi4kwAgYkhkSiw",
    "customer_cancel_url": null,
    "purchase_amount": 21000,
    "customer_fee": 378,
    "payment_plan": [
        {
            "purchase_amount": 7000,
            "customer_fee": 378,
            "due_date": 1552378923,
            "state": "pending"
        },
        {
            "purchase_amount": 7000,
            "customer_fee": 0,
            "due_date": 1555057323,
            "state": "pending"
        },
        {
            "purchase_amount": 7000,
            "customer_fee": 0,
            "due_date": 1557649323,
            "state": "pending"
        }
    ],
    "customer": {
        "id": "customer_11h3ch7UDyyCiuHCKy02y4EeWkwd3JuHUb",
        "created": 1552378923,
        "first_name": "Martin",
        "last_name": "Dupont",
        "addresses": [],
        "email": "martin.dupont@gmail.com",
        "phone": "06 12 34 56 78",
        "birth_date": null,
        "card": {
            "id": "card_11h3cnA3x6oSqamXY0EmGGaiwu0kVhauep",
            "created": 1552379299,
            "exp_month": 11,
            "exp_year": 2019,
            "last4": "4242",
            "country": "FR",
            "funding": "debit",
            "brand": "visa",
            "three_d_secure_possible": true,
            "verified": true,
            "psp_representations": {
                "stripe": {
                    "customer_id": "cus_EgSusITxQmwGI8",
                    "original_source_id": "src_1ED5yCKi1KnRqlDtIF87iILn"
                }
            }
        },
        "banking_data_collected": false
    },
    "shipping_address": {
        "id": "address_11h3ch94QEYlpeX7w0I8MIkog4YK5F1ySa",
        "created": 1552378923,
        "first_name": null,
        "last_name": null,
        "company": null,
        "line1": "1 rue de Rivoli",
        "line2": null,
        "city": "Paris",
        "postal_code": "75004",
        "country": "France",
        "email": null,
        "phone": null
    },
    "billing_address": null,
    "custom_data": {},
    "orders": [],
    "refunds": []
}
Champ Description
id string Identifiant du Payment
created timestamp Date de création du Payment
billing_address Address Adresse de facturation de ce paiement, voir section Address
customer Customer Client, voir section Customer
customer_cancel_url string Url permettant au client d'annuler son paiement et de revenir au site marchand
customer_fee integer Frais payés par le client, en plus du montant du panier
merchant_name string Nom du marchand ayant créé le paiement
orders list of Order Liste des commandes payées avec ce paiement, voir section Order
payment_plan list Liste des prélèvements, avec pour chacun:
purchase_amountinteger Montant du panier
customer_feeinteger Frais payés par le client, en plus du montant du panier
due_datetimestamp Date à laquelle est dû ce prélèvement
statestring Etat du prélèvement, valeurs possibles : pending (pas encore prélevé), paid (prélevé), covered (incident de paiement couvert par Alma)
purchase_amount integer Montant du panier
refunds list of Refund Liste des remboursements opérés sur ce paiement, voir section Refund
return_url string Url vers laquelle le client sera redirigé une fois le paiement effectué, généralement là où le marchand valide la commande
shipping_address Address Adresse de livraison de la commande, voir section Address
state string Etat du paiement : not_started (le paiement a été créé), scored_no (le paiement en plusieurs fois est refusé par Alma), scored_yes (le paiement en plusieurs fois est accepté par Alma), scored_maybe (Alma a besoin de plus d'informations pour décider de l'acceptation du paiement) ou paid (le client a payé). Note : même dans les états scored_no et scored_maybe, un paiement peut être payé en une fois par le client
url string Url de la page Alma correspondant à ce paiement. Tant que le paiement n'est pas paid, il est actif pendant 48 heures. Passé ce délai il devient inaccessible et le client doit être en créer un autre. Quand le paiement est paid cette page devient un résumé de l'état du paiement et des éventuels retards de paiement pour le client

Créer un Payment

curl https://api.getalma.eu/v1/payments \
-H "Authorization: Alma-Auth <API key>" \
-d payment[purchase_amount]=10000 \
-d payment[return_url]="http://merchant.com/payment-success" \
-d payment[shipping_address][first_name]="Martin" \
-d payment[shipping_address][last_name]="Dupont" \
-d payment[shipping_address][line1]="1 rue de Rivoli" \
-d payment[shipping_address][postal_code]="75004" \
-d payment[shipping_address][city]="Paris"

POST https://api.getalma.eu/v1/payments

Paramètres

Champ Description
payment object Données du paiement, à savoir :
purchase_amountinteger Montant du panier
return_urlstring Url vers laquelle le client sera redirigé une fois le paiement validé
billing_addressAddress, optional Adresse de facturation sous forme d'un objet Address (voir Créer une Address). Au moins un champ entre shipping_address et billing_address doit être présent
customer_cancel_urlstring, optional Si renseigné, un lien d'annulation apparaîtra en bas de la page de paiement, ramenant le client vers cette url
installments_countinteger, optional Nombre de prélèvements, entre 2 et 4 (défaut : 3)
shipping_addressAddress, optional Adresse de livraison sous forme d'un objet Address (voir Créer une Address). Au moins un champ entre shipping_address et billing_address doit être présent
customer object, optional Données du client, à savoir :
addressesList of Address, optional Liste des addresses du client, chacune sous forme d'un objet Address (voir Créer une Address).
emailstring, optional Email du client
first_namestring, optional Prénom du client
last_namestring, optional Nom de famille du client
phonestring, optional Numéro de téléphone du client
order Order, optional Données de la commande associée au paiement au format Order, voir Créer un Order

Récupérer un Payment

curl https://api.getalma.eu/v1/payments/<payment_id> \
-H "Authorization: Alma-Auth <API key>"
$alma = new Alma\API\Client(<API key>, ['mode' => Alma\API\TEST_MODE]);

$alma.Payment.retrieve(<payment_id>)
import alma

alma.set_api_key(<API key>)

alma.Payment.retrieve(<payment_id>)

GET https://api.getalma.eu/v1/payments/<payment_id>

Paramètres : aucun

Retourne l'objet Payment.

Récupérer une liste de Payments

Pour récupérer 50 objets Payment dont le client a une adresse email contenant "gmail.com" et dont l'ID est plus ancien que payment_123

curl
https://api.getalma.eu/v1/payments?limit=50&starting_after=payment_123 \
-H "Authorization: Alma-Auth <API key>"

Voir la section Listes pour le format général des listes d'objets.

GET https://api.getalma.eu/v1/payments

Champ Description
customer_email string, optional Email du client ayant effectué le paiement. Note : tous les paiements dont l'email client contient customer_email seront renvoyés
state string, optional Etat du paiement : not_started, scored_no, scored_yes, scored_maybe, ou paid

Modifier un Payment

curl https://api.getalma.eu/v1/payments/<payment_id> \
-H "Authorization: Alma-Auth <API key>" \
-d customer[first_name]="Martin2" \
-d customer[last_name]="Dupont2" \

POST https://api.getalma.eu/v1/payments/<payment_id>

Permet de mettre à jour un paiement pour modifier le client et/ou la carte de paiement. Il est à noter qu'un Payment ne peut être modifié que s'il n'a pas encore commencé (le premier prélèvement a été effectué). A chaque modification, le paiement repasse en statut not_started, et doit donc être scoré à nouveau avant de pouvoir être payé.

Il faut noter qu'une fois un champ du client renseigné, il ne peut plus être modifié.

Il faut également noter que pour des raisons de sécurité des données, la seule manière de mettre à jour la carte liée à un paiement est via un token la représentant chez un PSP partenaire (Alma ne travaille qu'avec Stripe aujourd'hui).

Champ Description
customer object, optional Données du client, à savoir :
addressesList of Address, optional Liste des addresses du client, chacune sous forme d'un objet Address (voir Créer une Address).
emailstring, optional Email du client
first_namestring, optional Prénom du client
last_namestring, optional Nom de famille du client
phonestring, optional Numéro de téléphone du client
card object, optional Représentations de la carte ("tokens") crées au niveau du navigateur/device client
stripestring Identifiant du token représentant la carte chez Stripe

Refund

L'objet Refund représente un remboursement. Alma abstrait toute la complexité du remboursement d'un paiement en plusieurs fois : le marchand n'a pas à se soucier de ce que le client a déjà payer ou doit encore payer et peut rembourser le client à hauteur de ce qu'il a payé (à savoir payment.purchase_amount + payment.customer_fee). Tant que la somme des remboursements ne dépasse pas cette limite, le marchand peut opérer autant de remboursements qu'il le souhaite.

Objet Refund au format JSON

{
    "id": "refund_11h3jIO3ysBniMdtgC2AyEW4skyEG43P7H",
    "created": 1552404383,
    "amount": 17000,
    "payment": "payment_11h3ch442l36V9P4aASCwi4kwAgYkhkSiw",
    "merchant_reference": "981201927"
}
Champ Description
id string Identifiant du remboursement
created timestamp Date de création du remboursement
amount integer Montant du remboursement
payment string Identifiant du paiement sur lequel le remboursement a été appliqué
merchant_reference string Référence interne du marchand pour ce remboursement

Créer un Refund

Rembourser 150 euros

curl https://api.getalma.eu/v1/payments/<payment_id>/refunds \
-H "Authorization: Alma-Auth <API key>" \
-d amount=15000
-d merchant_reference=981201927

POST https://api.getalma.eu/v1/payments/<payment_id>/refunds

Pour rembourser un client, il suffit de créer un objet Refund sur l'objet Payment correspondant. Vous pouvez effectuer un remboursement total ou un (ou plusieurs) remboursements partiels. Vous pouvez rembourser un client à hauteur de ce qu'il va payer (c'est à dire le montant de l'achat plus les éventuels frais client) sans vous soucier de ce que le client a déjà effectivement payé - Alma s'occupe de déterminer de combien amputer les prochains prélèvements et quelle somme retourner au client.

Vous pouvez également passer une référence interne qui sera associée au Refund créé côté Alma, utile pour rapprocher les données de votre base de données avec les données d'Alma.

Champ Description
amount integer, optional Montant du remboursement. Si non renseigné, effectuer un remboursement total
merchant_reference string, optional Référence interne du marchand pour ce remboursement