# Billing Account API - Verify Payment PIN

## 1. API Overview

### Purpose

[context]
This API verifies the authentication PIN used for card-based payments.<br>It checks whether the user-provided PIN matches the previously registered authentication data to enhance the security of transactions.<br>The API operates without handling sensitive card information directly and leverages registered payment method data and authentication factors to ensure a secure payment process.
[/context]

### Details

[table:key-value]
| Item            | Value                            |
| :-------------- | :------------------------------- |
| **API Name**    | Verify Payment PIN                 |
| **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:Internal user number for tracking purposes] |
| paymentMethodId | [type:string] [req:Yes] [desc:Unique identifier for the payment method]   |
| paymentPin      | [type:string] [req:Yes] [desc:PIN to register for payment method]         |

### 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_en.md@@
| -1    | data            | [type:object] [req:Yes] [desc:Response data]                          |
| 0     | requestId       | [type:string] [req:Yes] [desc:RequestId issued after successful authentication. Use as authRequestId in the payment request.] |
| 0     | signature       | [type:string] [req:Yes] [desc:Signed value of the authentication RequestId (valid for 5 minutes). Use as authSignature in the payment request.] |
| 0     | pinErrorCount   | [type:number] [req:Yes] [desc:Number of incorrect PIN attempts]       |
| 0     | pinErrorLimit   | [type:number] [req:Yes] [desc:Maximum allowed incorrect PIN attempts] |

### 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
  }
}
```