Create user accounts

📘

App feature Required

Your app requires the CreateAccount feature. Contact our team to enable it if you still don't have it.

Overview

For an optimal onboarding flow for your users, you can create them a HandCash account in case they don't have one yet.

This page describes the steps in order for your app to create new HandCash accounts.

1. Generate a new authentication keypair (private and public key)
2. Send a verification code to the email provided by the user
3. Verify the email code that was sent to the user's email
4. Create a new account for the verified email along with some authentication public key
5. Initialize the account as usually using the authentication private key

👍

Eventually, users will complete their account to enable all the wallet features including the ability to top up their balance.

Send the email verification code

Once users provide an email, you can send them a verification code through the HandCash SDK.

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

Make sure you keep requestIdin a good place as you will need it for the next step.

Verify the email code and create an account

After users receive the verification email, they should provide the verification code to your app.

At this point, you need to create a new authentication key pair. The public key will be sent to HandCash for the account creation process to associate the user with your app. The private key will be used to access the created account (trigger payments, get profile, etc...).

❗

Keep it safe!

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

const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect({ 
   appId: '<app-id>', 
   appSecret: '<secret>',
}); 
const keyPair = handCashConnect.generateAuthenticationKeyPair();
await handCashConnect.verifyEmailCode(requestId, verificationCode, keyPair.publicKey);
referralAlias = 'myHandle'; //optional parameter
const publicProfile = await handCashConnect.createNewAccount(keyPair.publicKey, email, referralAlias);

// You are ready to use this account as usual
const cloudAccount = handCashConnect.getAccountFromAuthToken(keyPair.privateKey);

Error handling

The user already has a HandCash account

If the user already has a HandCash account, the SDK will trigger a specific error. We suggest you redirect the user to HandCash following the usual login flow:

try {
    const requestId = await handCashConnect.requestEmailCode(email);
  // Continue the account creation process
} catch (error) {
  if (error.message === 'Full account exist - redirect user to login instead') {
    const redirectionLoginUrl = handCashConnect.getRedirectionUrl();
    // Redirect the user to follow the login process
  } else {
    // Handle the error normally
  }
}

Caveats

 ⚠️ Use the proper unique ID ⚠️

When you create an account HandCash assigns a temporary username (handle). When users complete the account creation in HandCash, they will define a custom username (handle). So don't keep references to the username (handle) as it will change at some point. Use the id property available in the publicProfile.

const publicProfile = await handCashConnect.createNewAccount(keyPair.publicKey, email);

const uniqueId = publicProfile.id; // DO THIS

const uniqueId = publicProfile.handle; // DON'T DO THIS

What happens if I lose the authToken?

As long as the user hasn't migrated yet to a full account in the HandCash app, the process to create an account can be repeated for the same email to obtain a new access key if needed.