Elara Help

Appearance

PayPal activation ​

PayPal supports the full checkout surface in Elara: one-time visit packs and recurring (monthly and yearly) memberships through the PayPal Subscriptions API. Recurring plans bill through PayPal-managed billing plans, and renewals, cancellations, and failed payments are reconciled from PayPal webhooks.

PayPal is off by default. Until Elara turns it on, PayPal does not appear as a payment provider option and no PayPal checkout runs, so going live takes two things: a live PayPal merchant account, which you set up yourself, and PayPal being turned on for Elara, which support does for you.

PayPal is turned on for Elara as a whole rather than brand by brand.

Viewing this provider configuration in Payment settings requires brands:read. Selecting PayPal, entering or removing credentials, connecting another provider, or saving changes requires brands:update. The separate payments:read permission covers Point of Sale and payment records, not provider configuration.

How to tell where you stand ​

Select PayPal as your provider in Payment settings and the panel shows one of Unavailable, Not configured, or Live.

Unavailable means PayPal has not been turned on yet. Checkout refuses PayPal in that state rather than taking test payments, so treat it as "not ready" and ask support, per step 3.

Not configured means PayPal is on but this brand is still missing at least one of the Client ID, Secret Key, and Webhook ID. Go to step 5.

Live means PayPal is on and the Client ID, Secret Key, and Webhook ID are saved for this brand. It does not confirm that they are correct, that PayPal is your saved default provider, or that the webhook is registered in PayPal, so it is a necessary signal rather than a complete one. A real test transaction is the only way to confirm checkout works end to end, which is why step 6 below exists.

You may also see Sandbox on a test or staging site, where PayPal always runs against PayPal's test system. It does not appear on a live account.

Activation steps ​

1. Create the live PayPal merchant account (business-side) ​

  • Sign up for (or use an existing) PayPal Business account.
  • Complete PayPal's business verification. Recurring billing (Subscriptions) must be enabled on the account, confirm it is available before going live.

2. Create a live REST app ​

  1. In the PayPal Developer Dashboard, switch to Live and create an app under your business account.
  2. Copy the Client ID and Secret.
  3. Ensure the app has Subscriptions enabled in its feature list.

3. Ask Elara support to turn PayPal on ​

Email Elara support and ask for PayPal to be enabled. This has to come before the next step: while PayPal is off, it is not offered as a provider option and cannot be saved as your default.

4. Register the webhook ​

Recurring billing depends on webhooks. The membership is created on the first successful charge (not at checkout), and renewals, cancellations, and failures are all driven by webhook events.

  1. In the live REST app, add a webhook pointing at:

    https://<your-api-host>/webhooks/paypal/<brandId>

    The brandId path segment scopes the webhook to a single brand; each brand registers its own webhook so signature verification runs against that brand's own webhook id.

  2. Subscribe to these event types:

    EventPurpose
    PAYMENT.SALE.COMPLETEDActivates the membership on first charge and advances coverage on each renewal
    PAYMENT.SALE.REFUNDED / PAYMENT.SALE.REVERSEDReconciles subscription charge refunds and reversals
    BILLING.SUBSCRIPTION.ACTIVATEDActivates a gift-funded first term or restores a suspended subscription
    BILLING.SUBSCRIPTION.PAYMENT.FAILEDDunning, triggers the payment-failed notification
    BILLING.SUBSCRIPTION.CANCELLEDMarks the subscription cancelled (coverage runs to period end)
    BILLING.SUBSCRIPTION.SUSPENDEDReflects a provider-side suspension
    BILLING.SUBSCRIPTION.EXPIREDReflects a subscription that reached its end
    PAYMENT.CAPTURE.REFUNDEDReconciles refunds issued from the PayPal side
    PAYMENT.REFUND.PENDING / PAYMENT.REFUND.CANCELLED / PAYMENT.REFUND.FAILEDKeeps a refund's outcome in sync when PayPal delays, cancels, or fails it
    CUSTOMER.DISPUTE.CREATED / CUSTOMER.DISPUTE.RESOLVEDReconciles disputes

Existing live webhooks also need both sale refund and reversal events. Refunding an individual subscription charge updates its payment record; it does not cancel the recurring plan or remove coverage purchased by another charge. Cancel or change the subscription separately when that is intended.

  1. Copy the generated Webhook ID. You paste it into Payment settings in the next step. Signature verification uses it to authenticate each event against PayPal, so until it is saved every delivery is rejected and recurring memberships will not activate.

5. Save the brand credentials ​

In Elara, open Settings > Payments for the brand and enter the live Client ID, Secret Key, and the Webhook ID from the previous step. Set PayPal as the default provider and save, then select Test saved credentials.

The test authenticates with the saved app, fetches the Webhook ID from that app, checks that it targets /webhooks/paypal/<brandId>, and checks every event in step 4. A Webhook ID from another app, the wrong target, or an incomplete event list fails with the field that needs repair. One-time PayPal products remain available when the app credentials work, but recurring plans stay hidden and their checkout stays blocked until this webhook check passes. The Secret Key is encrypted per brand. The Client ID and Webhook ID are stored as non-secret identifiers so the settings page can show their saved values. Each franchise/brand connects its own merchant account.

6. Verify live ​

  1. Confirm the Payments settings panel shows Live for the brand, that PayPal is selected and saved as the default provider, and that Test saved credentials succeeds.
  2. Run a live one-time (visit pack) checkout and confirm the membership appears. This exercises the synchronous order and capture path.
  3. Run a live recurring (monthly) checkout and approve it in PayPal. The settings test proves the webhook configuration, while this checkout proves the full delivery and activation path. A recurring membership is created on the first successful charge, not at checkout.
  4. Cancel the subscription in PayPal and confirm the CRM reflects it.

Troubleshooting ​

  • PayPal is missing from the provider dropdown. It has not been turned on yet. Ask support to enable it, per step 3. If your brand already had PayPal saved as its provider before it was switched off, PayPal stays in the dropdown and the panel reads Unavailable instead, so the dropdown on its own is not proof that PayPal is on.
  • PayPal not offered at checkout after saving the Client ID, Secret Key, and Webhook ID. Check the Payments settings panel. If it reads Unavailable, PayPal has not been turned on yet, so ask support to enable it. If it reads Live and checkout still refuses, confirm PayPal is saved as the default provider, not just selected in the dropdown.
  • Recurring plans are not offered, but visit packs are. Select Test saved credentials. The saved Webhook ID must belong to the saved PayPal app, target /webhooks/paypal/<brandId>, and subscribe to every event in step 4. Recurring checkout fails closed when any check fails, while synchronous one-time checkout remains available.
  • Membership never activates after a recurring checkout. Run Test saved credentials again, then inspect PayPal's delivery log for the webhook. A successful settings test proves the current ownership, target, and event subscriptions; the delivery log shows whether PayPal sent PAYMENT.SALE.COMPLETED and what response it received.
  • A Webhook ID can be repaired while a refund is pending. Refund calls use the saved Client ID and Secret Key, not the Webhook ID. The Webhook ID can therefore be filled in or replaced without waiting for a legacy refund attempt to finish, which avoids making reconciliation wait on the configuration repair it needs.
  • Removing a credential is refused while subscriptions are billing. PayPal keeps charging a subscription after you move the studio to another provider, and each renewal, cancellation and refund for it arrives on a webhook we cannot accept without all three of the Client ID, Secret Key, and Webhook ID. Removing any one of them would leave those members paying while their memberships stop advancing, so it is refused until the subscriptions are cancelled in PayPal. Moving the studio to another provider without removing anything is always allowed: the saved Client ID, Secret Key, and Webhook ID keep reconciling the old subscriptions while new checkouts go to the new provider.
  • An unfinished approval also blocks credential changes. An APPROVAL_PENDING subscription can still be approved later. Cancel the unfinished subscription in PayPal, then retry Save. Elara retires provider-confirmed cancelled or expired attempts that have no completed-payment evidence. If PayPal cannot verify one attempt, the error says that its state is unknown instead of claiming that it is billing.
  • Removing a credential is refused. While PayPal is the saved default provider, its Client ID, Secret Key, and Webhook ID cannot be taken away one at a time. To remove the Secret Key, click Remove saved key while PayPal is still shown, then select the replacement provider (or None) and save. The pending removal survives that switch. Payment settings deliberately keeps the Client ID and Webhook ID, so switching providers does not erase identifiers you may need when returning to PayPal. If the save is refused, see the bullet above about subscriptions that are still billing.
  • Renewals not recorded. Same cause as above. Confirm the webhook subscription includes PAYMENT.SALE.COMPLETED and that the saved Webhook ID belongs to your live app, not a sandbox one.