Customer Onboarding & PIN Setup

Creating a customer custody wallet begins with two steps: registering the customer profile in your organization and initiating the secure PIN setup through the Planbok Gateway.

1. Register the Customer Profile

First, you must create a customer record in your Planbok organization. This profile will act as the identity that "owns" all subsequent blockchain wallets.

Endpoint: POST /v2/customers
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body:

Code
{
  "name": "Jane Doe",
  "refId": "unique_user_id_001"
}

• refId: This should be your internal system's unique identifier for the user. It allows you to map Planbok wallets back to your database.

2. Initialize PIN Setup

Once the customer is created, you must initiate the PIN Setup challenge. This creates the user's first security shard, which is protected by their personal PIN.

Endpoint: POST /v2/customers/{id}/initialize
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body:

Code
{
  "redirectUrl": "https://yourapp.com/dashboard/onboarding-complete"
}

The Response

Planbok will return a Challenge object:

Code
{
  "success": true,
  "data": {
    "challengeId": "69a519b8ee7a220fecf3ca75",
    "redirectUrl": "https://gateway.planbok.io/pin/setup?challenge=...",
    "status": "pending"
  }
}

3. Redirecting the User

You must now redirect your user to the redirectUrl provided in the response.

1. Gateway Entry: The user arrives at the Planbok Gateway.
2. PIN Selection: The user enters and confirms their 6-digit PIN.
3. Key Generation: The Gateway performs client-side derivation of the user's shard.
4. Mandatory Recovery Setup: The user must set up account recovery via security questions or email. This creates a backup of their encrypted shard and is required before any wallets can be provisioned.
5. Redirect Home: Once complete, the Gateway automatically redirects the user back to the redirectUrl you provided (e.g., https://yourapp.com/dashboard/onboarding-complete).

4. Verification (Optional)

You can verify if a customer has successfully set up their PIN by fetching their profile:

Endpoint: GET /v2/customers/{id}

Response Check:

Code
{
  "data": {
    ...
    "hasPin": true,
    "hasRecovery": false,
    "status": "active"
  }
}

[!IMPORTANT] Recovery setup is mandatory. Users who do not complete this step will not be able to provision new wallets or sign transactions. Always ensure your application checks the hasRecovery flag.

Next Steps

Now that the customer has a PIN, you can Provision their first wallets.