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.
- Generate a new authentication keypair (private and public key)
- Send a verification code to the email provided by the user
- Verify the email code that was sent to the user's email
- Create a new account for the verified email along with some authentication public key
- 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 requestId
in 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.
Updated 10 months ago