👋
This is only a brief overview of the API documentation. Please refer to the sections in the left-hand menu for more detailed explanations.

API Overview

This page provides a complete summary of the HelloAsso API v5 and Plus Billetterie API, including authentication, Checkout integration, and all available endpoints.

Base URLs

Environment	API Base URL	Website
Production	`https://api.helloasso.com/v5`	helloasso.com
Sandbox	`https://api.helloasso-sandbox.com/v5`	helloasso-sandbox.com

🧪
Use the sandbox environment to test your integration. Create an organization at helloasso-sandbox.com, then retrieve your API client from the back office. Virtual credit cards are available for testing payments.

Authentication (OAuth 2.0)

The HelloAsso API uses OAuth 2.0 for authentication. You need an API client (ID and Secret) to get started.

Getting your API credentials

Organizations (associations): Obtain your client ID and secret from your administration area. You receive these privileges: AccessPublicData, AccessTransactions, and Checkout.
Partners: Contact HelloAsso at [email protected] to obtain a client.

🔒
Keep your client ID and secret confidential. Never expose them in client-side code or public repositories.

Supported grant types

Use grant_type=client_credentials to authenticate directly with your client ID and secret.

Organizations: Access is limited to the organization the client was issued to.
Partners: Does not grant any User Roles on organization resources. You can only access routes that don't require a User Role.

curl -X POST https://api.helloasso.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "UxMiwiZX...",
  "token_type": "bearer",
  "expires_in": "1800"
}

Token lifecycle

Token	Lifetime	Notes
`access_token`	30 minutes	Short-lived JWT, include in the `Authorization: Bearer TOKEN` header
`refresh_token`	1 month	Use it to get a new access token + refresh token pair

Each time you refresh, you receive a new access_token (valid 30 min) and a new refresh_token (valid 1 month). By continuously using each refresh token, you can stay authenticated indefinitely without re-entering credentials.

Checkout Integration

The Checkout allows contributors to make payments through a form pre-filled by a partner or organization.

How it works

Create a checkout intent — POST /organizations/{organizationSlug}/checkout-intents with contributor information, payment terms, and redirect URLs.
Redirect the contributor — The response contains a redirectUrl (valid for 15 minutes). Redirect the contributor to this URL to complete payment.
Contributor pays — The contributor validates the form and pays.
Handle the redirect — The contributor is redirected to your returnUrl with a result parameter (success, error, etc.).
Receive notifications — Configure webhook notifications for Order and Payment events.
Verify the result — GET /organizations/{organizationSlug}/checkout-intents/{checkoutIntentId} to retrieve the checkout intent result and created order.

Required fields for checkout intent

Field	Type	Description
`totalAmount`	integer	Total amount in cents (must equal initial amount + sum of terms)
`initialAmount`	integer	First payment amount in cents
`itemName`	string	Description of what the contributor is paying for (max 250 chars)
`backUrl`	string	URL if the contributor wants to go back
`errorUrl`	string	URL called on checkout error
`returnUrl`	string	URL called after payment
`containsDonation`	boolean	Whether the payment (or part of it) is a donation

Optional fields

Field	Type	Description
`terms`	array	List of future payment terms (amount in cents + date)
`payer`	object	Pre-fill payer info: firstName, lastName, email, address, etc.
`metadata`	object	Custom JSON metadata (max 20,000 chars)
`paymentOptions.enableSepa`	boolean	Enable SEPA payment for this checkout

HelloAsso API v5 — Endpoints

All endpoints below use the base URL https://api.helloasso.com/v5 and require OAuth 2.0 authentication.

Please go to the API Reference section.