Brumisphere Checkout Button for HelloAsso

Sharraxaad

Brumisphere Checkout Button for HelloAsso adds a generic [helloasso_checkout_button] shortcode to WordPress. It creates HelloAsso checkout intents server-side only after the visitor clicks the button, stores payment records in separate sandbox and production tables, and updates payment state through HelloAsso webhooks.

The plugin is published by Brumisphère, Agence Webmarketing, and is designed as a business-agnostic HelloAsso checkout integration. It does not include booking, calendar, week selection, or custom business workflows.

Features

• Generic [helloasso_checkout_button] shortcode.
• Server-side checkout creation after an explicit visitor click.
• Transient-backed checkout configuration with nonce validation.
• Separate sandbox and production credentials.
• Separate physical payment tables for sandbox and production.
• HelloAsso OAuth and API v5 clients with tuned WordPress HTTP requests.
• Optional defensive cURL fallback for a specific Azure 404 HTML misroute, disabled by default and available through a developer filter after WordPress HTTP API is tried first.
• Environment-specific webhook endpoints.
• HMAC SHA-256 webhook validation when an environment Webhook Signature Key is configured.
• Controlled unsigned webhook fallback when a signature key is unavailable.
• Admin Payments screen for sandbox and production logs without changing the active checkout environment.
• Minimized webhook event storage; raw webhook payloads are not stored by default.
• Secure output escaping, settings sanitization, and admin capability checks.

The front end never receives client secrets, access tokens, webhook signature keys, or Authorization headers.

Configuration

Settings are available under HelloAsso Checkout > Settings.

General

• Active checkout environment: sandbox or production.
• Debug logging.
• Allow unsigned webhooks when signature key is missing.
• Delete plugin data on uninstall.

Production credentials

• Production Client ID.
• Production Client Secret.
• Production Organization Slug.
• Production Webhook Signature Key.

Sandbox credentials

• Sandbox Client ID.
• Sandbox Client Secret.
• Sandbox Organization Slug.
• Sandbox Webhook Signature Key.

Checkout defaults

• Default total amount in cents.
• Default initial amount in cents.
• Default item name.
• Default donation mode.
• Default SEPA setting.
• Default return, error, and back URLs.
• Optional default metadata JSON.

Shortcode

Basic usage:

[helloasso_checkout_button]

With an explicit amount and label:

[helloasso_checkout_button total_amount="2500" item_name="Donation"]

Supported attributes:

• total_amount – total amount in cents. Recommended amount attribute.
• amount – compatibility alias for total_amount; prefer total_amount.
• initial_amount – initial amount in cents. Defaults to total_amount.
• item_name – item label, up to 250 characters.
• contains_donation – accepts 1, true, yes, or on.
• enable_sepa – accepts 1, true, yes, or on.
• return_url – valid URL after successful checkout.
• error_url – valid URL after checkout error.
• back_url – valid URL when the visitor goes back.
• metadata – optional JSON object.
• lang – optional language such as fr, en, or es.

Shortcode attributes are sanitized and merged with configured defaults. The plugin stores checkout configuration server-side in a short-lived transient and renders only a generic button, public transient token, and nonce. The checkout creation response returns only the HelloAsso redirect URL, not the local payment_uuid.

Checkout creation is rate limited before the transient token is consumed, before a local payment row is created, and before HelloAsso OAuth/API calls run. Defaults are a 10-second cooldown and 5 attempts per 5-minute rolling window per hashed client identity. Excess attempts return HTTP 429 Too Many Requests. If WordPress cannot persist the rate-limit counter, checkout creation fails closed with HTTP 503 Service Unavailable and debug logs include checkout_rate_limit_storage_failed.

If checkout creation fails and the plugin cannot persist the local payment row as api_error, debug logs include checkout_payment_error_status_update_failed without exposing the full payment UUID or payer data.

Repeated renders of the same normalized shortcode configuration can reuse a render token for 5 minutes per hashed client and page context to reduce transient bloat. Once a token is consumed, the reuse index is invalidated so future renders receive a fresh token. A stale cached page or second tab can still submit an already consumed token and receive HTTP 410; refresh the page and try again. If WordPress cannot store the render token, the shortcode shows a controlled temporary-unavailable message instead of emitting an invalid token. If only the reuse index cannot be stored, checkout continues with the valid token and debug logs include checkout_render_token_reuse_index_failed.

Webhooks

Preferred webhook endpoints:

• /wp-json/helloasso-checkout/v1/webhook/sandbox
• /wp-json/helloasso-checkout/v1/webhook/production

Backward-compatible aliases are also registered:

• /wp-json/brumisphere-checkout-button-helloasso/v1/webhook/sandbox
• /wp-json/brumisphere-checkout-button-helloasso/v1/webhook/production

When an environment Webhook Signature Key is configured, the plugin requires the x-ha-signature header and validates it with HMAC SHA-256 and hash_equals(). Invalid signatures are always rejected when a key is configured.

If HelloAsso does not provide a Webhook Signature Key, administrators can explicitly enable Allow unsigned webhooks when signature key is missing. This fallback is disabled by default, shows admin warnings, logs bypass events only when Debug logging is active, and weakens webhook authenticity checks. It only applies while the matching environment key is missing, never creates new payments, and only updates an existing local payment matched by payment_uuid in the correct environment table.

For production, use a Webhook Signature Key when available and keep unsigned webhook processing disabled unless a controlled operational exception is required.

Webhook request bodies are limited to 262144 bytes by default and oversized requests return HTTP 413 Payload Too Large before signature validation or JSON parsing. Developers can adjust this with the hacb_max_webhook_body_bytes filter.

Signed webhook reconciliation uses payment_uuid, checkout_id, order_id, then payment_id. Unsigned fallback is stricter and only uses payment_uuid. If a webhook includes payment_uuid but no local payment row exists yet, the event is kept as pending_payment_match and returns HTTP 503 Service Unavailable so the provider can retry delivery. If the local payment row is found but the database update fails, the event is kept as retryable_update_failed without processed_at and also returns HTTP 503. A zero-row payment update is accepted only after rereading the row and verifying that the expected status is already stored; otherwise the event remains retryable. Events are claimed with a processing lease before payment updates run; fresh duplicate deliveries return in_progress, while stale processing rows can be retried. If a claim attempt fails while the latest stored event state is still retryable or stale, the endpoint returns HTTP 503 instead of treating it as a final duplicate. Critical webhook event transitions must persist before success is reported; if a transition such as processed cannot be stored, the endpoint returns HTTP 503.

Payments

The HelloAsso Checkout > Payments screen shows sandbox and production payment records. You do not need to change the active checkout environment to review both environments.

Payment status is created as pending during checkout creation and updated later by webhook processing.

Payment tables:

• {$wpdb->prefix}helloasso_checkout_sandbox_payments
• {$wpdb->prefix}helloasso_checkout_production_payments

Webhook events are stored separately for idempotency and troubleshooting. Raw webhook payloads are processed in memory and discarded by default; the event table stores only a minimized, sanitized operational summary.

External Services

This plugin connects to the HelloAsso service to create checkout intents and receive payment status updates. A HelloAsso account and API credentials are required.

After credentials have been configured, the plugin contacts HelloAsso only when a visitor explicitly clicks a rendered checkout button and when HelloAsso sends a webhook to the configured WordPress REST endpoint.

For OAuth and checkout creation, the plugin sends the configured HelloAsso client ID, client secret, organization slug, checkout amount, item name, donation and SEPA flags, return/error/back URLs, optional language, optional custom metadata, the local payment UUID, and the current site host. The browser is redirected to the checkout URL returned by HelloAsso.

The checkout button displays the HelloAsso logo from https://api.helloasso.com/v5/img/logo-ha.svg.

For webhooks, HelloAsso sends payment event data back to this WordPress site. The plugin processes the webhook body in memory, validates the configured signature when available, stores only minimized event data for idempotency/troubleshooting, and updates the matching local payment record. Webhook payloads can include payment identifiers, status, payer name, payer email, amount, and metadata depending on the event sent by HelloAsso.

Service endpoints used by the plugin:

• Production OAuth/API: https://api.helloasso.com
• Sandbox OAuth/API: https://api.helloasso-sandbox.com

HelloAsso terms and privacy information are available from HelloAsso:

• Terms: https://info.helloasso.com/cgu-associations
• Privacy: https://www.helloasso.com/confidentialite

Security and Privacy

• API client secrets stay in WordPress admin settings.
• Configured secrets are not rendered back into password field values.
• Empty secret fields preserve existing values; use the explicit clear checkbox to remove a stored secret.
• Access tokens are not printed in the front end.
• Webhook signature keys are never displayed in full.
• Authorization headers are not logged.
• Webhook payloads are not stored raw by default.
• Debug logs avoid full payer data and sensitive values.
• Admin screens require manage_options.
• Output is escaped and settings are sanitized.
• Checkout requests use nonce validation.
• Checkout creation is rate limited and does not store or log raw client IP addresses.
• Shortcode render tokens are reused over a short window to reduce transient bloat.
• Webhooks use HMAC SHA-256 validation when signature keys are configured.
• Oversized webhook bodies are rejected before signature validation, JSON parsing, or payload traversal.
• Webhook debug logs use presence fields and truncated hashes instead of full payment_uuid values or raw remote IP addresses.