# 빌링계정 API - 결제 비밀번호 등록

## 1. API Overview

### Purpose

[context]
카드 결제 시 사용되는 인증 비밀번호(PIN)를 등록하는 API입니다.<br>
사용자가 입력한 PIN은 반드시 암호화하여 전달해야 하며, EBP는 암호화 방식에 간섭하지 않습니다.<br>
이 API는 민감한 카드 정보를 직접 처리하지 않고, 저장된 결제 수단 데이터와 PIN을 결합해 보안을 강화하는 것을 목표로 합니다.
[/context]

> **참고**: 결제 비밀번호 변경은 지원하지 않습니다. 비밀번호 분실 시 기존 결제 수단 삭제 후 재등록이 필요합니다.

### Details

[table:key-value]
| 항목 | 값 |
| :-------------- | :--------------------------------- |
| **API Name**    | 결제 비밀번호 등록 |
| **API Path**    | /api/v2/payment-methods/pin/registration |
| **API ID**      | EBP_API_131 |
| **HTTP Method** | [badge:POST,blue,lg]               |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]

## 2. Request Specification

### 2.1 Request Header

@@include:common-headers-link.md@@

### 2.2 Request Data Schema

| Field      | Details & Description                                  |
|------------|--------------------------------------------------------|
| userNo     | [type:string] [req:Yes] [desc:사용자 번호]  |
| paymentMethodId    | [type:string] [req:Yes] [desc:결제 수단을 식별하는 고유 ID]       |
| paymentPin | [type:string] [req:Yes] [desc: 결제용으로 등록할 PIN (암호화 전송)] |

### 2.3 Request Examples

#### JSON Example

```json
{
  "userNo": "T0a8w9h7t5h3v5w6w4v6v4d1d4c1",
  "paymentMethodId": "202512110245491",
  "paymentPin": "44a019096dabfb5c660df1252609528795400f653ba"
}
```

## 3. Response Specification

### 3.1 Response Data Schema

#### Response Data Schema

@@include:standard-response.md@@
| -1 | data | [type:object] [desc: null]            |
| 0 | paymentMethodId | [type-size:string,16] [req:Yes] [desc:결제 수단을 식별하는 고유 ID]                      |

### 3.2 Response Samples

#### Success Response

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EFX0CRR7JK0KCSSTFEEDRDVG",
  "timestamp": "2025-12-30T07:33:13.824093100Z",
  "data": {
    "paymentMethodId": "b79c2955f3a7462f86885c2d7fae04b5"
  }
}
```