# 빌링계정 API - 결제 수단 조회

## 1. API Overview

### Purpose

[context]
특정 사용자(`userNo`)가 등록한 결제 수단의 전체 목록과 상세 상태를 조회하는 API입니다.<br>
주로 '내 결제 수단 관리' 화면이나 결제 단계에서 저장된 카드를 불러올 때 사용됩니다.<br>
마스킹된 카드 번호, 카드사 정보, 결제 수단 차단 여부 등을 제공하여 사용자가 유효한 결제 수단을 식별하고 선택할 수 있도록 지원합니다.
[/context]

[table:key-value]
| 항목            | 값                          |
| :-------------- | :-------------------------- |
| **API Name**    | 결제 수단 조회              |
| **API Path**    | /api/v2/payment-methods/query |
| **API ID**      | EBP_API_109                 |
| **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-size:string,32] [req:Yes] [desc:사용자 고유 식별 번호] |

### 2.3 Request Examples

#### JSON Example

```json
{
  "userNo": "dba6e05d13b7557e9efa4d414145cbfc"
}
```

## 3. Response Specification

### 3.1 Response Data Schema

#### Response Data Schema

@@include:standard-response_ko.md@@
| -1    | data            | [type:array] [req:Yes] [desc:결제 수단 목록]                                               |
| 0     | userNo          | [type:string] [req:Yes] [desc:사용자 고유 식별 번호]                                         |
| 0     | billingAccountNo| [type:string] [req:Yes] [desc:빌링 계정 번호]                                                |
| 0     | paymentMethod   | [type:string] [req:Yes] [desc:결제 수단 코드 [modal:appendix/payment-method-codes#payment-methods]] |
| 0     | paymentMethodId | [type-size:string,16] [req:Yes] [desc: 결제 수단 식별자 (서버 내부/외부 트래킹용)]             |
| 0     | cardNumber      | [type:string] [req:Yes] [desc:마스킹된 카드번호 (원본 PAN 미포함. 권장: 앞 6/뒤 4만 노출)] |
| 0     | cardIssuer      | [type:string] [req:Yes] [desc:카드 발급사 또는 브랜드명 (Visa, Mastercard 등)]             |
| 0     | isBlocked       | [type:boolean] [req:Yes] [desc:차단 여부 (true=차단됨)]                                    |
| 0     | pinErrorCount   | [type-range:number,0,5] [req:Optional] [desc:PIN 입력 오류 횟수]                           |
| 0     | isPinRegistered | [type:boolean] [req:Optional] [desc:PIN 등록 여부]                                         |
| 0     | pgProvider      | [type:string] [req:Yes] [desc:결제 대행사(PG) 코드] [eg:WORLDPAY, OMISE]                   |
| 0     | pgChannel       | [type:string] [req:Yes] [desc:PG 채널 코드] [eg:WP_CARD, OMISE_CARD]                       |

### 3.2 Response Samples

#### Success Response

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "01EFX0CUI7JK0KCSSTFEEDRDVA",
  "timestamp": "2025-12-30T06:21:55.556809100Z",
  "data": [
    {
      "userNo": "AU1741850000100",
      "billingAccountNo": "K202603170624637",
      "paymentMethod": "CARD",
      "paymentMethodId": "b79c2955f3a7462f86885c2d7fae04b5",
      "cardNumber": "************0023",
      "cardIssuer": "Visa",
      "isBlocked": false,
      "pinErrorCount": 0,
      "isPinRegistered": true,
      "pgProvider": "WORLDPAY",
      "pgChannel": "WP_CARD"
    }
  ]
}
```