# Wallet

### Register

If the user's login result `loginStatus` is `pinRequired` or `registerRequired`, proceed with the registration process.

<table><thead><tr><th width="212">loginStatus</th><th>Description</th></tr></thead><tbody><tr><td><code>pinRequired</code></td><td>Creates the user's wallet and registers the app..<br>Requires the user to input a PIN for the initial wallet creation.<br>It is recommended to request the PIN input twice for verification.</td></tr><tr><td><code>registerRequired</code></td><td>Since this process registers the account of an already created wallet with the app, one PIN input is required for existing PIN verification.</td></tr></tbody></table>

{% hint style="info" %}
Wepin provides a UI Library for receiving the user's PIN input. Use this library to receive the PIN from the user, and then use the result to proceed with the registration process. Refer to the PIN pad library list for each platform on the [API overview page](/en/api/overview.md).
{% endhint %}

```http
POST /v1/app/register HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

{
	"appId": "<String>",
	"userId": "<String>",
	"loginStatus": "pinRequired",
	"UVD": {
		"b64SKey": "<String>",
		"b64Data": "<String>",
	},
	"hint": {
		"version": 1
		"length": "Ng==",
		"data": "MSoqKjUq",
	},
}
```

#### Request

**Parameter**

<table><thead><tr><th width="150">Name</th><th width="106">Type</th><th width="393">Description</th><th>Required</th></tr></thead><tbody><tr><td>appId</td><td>String</td><td>The ID received after executing <a href="/pages/EQaogmCNNR1GmRx6oihQ#check-app-information">Check App Information</a>.</td><td>O</td></tr><tr><td>userId</td><td>String</td><td>The <code>userId</code> obtained from the <code>userInfo</code> during the <a href="/pages/EQaogmCNNR1GmRx6oihQ#login">Login</a> process.</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td>The user's wallet ID. Required when <code>loginStatus</code> is <code>registerRequired</code>.</td><td>X</td></tr><tr><td>loginStatus</td><td>String</td><td>The <code>loginStatus</code> value received from the <a href="/pages/EQaogmCNNR1GmRx6oihQ#login">Login</a> result.</td><td>O</td></tr><tr><td>UVD</td><td>Object</td><td>The encrypted value of the PIN entered by the user. This is obtained through the PIN Pad Library.</td><td>X</td></tr><tr><td>hint</td><td>Object</td><td>A hint related to the PIN entered by the user. This is obtained through the PIN Pad Library and is valid only when <code>loginStatus</code> is <code>pinRequired</code>. The hint is sent to the server and delivered to the user's email.</td><td>X</td></tr></tbody></table>

#### Response

**Success Response**

<table><thead><tr><th width="196">Name</th><th width="156">Type</th><th>Description</th></tr></thead><tbody><tr><td>success</td><td>Boolean</td><td>Success status</td></tr></tbody></table>

**Error Response**

<table><thead><tr><th width="195">Name</th><th width="152">Type</th><th>Description</th></tr></thead><tbody><tr><td>statusCode</td><td>Integer</td><td>Http status code value</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp value</td></tr><tr><td>path</td><td>String</td><td>Specifies which path (API) the error response is associated with.</td></tr><tr><td>message</td><td>String</td><td>Describes the error situation.</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>Returned when the entered PIN is incorrect, showing the number of remaining attempts for PIN verification.</td></tr></tbody></table>

If the response includes `RemainPinTryCnt`, it indicates that the PIN entered is incorrect. In this case, the client should provide an appropriate UI/UX to inform the user accordingly.

***

### Changing User Wallet PIN <a href="#changing-user-wallet-pin" id="changing-user-wallet-pin"></a>

Users can change the PIN of their wallet. The `nonce` value in `newUVD` must be set as `UVD's nonce + 1`.

```http
PATCH /v1/wallet/pin/change HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

{
	"UVD": {
		"b64SKey": "<String>",
		"b64Data": "<String>",
	},
	"newUVD": {
		"b64SKey": "<String>",
		"b64Data": "<String>",
	},
	"hint": {
		"version": 1
		"length": "Ng==",
		"data": "MSoqKjUq",
	},
}
```

#### Request

**Parameter**

<table><thead><tr><th width="123">Name</th><th width="105">Type</th><th width="419">Description</th><th>Required</th></tr></thead><tbody><tr><td>UVD</td><td>Object</td><td>User Verification Data.<br>The encrypted value of the user's current PIN. This is obtained through the PIN Pad Library.</td><td>O</td></tr><tr><td>newUVD</td><td>Object</td><td>User Verification Data. <br>The encrypted value of the user's new PIN. This is obtained through the PIN Pad Library.</td><td>O</td></tr><tr><td>hint</td><td>Object</td><td>A hint related to the user's entered PIN. This is obtained through the PIN Pad Library and sent to the server. The hint is then sent to the user's email.</td><td>O</td></tr></tbody></table>

#### Response

**Success Response**

<table><thead><tr><th width="201">Name</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>Boolean</td><td>Success status</td></tr></tbody></table>

**Error Response**

<table><thead><tr><th width="205">Name</th><th width="183">Type</th><th>Description</th></tr></thead><tbody><tr><td>statusCode</td><td>Integer</td><td>Http status code value</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp value</td></tr><tr><td>path</td><td>String</td><td>Specifies which path (API) the error response is associated with.</td></tr><tr><td>message</td><td>String</td><td>Describes the error situation.</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>Returned when the entered PIN is incorrect, showing the number of remaining attempts for PIN verification.</td></tr></tbody></table>

### Reset PIN Try Count for User Wallet <a href="#reset-pin-try-count-for-user-wallet" id="reset-pin-try-count-for-user-wallet"></a>

Requests a reset of the user's wallet PIN try count value.

```http
GET /v1/wallet/{walletId}/pin/reset-try-count?userId={userId} HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}
```

#### Request

**Parameter**

<table><thead><tr><th width="122">Name</th><th width="97">Type</th><th width="399">Description</th><th>Required</th></tr></thead><tbody><tr><td>userId</td><td>String</td><td>The <code>userId</code> obtained from the <code>userInfo</code> during the <a href="/pages/EQaogmCNNR1GmRx6oihQ#login">Login</a> process.</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td>Wallet ID received as a result of the <a href="/pages/EQaogmCNNR1GmRx6oihQ#login">Login</a>.</td><td>O</td></tr></tbody></table>

#### Response

**Success Response**

<table><thead><tr><th width="189">Name</th><th width="152">Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>Boolean</td><td>Success status</td></tr></tbody></table>

**Error Response**

<table><thead><tr><th width="191">Name</th><th width="152">Type</th><th>Description</th></tr></thead><tbody><tr><td>statusCode</td><td>Integer</td><td>Http status code value</td></tr><tr><td>walletId</td><td>String</td><td>The user's wallet ID.</td></tr><tr><td>maxTryCount</td><td>String</td><td>The maximum allowed PIN try count for the wallet.</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>Returned when the entered PIN is incorrect, showing the number of remaining attempts for PIN verification.</td></tr><tr><td>recvResetCmd</td><td>Boolean</td><td><code>/v1/wallet/{walletId}/pin/reset-try-count</code> Indicates whether the operation was successful.</td></tr><tr><td>lockTime</td><td>String</td><td>The time remaining until the PIN try count is reset.</td></tr><tr><td>releaseTimestamp</td><td>String</td><td>The time when the user's PIN try count will be reset.</td></tr></tbody></table>

***

### Verification of User Wallet PIN <a href="#verification-of-user-wallet-pin" id="verification-of-user-wallet-pin"></a>

Verifies the PIN number of the user's wallet.

After [Resetting the user's Wallet PIN Try Count](#pin-reset-try-count), the PIN verification process must be performed.

```http
POST /v1/wallet/pin/verify HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}
```

#### Request

**Parameter**

<table><thead><tr><th width="131">Name</th><th width="121">Type</th><th width="341">Description</th><th>Required</th></tr></thead><tbody><tr><td>userId</td><td>String</td><td>The <code>userId</code> obtained from the <code>userInfo</code> during the <a href="/pages/EQaogmCNNR1GmRx6oihQ#login">Login</a> process.</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td>The user's wallet ID.</td><td>O</td></tr><tr><td>UVD</td><td>UVD</td><td>User's UVD. Use the response value from PIN Pad Library - generateAuthPINBlock.</td><td>O</td></tr></tbody></table>

#### Response

**Success Response**

<table><thead><tr><th width="196">Name</th><th width="175">Type</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>string</td><td>Request success or failure ("success" or "fail")</td></tr><tr><td>walletId</td><td>string</td><td>The user's wallet ID.</td></tr><tr><td>pinVerified</td><td>boolean</td><td>PIN verification result</td></tr></tbody></table>

#### Error Response

<table><thead><tr><th width="198">Name</th><th width="170">Type</th><th>Description</th></tr></thead><tbody><tr><td>statusCode</td><td>Integer</td><td>Http status code value</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp value</td></tr><tr><td>path</td><td>String</td><td>Specifies which path (API) the error response is associated with.</td></tr><tr><td>message</td><td>String</td><td>Describes the error situation.</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>Returned when the entered PIN is incorrect, showing the number of remaining attempts for PIN verification.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wepin.io/en/api/wallet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.