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

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

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 Body JSON

{
  "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
      }
    ]
  }
}

Exemple appel cURL

curl --location 'https://api.helloasso.com/v5/organizations/organizationSlug/checkout-intents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmN2ZiNWMxNzRmYzc0NTA0ZmQzNDA4TGNlZjY4MThiYSIsImNwcyI6WyJBY2Nlc3NJbnRlcm5hbERhdGEiLCJDdXRPcGVyYXRpb25zIiwiSW50ZXJuYWxUYWdPcGVyYXRpb24iLCJJbnRlcm5hbFVwZGF0ZU9yZ2FuaXphdGlvbiIsIk1haW50ZW5hbmNlT3BlcaF0aW9ucyIsIlBheW1lbnRPcGVyYXRpb25zIl0sIm5iZiI6MTczMzMxMDI5NSwiZXhwIjoxNzMzMzEyMDk1LCJpc3MiOiJodHRwczovL2FwaS5oZWxsb2Fzc28tc2FuZGJveC5jb20iLCJhdWQiOiI0YjE1NWM2ZDdiMTQ0ODVoOTdlY2M5NjRkZWQyM2JiNyJ9.NOvK1Lwy0rqqEafRQ_2HnvKksl7PfLpcwDjY_qF6ZXKT_NMb7cpiazkJpurW9KnIGT8ALXEqsyMhsjUct30L-B9nncHgDGaq_wxTNb4ENTHsyxmd9q5cSBkyS8el_zA2_QmS7ErdFbIfHTtG8agBJsOURHMRgrG6mYR1w77FA6FDRceUPnh1idQEvEPGQkeqerHcWtbdGjXbKwvZRsSdOzCPrT6CdgZhunmCx9jWbuaOppAOGZkDNru12ZQyfH3nQt77LLvLvwTdujegeQlBLjM4H1sWU3sT5_ZRq4JVU1nVukivZg5q57J7JqSb7OzbP-twulSw2bzhfmtvRF0RMg' \
--data-raw '
{
  "totalAmount": 7000,
  "initialAmount": 7000,
  "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,
  "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 :

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]:

❗️

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]:

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:

• errorUrl : https://www.partnertest.com/return-checkout.php?type=error
• returnUrl : https://www.partnertest.com/return-checkout.php?type=return

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