Users, Subscriptions, and White-label External Gateway Guidelines

This doc serves as a guide to managing user subscriptions on the AURA API as well as a template for setting up an external payment platform in an AURA Panic White-Label App.

User Registration

In order to register a user you will need valid API credentials. To do this, first contact the AURA team via developers@aura.services and ask them to generate a set of credentials. If API access is required for a white-label offering they will explicitly need to enable the white-label registration flows for you.

All users registered via the API will automatically have subscriptions activated. These subscriptions can be queried, deactivated, and modified. Details to follow.

Authentication and Authorization

Authentication to the AURA API can be done in one of two ways: via either a backend/server (client_credentials) or a user (password) authentication grant.

If an authentication request is successful, an authorization token will be returned in the body of the response under the accessToken tag alongside an expiry time for the token based on seconds passed since the unix epoch.

These authorization tokens can then be used to access endpoints on the AURA API by including them in the Authorization header with the Bearer prefix.

All authorization tokens are Json Web Tokens (JWTs) conforming to the RFC 7519 open standard for securely transmitting information between parties. Authorization tokens can only be obtained by successfully authenticating to the AURA API.

Integration API Registration

Obtain a server token with the credentials provided by sending a request to:

POST /oauth/token

Body:
{
    "clientId": "*********",
    "clientSecret": "**********"
}

With a valid server token in hand you will be able to register a user by adding your server token to the Authorization header with a Bearer prefix and sending the following request with the relevant mobile number:

POST /oauth/user

Body:
{
    "email": "test@123.co.za",
    "password" "************"
}

Having successfully registered a user, you can then obtain a token for that user by sending a request to:

POST /oauth/token

Body:
{
    "clientId": "***********"
    "email": "example@mail.com"
    "password": "*****"
}

This is the token that will be used to initiate a panic for a specific user. There tokens are extremely long lived and are designed to be cached.

White-Label API Registration

All of the white-labels handle user sign-up dynamically on logging in with a mobile-number/OTP combination. The user is then able to activate their subscription inside the app using either the coupon mechanism or an external payment gateway where applicable.

For certain use cases a pre-registration of users with an already activated subscription is required. This is primarily for re-sellers who have made an app sale already and want to the user not to have to worry about entering a coupon code.

Obtain a server token with the credentials provided by sending a request to:

POST /oauth/token

Body:
{
    "clientId": "*********",
    "clientSecret": "**********"
}

With a server token in hand you will be able to register a user by adding your server token to the Authorization header with a Bearer prefix and sending the following request with the relevant mobile number:

POST /oauth/user

Body:
{
    "mobileNumber": "+27761234567"
}

Optionally you can pass in a coupon code and/or a customer object that has the user’s information. Passing in the customer object allows you create a user with a pre-populated profile. Passing in a coupon code will activate a coupon subscription instead of a SMS subscription for the customer.

POST /oauth/user

Body:
{
    "mobileNumber": "+27721231517"
    "couponCode":"IHOR34WCA",
    "customer": {
        "name": "john" ,
        "surname" : "doe",
        "gender":"Male",
        "email":"john@doe.com",
        "vehicleMake":"rezvani",
        "vehicleModel":"tankX",
        "vehicleColour":"grey",
        "vehicleLicensePlate":"RE ZVA NI GP",
        "dateOfBirth":"1903-03-03"
    }
}

User Subscriptions

A registered user will always be able to obtain a valid token from the AURA API however without an active subscription, a user will not be able to create a panic.

Fetching a User’s Subscriptions

A complete history of a user’s subscriptions is kept on the AURA API. This is available for querying by fetching from :

GET /customers/{identifier}/subscriptions

Here the identifier can be one of the following:

customerId → Unique identifier for a customer on the AURA DB.
mobileNumber → Unique for White-label offerings per source.
email → Unique for API integrations per source.
auth0UserId → Unique per integration per source.

Generally the safest query to run here is using the customerId or the auth0UserId. The auth0UserId can be obtained by decoding the user token and follows the format auth0|userId for API integrations and sms|userId for white-label offerings.

The resulting data is an array of subscriptions associated with the customer:

[
  {
    "id": 23,
    "subscriptionTypeId": 2,
    "customerId": 3,
    "updatedAt": "2017-07-28T08:28:17.801Z",
    "createdAt": "2017-07-28T08:28:17.801Z",
    "CancelledDate": "2017-07-28T08:28:17.801Z",
    "CancelledReason": "Did not like that customer",
    "validFrom": "2017-07-28T08:28:17.801Z",
    "validTo": "2020-07-28T08:28:17.801Z"
  },
  {
    "id": 24,
    "subscriptionTypeId": 2,
    "customerId": 3,
    "updatedAt": "2017-07-28T08:28:17.801Z",
    "createdAt": "2017-07-28T08:28:17.801Z",
    "CancelledDate": null,
    "CancelledReason": null,
    "validFrom": "2017-07-28T08:28:17.801Z",
    "validTo": "2020-07-28T08:28:17.801Z"
  }
]

Here, only one subscription will be active. A subscription is active if the following conditions are satisfied:

validFrom < current date.
validTo > current date.
CancelledDate is null.
CancelledReason is null.

Cancelling a Users’s subscription

Cancelling is done by sending the following request with a valid user or server token and optionally supplying a cancellation reason:

DELETE /subscription/{subscriptionId}

Body (Optional):
{
    "reason": "Customer no longer active"
}

Here the subscriptionId should be obtained from the /customers/{identifier}/subscriptions endpoint.

Modifying a User’s subscription

If you find yourself needing to modify existing subscriptions' validFrom and validTo dates i.e if you have product offerings for certain periods etc. Please contact the AURA dev team via developers@aura.services and they will expose endpoints to suit your needs.

White-Label External Payment Gateways

In the event that you have a white-labelled panic app from AURA, you may decide that your users should be able to activate a subscription by filling in their card details. Should this thought occur to you there are two options: App store payment gateways and using an external page redirect.

App Store Payment Gateways

This is not yet implemented. A PoC was done on it and should there be a requirement for it, the dev team will get on it. Downside here is that Apple and Google take a very large cut of your debit orders hence the low uptake.

External Page Redirects

Should you wish to embed a payment gateway into your white-label app and avoid using the Apple or Google payment gateways there is a configurable option on the white-labels for activating a subscription via and external redirect.

This process ships 99% of the work for implementation onto you. The team at AURA has no interest in handling individual user’s billing. As such you will need to implement the following (refer to diagram below):

A user that is logged in to the app without a valid subscription will be presented with the option to activate a subscription either via coupon code or via a web sign-up.
On selecting web sign-up and hitting activate, a browser will open up taking the user to an external page (Sign-up Handler). This is done by providing AURA with an URL to the Sign-up Handler web page. The app will then open up the browser and pass through the logged in users unique identifier and well as an identifier for the app as query parameters.
On being navigated to the Sign-up Handler, the user will need to complete a payment flow. This flow is entirely independent of AURA.
On successfully processing payment, the Sign-up Handler page will redirect to the AURA Payment Handler indicating a successful or unsuccessful payment. The AURA Payment Handler will then either activate a subscription or ignore based on pyament success and then take the user back in to the app.

An example external redirect system can be seen below: