# 빌링계정 API - 결제 수단 조회 (v0.2)

## 1. API Overview

### Purpose

[context]
특정 사용자(`userNo`)가 등록한 결제 수단의 전체 목록과 상세 상태를 조회하는 API입니다.<br>
v0.2 규격에서는 수단의 성격(`paymentMethodType`)에 따라 분기된 상세 정보(`details`)와 등록 시 기록된 부가 정보(`metadata`)를 함께 제공합니다.
[/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": "AU1741850000100"
}
```

## 3. Response Specification

### 3.1 Response Data Schema

@@include:standard-response.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:결제 수단 브랜드 코드]                                         |
| 0 | paymentMethodId | [type:string] [req:Yes] [desc:결제 수단 식별자]                                             |
| 0 | paymentMethodType | [type:string] [req:Yes] [desc:수단 성격 분류. `INSTRUMENT`(직접), `AGREEMENT`(계약)]         |
| 0 | pgProvider | [type:string] [req:Yes] [desc:결제 대행사(PG) 코드]                                         |
| 0 | pgChannel | [type:string] [req:Yes] [desc:PG 채널 코드]                                                 |
| 0 | status | [type:string] [req:Yes] [desc:결제 수단 상태] [eg:ACTIVE]                                   |
| 0 | isBlocked | [type:boolean] [req:Yes] [desc:차단 여부 (true=차단됨)]                                    |
| 0 | pinErrorCount | [type:number] [req:Optional] [desc:PIN 입력 오류 횟수]                                      |
| 0 | isPinRegistered | [type:boolean] [req:Optional] [desc:PIN 등록 여부]                                         |
| 0 | details | [type:object] [req:Yes] [desc:수단별 상세 정보. 결제 수단에 따라 가변적입니다.]     |
| 0 | metadata | [type:object] [req:Optional] [desc:등록 시 전달된 추가 정보 객체. 결제 수단별 상세 정보는 하단의 **메타데이터 상세**를 참조하십시오.] |
| 0 | createdAt | [type:string] [req:Yes] [desc:등록 일시 (ISO 8601)]                                         |

### 3.1.1 Metadata

메타데이터는 결제 수단 등록 시점에 클라이언트가 전달한 부가 정보이며, 결제 수단의 특성에 따라 포함되는 필드가 다를 수 있습니다.

#### 3.1.1.1 NAVER_PAY

| Field       | Details & Description                                 |
|:------------|:------------------------------------------------------|
| mid         | [req:Yes][type:string] [desc:가맹점 식별 번호 (Merchant ID)] |
| productCode | [req:Yes][type:string] [desc:등록 시 기준이 되는 상품 코드]       |
| productName | [req:Yes][type:string] [desc:등록 시 기준이 되는 상품 명칭]       |
| amount      | [req:Yes][type:number] [desc:등록 또는 첫 결제 기준 금액]        |

### 3.2 Response Samples

#### Success Response

[tabs]
[tab:Worldpay | Card]

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

[tab:NaverPay]

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "01EFX0CUI7JK0KCSSTFEEDRDVA",
  "timestamp": "2025-12-30T06:21:55.556809100Z",
  "data": [
    {
      "userNo": "KR1741850000100",
      "billingAccountNo": "K202603170624637",
      "paymentMethod": "NAVER_PAY",
      "paymentMethodId": "n79c2955f3a7462f86885c2d7fae04b6",
      "paymentMethodType": "AGREEMENT",
      "pgProvider": "NAVER_PAY",
      "pgChannel": "NAVER_PAY_RECURRING",
      "status": "ACTIVE",
      "isBlocked": false,
      "details": {
        "maskedIdentifier": "kr***@example.com",
        "methodName": "네이버페이 머니"
      },
      "metadata": {
        "mid": "NAVER_MID_12345",
        "productCode": "SUBS_PROD_001",
        "productName": "정기 구독 서비스",
        "amount": 0
      },
      "createdAt": "2026-04-27T10:00:00Z"
    }
  ]
}
```

[/tabs]