> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aurasos.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aurasos.com/_mcp/server.

# 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

| AURA                                                       | You (the integrator)                         |
| ---------------------------------------------------------- | -------------------------------------------- |
| Embeds the Panic API in your branded app                   | Build and host the **signup handler**        |
| Manages subscriptions (create / query / update / cancel)   | Process payment via your chosen gateway      |
| Provides emergency response while a subscription is active | Store card details and run recurring billing |

## The flow

```mermaid
sequenceDiagram
    participant App as White-label app
    participant Handler as Your signup handler
    participant Gateway as Payment gateway
    participant AURA as AURA Panic API
    App->>Handler: Open webview (token + redirectUrl + userid)
    Handler->>Gateway: Take payment
    Gateway-->>Handler: Payment result
    Handler->>AURA: Activate subscription (POST /panic-api/v2/subscriptions)
    Handler->>App: Redirect to redirectUrl?success=true
    App->>AURA: Verify subscription
    AURA-->>App: Success / failure screen
```

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](#activating-the-subscription) 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`](/api-reference/subscriptions/list-subscription-types) 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`](/api-reference/subscriptions/create-subscription):

```json
{
  "customerId": 178921,
  "subscriptionTypeId": 12,
  "validFrom": "2024-11-06T00:00:00.000Z",
  "validTo": "2024-12-11T00:00:00.000Z"
}
```

## 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}`](/api-reference/subscriptions/update-subscription).
* **Cancel early** — [`DELETE /panic-api/v2/subscriptions/{subscriptionId}`](/api-reference/subscriptions/delete-subscription);
  access is lost immediately.
* **Re-subscribe** — lapsed or deleted subscriptions can't be recovered; create a
  new one with [`POST /panic-api/v2/subscriptions`](/api-reference/subscriptions/create-subscription).
* **Family** — use `WEB_SIGNUP_FAMILY`; dependants are linked to the main member's
  subscription and lose access if it lapses.

> **Note**
>
> All dates use **ISO 8601 in UTC** (e.g. `2020-05-12T13:05:25.961Z`). Convert from
> your local timezone so subscriptions activate when intended.