{
"aid": "helloasso.com:main-5.0",
"name": "HelloAsso API",
"type": "Index",
"description": "You can find a complete HelloAsso API guide by following this [link](https://dev.helloasso.com/).\r\n\r\nA python wrapper is also available by following this [link](https://github.com/HelloAsso/HaApiV5).\r\n\r\nIn order to access any endpoint you will need to authenticate using **OAuth 2.0** authentication server : `https://api.helloasso.com/oauth2`\r\n\r\nWhen browsing the Swagger documentation :\r\n- The easiest way to use it is to use the Swagger Authorize feature. \r\n- Or you can override the Input `Bearer JWT` in the Authorization Header field. You can easily generate a JWT using Postman's Request Token feature\r\n\r\nThere are two levels of authorization :\r\n - Client privileges : this defines the endpoints the client has access to.\r\n - User Roles : being authorized by an organization grants rights on this organization.\r\n\r\nConnecting to the API with OAuth 2.0\r\n\r\n**In order to use the API, you must authenticate with the OAuth 2.0 server using a private API Client.**\r\n\r\n*What is OAuth 2.0 ? : https://tools.ietf.org/html/rfc6749*\r\n\r\n* If you are an **organization** (i.e. association), you can obtain a client (Id and Secret) in your administration area. You will be granted the following privileges : AccessPublicData, AccessTransactions and Checkout.\r\n* If you are a **partner**, please contact HelloAsso at partenariats@helloasso.org in order to obtain a client.\r\n\r\nIn any case, please keep the client (id and secret) to yourself.\r\n\r\nOn HelloAsso, we support the following grants :\r\n* Client Credentials\r\n `grant_type=client_credentials`\r\n If used by an organization, the rights are limited to the current organization to which the client has been issued.\r\n If used by a partner, it does not grant you any rights (User Roles) on resource owned by an organization, you can only access routes without any User Role required.\r\n See [more information below](#DescClientCredentials).\r\n* Refresh\r\n `grant_type=refresh_token`\r\n See [more information below](#DescRefreshToken).\r\n* Authorization Code\r\n `grant_type=authorization_code`\r\n Only for partners : it permits you to access private resources of organizations, by using the [authorization flow](#DescAuthorizeFlow).\r\n* Disconnect (custom endpoint)\r\n By calling https://api.helloasso.com/oauth2/disconnect, with a valid Bearer token in the Authorization Header, you will disconnect the user, and revoke its tokens. See [more information below](#DescDisconnect).\r\n\r\nWhen authenticating, you will receive an `access_token` which is short-lived (30 minutes), and a `refresh_token`, that will permit you to obtain a new `access_token` for one month. When you have an `access_token` and a `refresh_token`, **you MUST obtain a new `access_token` using the `refresh_token` issued to you** (with the `grant_type=refresh_token`), **and MUST NOT obtain a new `access_token` by using the client**. When refreshing, you will obtain a new `access_token` valid for 30 minutes, and a new `refresh_token` valid for another month. If you continue to use each `refresh_token` that you receive, you could stay authenticated forever, without requiring to enter again your client secret or prompting the user for its login and password.\r\n\r\nClient Credentials\r\n\r\nThis is your first route to obtain an `access_token` to communicate with the API.\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|----------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nclient_secret | Your Client Secret | **Required**\r\ngrant_type | *client_credentials* | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=client_credentials&client_id=9fdc22226bf24ff99b875f4a7c503715&client_secret=AvUYelYH1aSZZ3QNBiZOybmBlZTpUcNSonsufB5txuw='\r\n```\r\n\r\n\r\nRefresh Token\r\n\r\nYour route to refresh indefinitely your `access_token` and obtain a new one.\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|--------------------|------------------\r\ngrant_type | *refresh_token* | **Required**\r\nrefresh_token | Your Refresh Token | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=refresh_token&client_id=9fdc22226bf24ff99b875f4a7c503715&refresh_token=REFRESH_TOKEN'\r\n```\r\n\r\n\r\nAuthorize flow\r\n\r\nThe authorize flow will permit partner's applications to access protected resources (resources owned by an organization). Typically, you must display a button to your user to ask him to login on HelloAsso, and authorize you to access his resources.\r\n\r\nButton example :\r\n\r\n\r\n\r\nButton Code (HTML & CSS)\r\n```\r\n\r\n\r\n\r\n```\r\n\r\n\r\nWhen the user clicks on the button or link, you must open a popup window and direct him to this url : https://auth.helloasso.com/authorize with all the appropriate query parameters (see below).\r\n\r\nAuthorization Request\r\n\r\nRoute to display : **GET** `https://auth.helloasso.com/authorize`\r\n\r\nParameters\r\n\r\nKey | Information | Required/Optional\r\n-----------------------|------------------------------------------------------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nredirect_uri | The redirect uri that will be used when the authorize is complete (success or error). For security considerations, the domain of the redirect uri must be the same configured on your client in our database. The redirect uri must use the secure protocol `https`. You can modify this domain with the following endpoint https://api.helloasso.com/v5/partners/me/api-clients (see section \"Partners Managment\" bellow) | **Required**\r\ncode_challenge | The PKCE code challenge. See section [PKCE](#PKCE) below. | **Required**\r\ncode_challenge_method | The PKCE code challenge method, must be \"*S256*\" | **Required**\r\nstate | A value that will be sent back to you, to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery : **the state sent back must match the one you sent**. Must be a string, but you can use this to encode any data you want. The state should be less than 500 characters. | Optional\r\n\r\nWe recommend you to open the window with at least an height of 650px and a width of 500px.\r\n\r\n\r\nRequest Example\r\n\r\n```\r\nhttps://auth.helloasso.com/authorize\r\n ?client_id=9fdc22226bf24ff99b875f4a7c503715\r\n &redirect_uri=YOUR_REDIRECT_URI\r\n &code_challenge=YOUR_CODE_CHALLENGE\r\n &code_challenge_method=S256\r\n &state=abc\r\n```\r\n\r\n\r\n\r\nThis will display the login window and then the authorize window to the user : \r\n\r\n\r\n\r\nThe user has an option to sign up and register its organization, if he does not have one already.\r\nWhen the user completes the process, the window will redirect to the given `redirect_uri`, with the `authorization_code` in parameter (or with an error code if an error occurred).\r\n\r\nRedirect response\r\n\r\nIf success :\r\nKey | Information\r\n------|----------------------------------------------------------------------------------------------\r\ncode | The authorization code generated by the authorization server. Has a lifetime of five minutes.\r\nstate | If you supplied a state in the request, will be sent back to you\r\n\r\nIf error :\r\nKey | Information\r\n------------------|-----------------------------------------------------------------\r\nerror | A single error code.\r\nerror_description | Optional : a text providing additional information\r\nstate | If you supplied a state in the request, will be sent back to you\r\nSee more info here on error codes : https://tools.ietf.org/html/rfc6749#section-4.1.2.1\r\n\r\n\r\nYou can then exchange the code for an `access_token` and a `refresh_token`.\r\n\r\nAccess Token Request\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|-------------------------------------------------------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nclient_secret | Your Client Secret | **Required**\r\ngrant_type | *authorization_code* | **Required**\r\ncode | The authorization code received (when redirecting to your domain) | **Required**\r\nredirect_uri | The same redirect uri used when displaying the authorize window | **Required**\r\ncode_verifier | The PKCE code verifier | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\norganization_slug | The slug of the association which authorized the access\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=authorization_code&client_id=9fdc22226bf24ff99b875f4a7c503715&client_secret=AvUYelYH1aSZZ3QNBiZOybmBlZTpUcNSonsufB5txuw=' \\\r\n -d 'code=AUTHORIZATION_CODE_RECEIVED&redirect_uri=YOUR_REDIRECT_URI&code_verifier=YOUR_CODE_VERIFIER'\r\n```\r\n\r\n\r\nPKCE\r\n\r\nPKCE (Proof Key for Code Exchange) is a security measure for the authorization grant.\r\n\r\nThe specification can be found here : https://tools.ietf.org/html/rfc7636\r\n\r\nWe require you to use the challenge_method S256.\r\n\r\nBasically, you must generate a random Code Verifier of 43 to 128 characters, from the following characters : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~`. You then create the Code Challenge : you hash the code verifier with the SHA-256 hash function, encode it to base64, and then url encode it.\r\n\r\nYou will send the code challenge in the initial request to display the authorize window. HelloAsso will keep it stored with your request. When you will request a token in exchange for your authorization code, you will send the code verifier. HelloAsso will then validate it (length and characters used) and encode it the same way you did it (SHA-256, base 64 & uri encode) and compare the result with the code challenge stored during the authorize request. If it does not match, you will receive the error \"invalid_grant\".\r\n\r\nIf you want to test your code challenge generator, you can do so here with this online tool : https://tonyxu-io.github.io/pkce-generator/\r\n\r\n\r\nDisconnect\r\n\r\nDisconnect the user, and revoke its tokens. Returns 200 if disconnect worked.\r\n\r\nRoute : **GET** `https://api.helloasso.com/oauth2/disconnect`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n--------------|----------------------------------------------------------\r\nAuthorization | *Bearer JWT* (replace JWT with your `access_token` value)\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X GET \\\r\n https://api.helloasso.com/oauth2/disconnect \\\r\n -H 'Authorization: Bearer JWT'\r\n```\r\n\r\n\r\n\r\nHandling the notifications system\r\n\r\nYou will receive a notification when one of the following events occur:\r\n- A campaign is created\r\n- An order is made (including free orders where there are no payments)\r\n- A payment is made (whether it is a single payment or a payment by installment)\r\n- A payment is refunded\r\n- A payment is contested by the payer with his bank\r\n- A payment by installment is refused\r\n- An organization is renamed and his slug change\r\n\r\nDefine your notification URL\r\n\r\n* If you are an **organization** (i.e. association), you can define and manage your notification URL in your administration area.\r\n* If you are a **partner**, You can modify this notification URL with the following endpoint https://api.helloasso.com/v5/partners/me/api-notifications (see section \"Partners Managment\" bellow). \r\n\r\nIn any case, your callback URL **must use the secure protocol `https` and must support the `POST` verb.**\r\n\r\nThen, in your code, you can handle and listen for information coming from the defined URL.\r\n\r\n\r\nGet the notification content\r\n\r\nThe notification can have 4 different types : **Order**, **Payment**, **Form** (for campaign creation) or **Organization** (when the organization slug changed).\r\n\r\nWhen a new content is available, we will call the notification URL callback defined before with the corresponding data in the body.\r\n\r\nOrder Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Order\r\ndata | The order data. See [more information on the order model below](#model-HelloAsso.Api.V5.Common.Orders.OrderDetail)\r\n\r\nPayment Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Payment\r\ndata | The payment data. See [more information on the payment model below](#model-HelloAsso.Api.V5.Common.Orders.PaymentDetail)\r\n\r\nForm Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Form\r\ndata | The form data. See [more information on the form model below](#model-HelloAsso.Api.V5.Common.Models.Forms.FormPublicModel)\r\n\r\nOrganization Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Organization\r\ndata | { \"data\": { \"old_slug_organization\": \"ctb\", \"new_slug_organization\": \"club tennis bordeaux\" }, \"eventType\": \"Organization\"}\r\n\r\n\r\n\r\n\r\nCheckout Form\r\n\r\nThe Checkout is a type of form, specifically designed to allow contributors to make payments prefilled by an authorized partner or an organization.\r\nThe partner/organization creates a checkout intent (with all the contributor information that he may have, and specified payment terms ; see the following API route *POST checkout-intents* of the [Checkout intents management](#Checkout%20intents%20management) section), and receives in response a url (which is valid for 15 minutes). The contributor follows the url, and then validates the form and pays. The contributor is then redirected to the page of your choosing, with a result parameter (error, success etc).\r\nThe initiator receives a notification of each Order and Payment authorized (if you have configured them, see [Handling the notifications system](#DescNotifications). You can also verify your checkout intent result and receive the created order. See the route *GET checkout-intents/{checkoutIntentId}* of the [Checkout intents management](#operations-tag-Checkout%20intents%20management) section.\r\n\r\nYou can find a more detailed description on how to integrate by following this [link](https://dev.helloasso.com/docs/int%C3%A9grer-le-paiement-sur-votre-site).\r\n\r\nIf you want try checkout payments please use our test environnement https://www.helloasso-sandbox.com/ to create an organization.\r\nYou can then retrieve your API client in the back office and make calls on https://api.helloasso-sandbox.com/v5.\r\nVirtual credit cards are avaible by following this [link](https://docs.sips.Worldline-solutions.com/fr/cartes-de-test.html).\r\n\r\n",
"url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/helloasso.com/main/5.0/apis.json",
"tags": [
"helloasso.com",
"main"
],
"created": "2026-03-31",
"modified": "2026-03-31",
"specificationVersion": "0.19",
"access": "3rd-Party",
"maintainers": [
{
"FN": "Jentic",
"X-github": "jentic",
"url": "https://github.com/jentic"
}
],
"apis": [
{
"aid": "helloasso.com:main-5.0",
"name": "HelloAsso API",
"description": "You can find a complete HelloAsso API guide by following this [link](https://dev.helloasso.com/).\r\n\r\nA python wrapper is also available by following this [link](https://github.com/HelloAsso/HaApiV5).\r\n\r\nIn order to access any endpoint you will need to authenticate using **OAuth 2.0** authentication server : `https://api.helloasso.com/oauth2`\r\n\r\nWhen browsing the Swagger documentation :\r\n- The easiest way to use it is to use the Swagger Authorize feature. \r\n- Or you can override the Input `Bearer JWT` in the Authorization Header field. You can easily generate a JWT using Postman's Request Token feature\r\n\r\nThere are two levels of authorization :\r\n - Client privileges : this defines the endpoints the client has access to.\r\n - User Roles : being authorized by an organization grants rights on this organization.\r\n\r\nConnecting to the API with OAuth 2.0\r\n\r\n**In order to use the API, you must authenticate with the OAuth 2.0 server using a private API Client.**\r\n\r\n*What is OAuth 2.0 ? : https://tools.ietf.org/html/rfc6749*\r\n\r\n* If you are an **organization** (i.e. association), you can obtain a client (Id and Secret) in your administration area. You will be granted the following privileges : AccessPublicData, AccessTransactions and Checkout.\r\n* If you are a **partner**, please contact HelloAsso at partenariats@helloasso.org in order to obtain a client.\r\n\r\nIn any case, please keep the client (id and secret) to yourself.\r\n\r\nOn HelloAsso, we support the following grants :\r\n* Client Credentials\r\n `grant_type=client_credentials`\r\n If used by an organization, the rights are limited to the current organization to which the client has been issued.\r\n If used by a partner, it does not grant you any rights (User Roles) on resource owned by an organization, you can only access routes without any User Role required.\r\n See [more information below](#DescClientCredentials).\r\n* Refresh\r\n `grant_type=refresh_token`\r\n See [more information below](#DescRefreshToken).\r\n* Authorization Code\r\n `grant_type=authorization_code`\r\n Only for partners : it permits you to access private resources of organizations, by using the [authorization flow](#DescAuthorizeFlow).\r\n* Disconnect (custom endpoint)\r\n By calling https://api.helloasso.com/oauth2/disconnect, with a valid Bearer token in the Authorization Header, you will disconnect the user, and revoke its tokens. See [more information below](#DescDisconnect).\r\n\r\nWhen authenticating, you will receive an `access_token` which is short-lived (30 minutes), and a `refresh_token`, that will permit you to obtain a new `access_token` for one month. When you have an `access_token` and a `refresh_token`, **you MUST obtain a new `access_token` using the `refresh_token` issued to you** (with the `grant_type=refresh_token`), **and MUST NOT obtain a new `access_token` by using the client**. When refreshing, you will obtain a new `access_token` valid for 30 minutes, and a new `refresh_token` valid for another month. If you continue to use each `refresh_token` that you receive, you could stay authenticated forever, without requiring to enter again your client secret or prompting the user for its login and password.\r\n\r\nClient Credentials\r\n\r\nThis is your first route to obtain an `access_token` to communicate with the API.\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|----------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nclient_secret | Your Client Secret | **Required**\r\ngrant_type | *client_credentials* | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=client_credentials&client_id=9fdc22226bf24ff99b875f4a7c503715&client_secret=AvUYelYH1aSZZ3QNBiZOybmBlZTpUcNSonsufB5txuw='\r\n```\r\n\r\n\r\nRefresh Token\r\n\r\nYour route to refresh indefinitely your `access_token` and obtain a new one.\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|--------------------|------------------\r\ngrant_type | *refresh_token* | **Required**\r\nrefresh_token | Your Refresh Token | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=refresh_token&client_id=9fdc22226bf24ff99b875f4a7c503715&refresh_token=REFRESH_TOKEN'\r\n```\r\n\r\n\r\nAuthorize flow\r\n\r\nThe authorize flow will permit partner's applications to access protected resources (resources owned by an organization). Typically, you must display a button to your user to ask him to login on HelloAsso, and authorize you to access his resources.\r\n\r\nButton example :\r\n\r\n\r\n\r\nButton Code (HTML & CSS)\r\n```\r\n\r\n\r\n\r\n```\r\n\r\n\r\nWhen the user clicks on the button or link, you must open a popup window and direct him to this url : https://auth.helloasso.com/authorize with all the appropriate query parameters (see below).\r\n\r\nAuthorization Request\r\n\r\nRoute to display : **GET** `https://auth.helloasso.com/authorize`\r\n\r\nParameters\r\n\r\nKey | Information | Required/Optional\r\n-----------------------|------------------------------------------------------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nredirect_uri | The redirect uri that will be used when the authorize is complete (success or error). For security considerations, the domain of the redirect uri must be the same configured on your client in our database. The redirect uri must use the secure protocol `https`. You can modify this domain with the following endpoint https://api.helloasso.com/v5/partners/me/api-clients (see section \"Partners Managment\" bellow) | **Required**\r\ncode_challenge | The PKCE code challenge. See section [PKCE](#PKCE) below. | **Required**\r\ncode_challenge_method | The PKCE code challenge method, must be \"*S256*\" | **Required**\r\nstate | A value that will be sent back to you, to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery : **the state sent back must match the one you sent**. Must be a string, but you can use this to encode any data you want. The state should be less than 500 characters. | Optional\r\n\r\nWe recommend you to open the window with at least an height of 650px and a width of 500px.\r\n\r\n\r\nRequest Example\r\n\r\n```\r\nhttps://auth.helloasso.com/authorize\r\n ?client_id=9fdc22226bf24ff99b875f4a7c503715\r\n &redirect_uri=YOUR_REDIRECT_URI\r\n &code_challenge=YOUR_CODE_CHALLENGE\r\n &code_challenge_method=S256\r\n &state=abc\r\n```\r\n\r\n\r\n\r\nThis will display the login window and then the authorize window to the user : \r\n\r\n\r\n\r\nThe user has an option to sign up and register its organization, if he does not have one already.\r\nWhen the user completes the process, the window will redirect to the given `redirect_uri`, with the `authorization_code` in parameter (or with an error code if an error occurred).\r\n\r\nRedirect response\r\n\r\nIf success :\r\nKey | Information\r\n------|----------------------------------------------------------------------------------------------\r\ncode | The authorization code generated by the authorization server. Has a lifetime of five minutes.\r\nstate | If you supplied a state in the request, will be sent back to you\r\n\r\nIf error :\r\nKey | Information\r\n------------------|-----------------------------------------------------------------\r\nerror | A single error code.\r\nerror_description | Optional : a text providing additional information\r\nstate | If you supplied a state in the request, will be sent back to you\r\nSee more info here on error codes : https://tools.ietf.org/html/rfc6749#section-4.1.2.1\r\n\r\n\r\nYou can then exchange the code for an `access_token` and a `refresh_token`.\r\n\r\nAccess Token Request\r\n\r\nRoute : **POST** `https://api.helloasso.com/oauth2/token`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n-------------|------------------------------------\r\nContent-Type | *application/x-www-form-urlencoded*\r\n\r\nBody\r\n\r\nKey | Information | Required/Optional\r\n--------------|-------------------------------------------------------------------|------------------\r\nclient_id | Your Client Id | **Required**\r\nclient_secret | Your Client Secret | **Required**\r\ngrant_type | *authorization_code* | **Required**\r\ncode | The authorization code received (when redirecting to your domain) | **Required**\r\nredirect_uri | The same redirect uri used when displaying the authorize window | **Required**\r\ncode_verifier | The PKCE code verifier | **Required**\r\n\r\nResult (JSON)\r\n\r\nKey | Information\r\n-------------------|-------------------------------------------------------------------------\r\naccess_token | The JWT token to use in future requests\r\nrefresh_token | Token used to refresh the token and get a new JWT token after expiration\r\ntoken_type | Token Type : always \"*bearer*\"\r\nexpires_in | The lifetime in seconds of the access token\r\norganization_slug | The slug of the association which authorized the access\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X POST \\\r\n https://api.helloasso.com/oauth2/token \\\r\n -H 'content-type: application/x-www-form-urlencoded' \\\r\n -d 'grant_type=authorization_code&client_id=9fdc22226bf24ff99b875f4a7c503715&client_secret=AvUYelYH1aSZZ3QNBiZOybmBlZTpUcNSonsufB5txuw=' \\\r\n -d 'code=AUTHORIZATION_CODE_RECEIVED&redirect_uri=YOUR_REDIRECT_URI&code_verifier=YOUR_CODE_VERIFIER'\r\n```\r\n\r\n\r\nPKCE\r\n\r\nPKCE (Proof Key for Code Exchange) is a security measure for the authorization grant.\r\n\r\nThe specification can be found here : https://tools.ietf.org/html/rfc7636\r\n\r\nWe require you to use the challenge_method S256.\r\n\r\nBasically, you must generate a random Code Verifier of 43 to 128 characters, from the following characters : `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~`. You then create the Code Challenge : you hash the code verifier with the SHA-256 hash function, encode it to base64, and then url encode it.\r\n\r\nYou will send the code challenge in the initial request to display the authorize window. HelloAsso will keep it stored with your request. When you will request a token in exchange for your authorization code, you will send the code verifier. HelloAsso will then validate it (length and characters used) and encode it the same way you did it (SHA-256, base 64 & uri encode) and compare the result with the code challenge stored during the authorize request. If it does not match, you will receive the error \"invalid_grant\".\r\n\r\nIf you want to test your code challenge generator, you can do so here with this online tool : https://tonyxu-io.github.io/pkce-generator/\r\n\r\n\r\nDisconnect\r\n\r\nDisconnect the user, and revoke its tokens. Returns 200 if disconnect worked.\r\n\r\nRoute : **GET** `https://api.helloasso.com/oauth2/disconnect`\r\n\r\nHeaders\r\n\r\nKey | Value\r\n--------------|----------------------------------------------------------\r\nAuthorization | *Bearer JWT* (replace JWT with your `access_token` value)\r\n\r\nCURL Example\r\n\r\n```\r\ncurl -X GET \\\r\n https://api.helloasso.com/oauth2/disconnect \\\r\n -H 'Authorization: Bearer JWT'\r\n```\r\n\r\n\r\n\r\nHandling the notifications system\r\n\r\nYou will receive a notification when one of the following events occur:\r\n- A campaign is created\r\n- An order is made (including free orders where there are no payments)\r\n- A payment is made (whether it is a single payment or a payment by installment)\r\n- A payment is refunded\r\n- A payment is contested by the payer with his bank\r\n- A payment by installment is refused\r\n- An organization is renamed and his slug change\r\n\r\nDefine your notification URL\r\n\r\n* If you are an **organization** (i.e. association), you can define and manage your notification URL in your administration area.\r\n* If you are a **partner**, You can modify this notification URL with the following endpoint https://api.helloasso.com/v5/partners/me/api-notifications (see section \"Partners Managment\" bellow). \r\n\r\nIn any case, your callback URL **must use the secure protocol `https` and must support the `POST` verb.**\r\n\r\nThen, in your code, you can handle and listen for information coming from the defined URL.\r\n\r\n\r\nGet the notification content\r\n\r\nThe notification can have 4 different types : **Order**, **Payment**, **Form** (for campaign creation) or **Organization** (when the organization slug changed).\r\n\r\nWhen a new content is available, we will call the notification URL callback defined before with the corresponding data in the body.\r\n\r\nOrder Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Order\r\ndata | The order data. See [more information on the order model below](#model-HelloAsso.Api.V5.Common.Orders.OrderDetail)\r\n\r\nPayment Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Payment\r\ndata | The payment data. See [more information on the payment model below](#model-HelloAsso.Api.V5.Common.Orders.PaymentDetail)\r\n\r\nForm Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Form\r\ndata | The form data. See [more information on the form model below](#model-HelloAsso.Api.V5.Common.Models.Forms.FormPublicModel)\r\n\r\nOrganization Result (JSON)\r\nKey | Information\r\n------------------|-------------------------------------------------------------------------\r\neventType | Organization\r\ndata | { \"data\": { \"old_slug_organization\": \"ctb\", \"new_slug_organization\": \"club tennis bordeaux\" }, \"eventType\": \"Organization\"}\r\n\r\n\r\n\r\n\r\nCheckout Form\r\n\r\nThe Checkout is a type of form, specifically designed to allow contributors to make payments prefilled by an authorized partner or an organization.\r\nThe partner/organization creates a checkout intent (with all the contributor information that he may have, and specified payment terms ; see the following API route *POST checkout-intents* of the [Checkout intents management](#Checkout%20intents%20management) section), and receives in response a url (which is valid for 15 minutes). The contributor follows the url, and then validates the form and pays. The contributor is then redirected to the page of your choosing, with a result parameter (error, success etc).\r\nThe initiator receives a notification of each Order and Payment authorized (if you have configured them, see [Handling the notifications system](#DescNotifications). You can also verify your checkout intent result and receive the created order. See the route *GET checkout-intents/{checkoutIntentId}* of the [Checkout intents management](#operations-tag-Checkout%20intents%20management) section.\r\n\r\nYou can find a more detailed description on how to integrate by following this [link](https://dev.helloasso.com/docs/int%C3%A9grer-le-paiement-sur-votre-site).\r\n\r\nIf you want try checkout payments please use our test environnement https://www.helloasso-sandbox.com/ to create an organization.\r\nYou can then retrieve your API client in the back office and make calls on https://api.helloasso-sandbox.com/v5.\r\nVirtual credit cards are avaible by following this [link](https://docs.sips.Worldline-solutions.com/fr/cartes-de-test.html).\r\n\r\n",
"image": "",
"baseURL": "https://api.helloasso.com/v5",
"humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/helloasso.com/main/5.0",
"version": "5.0",
"tags": [
"helloasso.com",
"main"
],
"properties": [
{
"type": "OpenAPI",
"name": "OpenAPI definition",
"url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/helloasso.com/main/5.0/openapi.json",
"mediaType": "application/openapi+json"
},
{
"type": "GitHubRepo",
"url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/helloasso.com/main/5.0"
}
]
}
]
}
![\"\"](\"/img/ImgHaLoginWindow.png\")
![\"\"](\"/img/ImgHaAuthorizeWindow.png\")
\r\n\r\nThe user has an option to sign up and register its organization, if he does not have one already.\r\nWhen the user completes the process, the window will redirect to the given `redirect_uri`, with the `authorization_code` in parameter (or with an error code if an error occurred).\r\n\r\n