Third-party payment gateways

Use this integration when you want to process white-label subscription payments through your own third-party gateway (Payfast, NetCash, SagePay, Stripe, Safaricom, or another provider). After a successful payment, activate the customer’s subscription through the Panic API.

This is distinct from AURA-hosted payment options, which are available only when the customer source and app have been configured for a supported provider. With a third-party gateway, pricing, card storage, gateway choice, recurring collections, refunds, and payment compliance remain your responsibility.

Who does what

The flow

1. In the app, a customer without a subscription chooses Online subscription.

2. The app opens an in-app webview to your signup handler, passing three query parameters:

   • token — the customer’s AURA OAuth access token (a JWT). Do not log it or persist it in analytics. Its claims include customerId and sub — see Resolve the customer below before using either.
   • redirectUrl — where to send the customer when you’re done.
   • userid — the token’s sub claim: the customer’s Auth0 user identifier (for example auth0|abc123). This is not the AURA customerId — the two are unrelated values and userid cannot be used to look up the AURA customer on its own.

   e.g. https://my.paymentgateway.com?token=xxxxx&redirectUrl=...&userid=...

3. Your signup handler takes payment through your gateway.

4. On success, activate a subscription via the Panic API, then redirect back to redirectUrl with success=true (or success=false on failure), preserving the original parameters. The app watches the webview URL for the success parameter to decide which screen to show.

5. AURA’s payment handler verifies the subscription and returns the customer to the app, which shows a success or failure screen.

Activating the subscription

After payment succeeds, in your signup handler:

1. Find the subscription type — GET /panic-api/v2/subscriptions/subscriptionTypes and pick the entry whose value is WEB_SIGNUP_SINGLE (or WEB_SIGNUP_FAMILY for family plans). Store its id.
2. Resolve the customer. There is currently no API endpoint that resolves a customer from a bearer token on your behalf, so decoding the token is the supported way to get the customerId for this flow. Verify the token’s signature against AURA’s Auth0 JWKS before trusting it — do not decode it without verifying first — then read the customerId claim. userid (sub) is a different value and will not resolve to an AURA customer.
3. Create the subscription — POST /panic-api/v2/subscriptions:

1
{
2
  "customerId": 178921,
3
  "subscriptionTypeId": 12,
4
  "validFrom": "2024-11-06T00:00:00.000Z",
5
  "validTo": "2024-12-11T00:00:00.000Z"
6
}

Subscription lifecycle

• Once-off — set validTo to the actual service end date agreed with the customer. Do not use an arbitrary century-long entitlement as a substitute for an explicit commercial term.
• Monthly renewal — set validTo to ~35 days out (allow a few days’ grace for retries), then renew each cycle with PUT /panic-api/v2/subscriptions/{subscriptionId}.
• Cancel early — DELETE /panic-api/v2/subscriptions/{subscriptionId}; access is lost immediately.
• Re-subscribe — lapsed or deleted subscriptions can’t be recovered; create a new one with POST /panic-api/v2/subscriptions.
• Family — use WEB_SIGNUP_FAMILY; dependants are linked to the main member’s subscription and lose access if it lapses.