# 빌링계정 API - 결제 비밀번호 확인

## 1. API Overview

### Purpose

[context]
결제 시 사용되는 결제 수단의 인증 비밀번호(PIN)를 검증하는 API입니다.<br>사용자가 입력한 PIN이 사전에 등록된 인증 정보와 일치하는지 확인하여 등록된 재사용 가능한 결제 수단의 보안을 강화합니다.<br>민감한 정보를 직접 처리하지 않고 저장된 결제 수단 데이터와 인증 요소를 활용해 안전한 결제 환경을 제공합니다.
[/context]

### Details

[table:key-value]
| 항목            | 값                               |
| :-------------- | :------------------------------- |
| **API Name**    | 결제 비밀번호 확인               |
| **API Path**    | /api/v2/payment-methods/pin/verification |
| **API ID**      | EBP_API_126                      |
| **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": "KR1234567890",
  "paymentMethodId": "b79c2955f3a7462f86885c2d7fae04b5",
  "paymentPin": "1234"
}
```

## 3. Response Specification

### 3.1 Response Data Schema

#### Response Data Schema

@@include:standard-response.md@@
| -1    | data            | [type:object] [req:Yes] [desc:응답 데이터]                  |
| 0     | requestId       | [type:string] [req:Yes] [desc:인증 성공 시 발급되는 RequestId. 결제 요청 시 authRequestId로 사용합니다.] |
| 0     | signature       | [type:string] [req:Yes] [desc:인증 요청의 RequestId 서명 값(유효시간 5분). 결제 요청 시 authSignature로 사용합니다.] |
| 0     | pinErrorCount   | [type:number] [req:Yes] [desc:비밀번호(PIN) 입력 오류 횟수]      |
| 0     | pinErrorLimit   | [type:number] [req:Yes] [desc:허용되는 최대 비밀번호(PIN) 오류 횟수] |

### 3.2 Response Samples

#### Success Response

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "1767081244065",
  "timestamp": "2025-12-30T07:54:04.067215800Z",
  "data": {
    "requestId": "20260202070836883_06E1TBMGJCX7KRNQBGEDDRW30R",
    "signature": "LFrk03gQUuxWxS0YM3Hbzu9iP24PTKkkPuCa97MbFf0=",
    "pinErrorCount": 0,
    "pinErrorLimit": 0
  }
}
```