Authentication flow

Authentication flow

In order to get access to the user account to make payments and get their profiles, you need them to authorize your app.

This is how the authorization process works:

  1. The user is redirected to the redirectionUrl from your app, sending them to HandCash.
    Example: https://app.handcash.io/#/authorizeApp?appId=634e592573e133a1ee15a1b7

  2. HandCash will ask the user if they would like to grant permissions to your app: the user can either accept or decline access.

  3. The user will then be redirected, from HandCash back to your app. That redirection URL will contain the authToken you need to use their account from the SDK.
    Example: https://my-app.com/handcash/success?authToken=02ac9c3...ae7410

User authentication flow

User authentication flow

Code

To authenticate a user, generate a redirectionUrl using the SDK:

const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect({ 
   appId: '<app-id>', 
   appSecret: '<secret>',
});

// Use this field to redirect the user to the HandCash authorization screen.
const redirectionLoginUrl =  handCashConnect.getRedirectionUrl();

// Alternatively, you can compose the URL manually:
const redirectionLoginUrl = `https://app.handcash.io/#/authorizeApp?appId=${appId}`

Redirection

Serving the URL to the user will redirect them to HandCash, which will then prompt the user to grant permissions for your app.

App authorization preview in the HandCash App

App authorization preview in the HandCash App

Once the user selects accept or decline, they will be redirected back to your app's Authorization Success URL or Authorization Failed URL.

While redirecting, an authToken query parameter will be added to the request:

  • If accepted: <your-auth-success-url>?authToken=<token>
  • If declined: <your-auth-decline-url>

Now you can use the authToken to make payments and get the user profile.

Keep it safe!

Keep the authToken in a safe environment so it's not exposed to unwanted eyes.

Custom redirection parameters

If you need to pass any custom parameters, use the following syntax. The custom parameters will be passed back to your app upon redirect.

handCashConnect.getRedirectionUrl({'state': 'xyz'});

The redirection link above would make the redirection URL to your app look like this: https://my-app.com/handcash/success?authToken=02ac9c3...ae7410&state=xyz