# 지갑 생성 및 관리

### 등록하기 <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의 개요 페이지](https://docs.wepin.io/restful-api/overview)를 참고하세요.&#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="../login#app-info">앱 정보 확인하기</a> 실행 후 받은 id</td><td>O</td></tr><tr><td>userId</td><td>String</td><td><a href="../login#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="../login#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="../login#login">로그인</a> 과정에서 받은 <code>userInfo</code>의 userId</td><td>O</td></tr><tr><td>walletId</td><td>String</td><td><a href="../login#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="../login#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>