# 지갑 생성 및 관리

### 등록하기 <a href="#register" id="register"></a>

사용자 로그인 결과 `loginStatus`가 `pinRequired`이거나 `registerRequired`인 경우에는 등록하기 절차를 수행해야 합니다.

<table><thead><tr><th width="212">loginStatus</th><th>Description</th></tr></thead><tbody><tr><td><code>pinRequired</code></td><td>사용자의 지갑을 생성하고 앱 등록을 수행합니다.<br>최초 지갑 생성을 위한 사용자 PIN 입력을 받아야 합니다.<br>사용자로부터 2번 입력 받아 확인 할 것을 권장합니다.</td></tr><tr><td><code>registerRequired</code></td><td>사용자 지갑에 앱 등록을 수행합니다.<br>이미 생성된 지갑의 계정을 앱에 등록하는 것이기 때문에 기존 PIN확인을 위해 한번의 PIN 입력을 받습니다.</td></tr></tbody></table>

{% hint style="info" %}
위핀은 사용자의 PIN을 입력 받을 수 있는 UI Library를 제공하고 있습니다. 이를 이용하여 사용자로부터 PIN을 입력 받고, 그 결과를 받아 이후 등록 절차를 수행합니다. 플랫폼에 따른 핀 패드 라이브러리 목록은 [API의 개요 페이지](/restful-api/overview.md)를 참고하세요.&#x20;
{% 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>앱 ID : <a href="/pages/OuSeFTVsA0hkjyoAOvnH#app-info">앱 정보 확인하기</a> 실행 후 받은 id</td><td>O</td></tr><tr><td>userId</td><td>String</td><td><a href="/pages/OuSeFTVsA0hkjyoAOvnH#login">로그인</a> 과정에서 받은 <code>userInfo</code>의 userId</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td>사용자 지갑 ID.<br><code>loginStatus</code>가 <code>registerRequired</code> 일 때, walletId 필요합니다.</td><td>X</td></tr><tr><td>loginStatus</td><td>String</td><td><a href="/pages/OuSeFTVsA0hkjyoAOvnH#login">로그인</a> 결과 받은 <code>loginStatus</code> 값</td><td>O</td></tr><tr><td>UVD</td><td>Object</td><td>User Verification Data.<br>사용자가 입력한 PIN 값을 암호화한 값입니다. PIN Pad Library를 통해서 얻습니다.</td><td>X</td></tr><tr><td>hint</td><td>Object</td><td>사용자가 입력한 PIN 값에 대한 Hint. <br>PIN Pad Library를 통해서 얻습니다. <code>loginStatus</code> 가 <code>pinRequired</code> 인 경우에만 유효합니다.<br>Hint는 서버로 전달되어 사용자 e-mail로 전송 됩니다.</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>성공 여부</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 값</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp 값</td></tr><tr><td>path</td><td>String</td><td>어느 path(API)의 error response 인지를 나타냄.</td></tr><tr><td>message</td><td>String</td><td>Error 상황에 대한 message</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>사용자가 입력한 PIN이 틀린 경우 반환 되는 값으로, 남아있는 PIN 인증 시도 횟수.</td></tr></tbody></table>

response에 `RemainPinTryCnt`가 있는 경우는 PIN 값이 틀린 경우 입니다. 이 경우 Client에서 이에 맞는 UI/UX를 사용자에게 제공해야 합니다.

***

### 사용자 지갑 PIN 변경하기 <a href="#changing-user-wallet-pin" id="changing-user-wallet-pin"></a>

사용자는 본인의 지갑의 PIN 번호를 변경할 수 있습니다. newUVD에 들어가는 nonce 값은 UVD의 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>사용자가 입력한 PIN 값을 암호화한 값입니다. PIN Pad Library를 통해서 얻습니다.</td><td>O</td></tr><tr><td>newUVD</td><td>Object</td><td>User Verification Data. <br>사용자가 입력한 새로운 PIN 값을 암호화한 값입니다. PIN Pad Library를 통해서 얻습니다.</td><td>O</td></tr><tr><td>hint</td><td>Object</td><td>사용자가 입력한 PIN 값에 대한 Hint. <br>PIN Pad Library를 통해서 얻습니다. Hint는 서버로 전달되어 사용자 e-mail 로 전송 됩니다.</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>성공 여부</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 값</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp 값</td></tr><tr><td>path</td><td>String</td><td>어느 path(API)의 error response 인지를 나타냄.</td></tr><tr><td>message</td><td>String</td><td>Error 상황에 대한 message</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>사용자가 입력한 PIN이 틀린 경우 반환 되는 값으로, 남아있는 PIN 인증 시도 횟수.</td></tr></tbody></table>

### 사용자 지갑의 PIN Try Count 리셋 <a href="#reset-pin-try-count-for-user-wallet" id="reset-pin-try-count-for-user-wallet"></a>

사용자 지갑의 PIN try count값 초기화를 요청합니다.

```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><a href="/pages/OuSeFTVsA0hkjyoAOvnH#login">로그인</a> 과정에서 받은 <code>userInfo</code>의 userId</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td><a href="/pages/OuSeFTVsA0hkjyoAOvnH#login">로그인</a> 결과 받은 사용자 지갑 ID</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>성공 여부</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 값</td></tr><tr><td>walletId</td><td>String</td><td>사용자 지갑 ID</td></tr><tr><td>maxTryCount</td><td>String</td><td>해당 지갑의 Max PIN Try Count</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>사용자가 입력한 PIN이 틀린 경우 반환 되는 값으로, 남아있는 PIN 인증 시도 횟수.</td></tr><tr><td>recvResetCmd</td><td>Boolean</td><td><code>/v1/wallet/{walletId}/pin/reset-try-count</code> 수행 여부</td></tr><tr><td>lockTime</td><td>String</td><td>PIN Try Count 초기화되기까지 필요한 시간(분 단위)</td></tr><tr><td>releaseTimestamp</td><td>String</td><td>지갑 사용자의 PIN Try Count값이 초기화되는 시간</td></tr></tbody></table>

### 사용자 지갑의 PIN 검증 <a href="#verification-of-user-wallet-pin" id="verification-of-user-wallet-pin"></a>

사용자 지갑의 PIN 번호를 검증합니다.

{% hint style="info" %}
[사용자 지갑의 PIN Try Count 리셋](#pin-try-count) 후, PIN 검증 과정을 필수적으로 수행해야 합니다.
{% endhint %}

```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><a href="/pages/OuSeFTVsA0hkjyoAOvnH#login">로그인</a> 과정에서 받은 <code>userInfo</code>의 userId</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td>사용자 지갑 ID</td><td>O</td></tr><tr><td>UVD</td><td>UVD</td><td>사용자의 UVD<br>PIN Pad Library - generateAuthPINBlock 의 response 값 사용</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>요청 실패 여부 (“success” 또는 “fail”)</td></tr><tr><td>walletId</td><td>string</td><td>사용자 지갑 ID</td></tr><tr><td>pinVerified</td><td>boolean</td><td>PIN 검증 결과</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 값</td></tr><tr><td>timestamp</td><td>Timestamp</td><td>Time stamp 값</td></tr><tr><td>path</td><td>String</td><td>어느 path(API)의 error response 인지를 나타냄.</td></tr><tr><td>message</td><td>String</td><td>Error 상황에 대한 message</td></tr><tr><td>remainPinTryCnt</td><td>Integer</td><td>사용자가 입력한 PIN이 틀린 경우 반환 되는 값으로, 남아있는 PIN 인증 시도 횟수.</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/restful-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.