Reset Account Pin Code

This guide outlines how to enable a user to reset their PIN code. Note users must know their original PIN code to reset it. Otherwise, they must follow the Account Recovery flow outlined in this guide.

Before you begin, make sure you have:

• Completed the Create Your First Wallet guide to set up a user and their first wallet.

• Followed the Receive Inbound Transfer guide or Send Outbound Transfer guide to initialize user activity (optional, but helps validate wallet functionality).

• Installed and configured the sample app for your platform (web, iOS, or Android).

• Registered a callback to handle the Reset PIN flow. This includes:

  1. Sending the reset PIN request
  2. Handling the challenge response
  3. Completing the PIN verification

  See the sample app for an example implementation.

Follow these steps to guide a user through resetting their PIN using the User-Controlled Wallets SDK:

After you set up one of the web, iOS, or Android sample applications, you can:

1. Run the sample app and simulator.
2. Obtain your App ID. To get the App ID, do one of the following:
   1. Access the developer console and navigate to the configurator within user-controlled wallets. From there, copy the App ID.
   2. Make an API request to GET /config/entity and copy the App ID from the response body.
3. Add the App ID to the sample app.

Next, you need to acquire a session token. To do this, you make a request to thePOST /users/token using the previously created userId in Step 1. The userToken is a 60-minute session token used to initiate requests requiring a user challenge (PIN code entry). After 60 minutes, the session expires, and a you must generate a new userToken using the same endpoint.

From this response, you can acquire the encryptionKey and userToken which you provide in the respective sample app fields. You also use the userToken in the next step.

// Import and configure the user-controlled wallet SDK
const {
  initiateUserControlledWalletsClient,
} = require('@circle-fin/user-controlled-wallets')
const circleUserSdk = initiateUserControlledWalletsClient({
  apiKey: '<API_KEY>',
})

const response = await circleUserSdk.createUserToken({
  userId: '2f1dcb5e-312a-4b15-8240-abeffc0e3463',
})

{
  "data": {
    "userToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCC9.eyJkZXZlbG9wZXJFbnRpdHlFbnZpcm9ubWVudCI6IlRFU1QiLCJlbnRpdHlJZCI6IjRlMDdhOGM5LTIxOTAtNDVlNC1hNjc0LWQyMGFkNjg4MWI3YyIsImV4cCI6MTY5MDU1MjcwNywiaWF0IjoxNjkwNTQ5MTA3LCJpbnRlcm5hbFVzZXJJZCI6ImQ2ZjkzODliLWQ5MzUtNWFlYy1iOTVhLWNjNTk1NjA2YWM5NiIsImlzcyI6Imh0dHBzOi8vcHJvZ3JhbW1hYmxlLXdhbGxldC5jaXJjbGUuY29tIiwianRpIjoiMmE0YmJlMzAtZTdkZi00YmM2LThiODMtNTk0NGUyMzE2ODlkIiwic3ViIjoiZXh0X3VzZXJfaWRfOSJ9.dhfByhxZFbJx0XWlzxneadT4RQWdnxLu3FSN9ln65hCDOfavaTL1sc4h-jUR8i4zMmfdURw3FFcQIdSbm-BUg6M7FP_fp-cs9xBbNmRZa31gMd1aKdcajJ9SvlVrfUowYfGXM3VcNF8rtTFtW-gk1-KzU4u10U35XXbbMcW1moxE0Rqx_fKotDgk2VdITuuds5d5TiQzAXECqeCOCtNoDKktMkglltbnLxOaRl2ReZjGt-ctD2V0DbYNO4T_ndPSUDI6qD7dXQRed5uDcezJYoha3Qj3tFGBglEnox2Y6DWTbllqjwmfTGrU8Pr0yz4jQz7suGwmiCzHPxcpYxMzYQ",
    "encryptionKey": "Tlcyxz7Ts9ztRLQq5+pic0MIETblYimOo2d7idV/UFM="
  }
}

Make a request to PUT /user/pin using the userToken returned from Step 1. This call returns a challengeId, which is used with the Circle Programmable Wallet SDK to have the user reset their PIN code.

const response = await circleUserSdk.updateUserPin({
  userToken: '<USER_TOKEN>',
})

{
  "data": {
    "challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
  }
}

Using the sample application, enter the userToken and secretKey returned from Step 1. Enter the challengeId returned from Step 2.

You should be ready to execute the reset PIN code workflow via the Circle Programmable Wallet SDK. Once you've entered the required fields indicated in Step 3, click Execute to continue.

The sample application takes you through the authentication and PIN code reset process, which includes the user entering their PIN code to authorize the reset and entering a new PIN code.

Make a request GET /user/challenges/{id} using the challengeId received from Step 2 to retrieve the status of the challenge. Additionally, Circle sends a notification to a subscribed endpoint once the PIN code reset is complete. For a full list of possible statuses, see the Asynchronous States and Statuses guide.

const response = await circleUserSdk.getUserChallenge({
  userToken: '<USER_TOKEN>',
  challengeId: '<CHALLENGE_ID>',
})

{
  "data": {
    "challenge": {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "correlationIds": ["54399e5a-1bf6-4921-9559-10c1115678cd"],
      "status": "COMPLETED",
      "type": "CHANGE_PIN"
    }
  }
}

WHAT'S NEXT

The user has successfully reset their PIN code! Move on to recover an account guide to complete:

• Recover an Account