Fonctionnement de HelloAsso Checkout

Comment utiliser HelloAsso Checkout pour collecter des paiements sur votre site Web.

Déroulement général d'un paiement checkout


  1. Initialisation d’une demande d'encaissement via un POST vers l’API HelloAsso.
  2. Les données sont invalides, l'API renvoie le détail de l’erreur de validation.
  3. Les données sont valides, l’API renverra un Identifiant d’encaissement, ainsi que l’url de redirection pour le contributeur. Votre site redirige l'utilisateur vers cette URL.
  4. Sur la page sur laquelle il vient d'être redirigé, le contributeur vérifie son panier, puis remplit ses informations bancaires.
  5. Si pendant son paiement:
    1. le contributeur clique sur la flèche de retour arrière, il est redirigé vers backURL
    2. Une erreur survient, le contributeur est redirigé vers errorURL
  6. Aucune erreur constatée, le contributeur est redirigé vers l’URL de retour prédéfinie par le partenaire: returnURL
  7. Dans le cas d'un succès de paiement, HelloAsso envoie une notification à votre serveur avec les informations du paiement, ainsi qu’une notification avec les informations de la commande.
    Cette notification doit être utilisée pour valider le paiement.
  8. Si nécessaire, vous pouvez interroger vous-même le serveur HelloAsso pour récupérer la commande liée à votre demande d’encaissement.
  9. L’API HelloAsso vous renvoie votre demande d’encaissement et vos metadata. Si une commande a été créée, le détail de la commande vous est renvoyé.

1. Initialisation d'une demande d'encaissement

Le POST effectué par le partenaire permet l’initialisation d’un paiement pré-rempli avec des données transmises.

URL

https://api.helloasso.com/v5/organizations/{asso-slug}/checkout-intents

Les informations de pré remplissage sont à transmettre dans le body de la requête au format JSON.

Nous vous recommandons fortement de nous fournir également tous les paramètres recommandés, cela facilitera le parcours du payeur, qui sera ainsi en mesure de valider son panier plus rapidement.

Paramètres

ChampsObligatoireDescriptionTypeExemples
totalAmountOuiMontant en centime total (TTC) du paiement, doit être égal à la somme du montant initial ainsi que des échéancesnumérique1000 (pour : 10.00€)
initialAmountOuiMontant en centime du paiement (TTC) à payer immédiatementnumérique1000 (pour : 10.00€)
itemNameOuiDescription de l’achat. Sera affiché dans le compte HelloAsso de l'associationtexte (max 250 caractères)Maillot, 2 places concert XXX, Renouvellement licence Fédération X 2021, ...
backUrlOuiUrl de retour sur votre site si l'acheteur souhaite modifier son panier avant de payer. Https uniquementurlhttps://www.partnertest.com
/cancel.php
errorUrlOuiL’url de retour en cas d’erreur technique.
Https uniquement
urlhttps://www.partnertest.com
/error.php
returnUrlOuiL’url de retour après le paiement
Https uniquement
urlhttps://www.partnertest.com
/return.php
containsDonationOuiIndique si le paiement ou une partie est assimilable à un don à l'association. Pour des raisons de conformité, ce paramètre est obligatoire.booléentrue ou false
termsNonTableau contenant les échéances éventuellestableauA utiliser dans le cas d'un paiement avec des échéances.
Voir paiements par échéances.
terms[].amountOui, si échéanceMontant de l’échéance (TTC) en centimesnumérique1000 (pour : 10.00€)
terms[].dateOui, si échéanceDate de l’échéancedate, format : aaaa-mm-jj2021-12-25
payer.firstNameRecommandéPrénom du contributeurtexte (max 255 caractères)Jean
payer.lastNameRecommandéNom du contributeurtexte (max 255 caractères)Dubois
payer.emailRecommandéAdresse Emailemail (max 255 caractères)[email protected]
payer.dateOfBirthRecommandéDate de naissance du contributeurdate, format : aaaa-mm-jj1986-08-25
payer.addressRecommandéAdresse du contributeurtexte1 Rue des jonquilles
payer.cityRecommandéVilletexteBordeaux
payer.zipCodeRecommandéCode postalalphanumérique33000
payer.countryRecommandéPaysformat : ISO 3166-1 / Alpha-3 codeFRA
metadata

Uniquement pour les partenaires
NonInformations partenaire. Ces infos ne seront pas transmises à l’association ou au contributeur. Elles vous seront renvoyées avec la commande ou le paiement lors de la notification, ou quand vous voudrez récupérer le détail du paiement ou de la commandeObjet Json (max 20000 caractères quand sérialisé){"payment_ref":150, "contributor_id":"1541

Contrôle des champs

Nom / prénom

Si le nom ou le prénom sont transmis, ils ne doivent pas contenir :

  • 3 caractères répétitifs
  • Un chiffre
  • Un seul caractère
  • Aucune voyelle
  • Les valeurs : "firstname", "lastname", "unknown", "first_name", "last_name", "anonyme", “user", "admin", "name", “nom", "prénom", "test”
  • De caractères spéciaux, à l’exception des lettres "e", "a" et "u" accentuées, "‘", "-", "ç"
  • Des caractères n’appartenant pas à l’alphabet latin

De plus, le nom et le prénom ne doivent pas être identiques.

Autres

  • L’email doit être valide
  • La date de naissance doit correspondre à un acheteur majeur

Exemple


{
  "totalAmount": 7000,
  "initialAmount": 3000,
  "itemName": "Adhesion Football",
  "backUrl": "https://www.partnertest.com/back.php",
  "errorUrl": "https://www.partnertest.com/error.php",
  "returnUrl": "https://www.partnertest.com/return.php",
  "containsDonation": true,
  "terms": [
    {
      "amount": 2000,
      "date": "2021-03-25"
    },
    {
      "amount": 2000,
      "date": "2021-04-25"
    }
  ],
  "payer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "dateOfBirth": "1986-07-06",
    "address": "23 rue du palmier",
    "city": "Paris",
    "zipCode": "75000",
    "country": "FRA",
    "companyName": "HelloAsso"
  },
  "metadata": {
    "reference": 12345,
    "libelle": "Adhesion Football",
    "userId": 98765,
    "produits": [
      {
        "id": 56,
        "count": 1
      },
      {
        "id": 78,
        "count": 3
      }
    ]
  }
}

2. Récupération de l'URL d'encaissement

Si toutes les données sont valides, HelloAsso renverra un id de demande d’encaissement, ainsi que l’url de redirection à utiliser :

ChampsDescription
IdIdentifiant de la demande d’encaissement
redirectUrlURL sur laquelle rediriger le contributeur.

S’il y a une erreur, vous recevrez un code http d’erreur (400 dans le cas de mauvais paramètres), et si possible le nom des champs en erreur.

⚠️

L’URL de redirection a une durée de validité de 15 minutes.

3. Réalisation de la transaction et urls de retour

Lorsque le contributeur est redirigé sur la page d’encaissement, il est invité à compléter ou vérifier ses informations, puis il à la possibilité de payer.

Cas 1. Tentative de paiement réalisée

Dans le cas d’une tentative de paiement correctement réalisé, les paramètres suivant sont ajoutés lors de la redirection vers la [returnUrl]:

Nom du paramètreDescription
checkoutIntentIdIdentifiant du checkout
codeStatut du paiement: succeeded ou refused
orderIdIdentifiant de l’order lié au checkout.

❗️

Validation d'un paiement

Attention, une fois la tentative de paiement réalisée il vous appartient de vérifier le paramètre “code” pour afficher un page de confirmation de paiement.

Afin de valider définitivement le paiement, il est impératif de réconcilier votre paiement. En effet, le code décris ci-dessous peut être facilement falsifié.

Exemple

https://www.partnertest.com/return.php?checkoutIntentId=3&code=succeeded&orderId=462873

Cas 2. Erreur technique pendant le paiement

Dans le cas d’une erreur technique pendant le paiement, les paramètres suivant sont ajoutés lors de la redirection vers la [errorUrl]:

Nom du paramètreDescription
checkoutIntentIdCorrespond à l’identifiant du checkout
errorDans le cas où l'erreur à pu être identifiée par nos services, un code erreur est transmis.

Exemple :

https://www.partnertest.com/error.php?checkoutIntentId=3
https://www.partnertest.com/error.php?checkoutIntentId=3&error=reason

Utilisation de la même URL pour errorURL et la returnURL

Vous pouvez utiliser la même route pour gérer votre returnURL et votre errorURL. Veillez juste à ne pas utiliser les paramètres décris ci-dessous.

Par exemple, vous pouvez utiliser le paramètre “type” pour différencier vos deux urls:

Dans ce cas, nous appellerons ces Urls de ces façons là :

  • Erreur technique:
https://www.partnertest.com/return-checkout.php?type=error&checkoutIntentId=3&error=reason
  • Paiement réalisé et accepté:
https://www.partnertest.com/return-checkout.php?type=return&checkoutIntentId=3&code=succeeded
  • Paiement réalisé et refusé:
https://www.partnertest.com/return-checkout.php?type=return&checkoutIntentId=3&code=refused