빌링계정 API - 결제 수단 조회 (v0.2) #
1. API Overview #
Purpose #
특정 사용자(userNo)가 등록한 결제 수단의 전체 목록과 상세 상태를 조회하는 API입니다.
v0.2 규격에서는 수단의 성격(paymentMethodType)에 따라 분기된 상세 정보(details)와 등록 시 기록된 부가 정보(metadata)를 함께 제공합니다.
| 항목 | 값 |
|---|---|
| API Name | 결제 수단 조회 |
| API Path | /api/v2/payment-methods/query |
| API ID | EBP_API_109 |
| HTTP Method | POST |
| Region | Global |
2. Request Specification #
2.1 Request Header #
상세한 헤더 정보는 Common Headers 문서를 참고하세요.
2.2 Request Data Schema #
| Field | Details & Description |
|---|---|
| userNo |
🔴 Required 사용자 고유 식별 번호 |
2.3 Request Examples #
JSON Example #
{
"userNo": "AU1741850000100"
}
3. Response Specification #
3.1 Response Data Schema #
| depth | Field | Details & Description |
|---|---|---|
| -1 | resultCode |
🔴 Required 결과 코드 (성공 "0", 에러 시 "EBP-A-0001" 등) |
| -1 | message |
🔴 Required 결과 메시지 (성공 또는 에러 상세) |
| -1 | requestId |
🔴 Required 추적을 위한 고유 요청 ID |
| -1 | timestamp |
🔴 Required ISO 8601 형식의 응답 타임스탬프 e.g., 2025-12-19T14:24:00+09:00 |
| -1 | data |
🔴 Required 결제 수단 목록 데이터 |
| 0 | userNo |
🔴 Required 사용자 고유 식별 번호 |
| 0 | billingAccountNo |
🔴 Required 빌링 계정 번호 |
| 0 | paymentMethod |
🔴 Required 결제 수단 브랜드 코드 |
| 0 | paymentMethodId |
🔴 Required 결제 수단 식별자 |
| 0 | paymentMethodType |
🔴 Required 수단 성격 분류. |
| 0 | pgProvider |
🔴 Required 결제 대행사(PG) 코드 |
| 0 | pgChannel |
🔴 Required PG 채널 코드 |
| 0 | status |
🔴 Required 결제 수단 상태 e.g., ACTIVE |
| 0 | isBlocked |
🔴 Required 차단 여부 (true=차단됨) |
| 0 | pinErrorCount |
⚪ Optional PIN 입력 오류 횟수 |
| 0 | isPinRegistered |
⚪ Optional PIN 등록 여부 |
| 0 | details |
🔴 Required 수단별 상세 정보. 결제 수단에 따라 가변적입니다. |
| 0 | metadata |
⚪ Optional 등록 시 전달된 추가 정보 객체. 결제 수단별 상세 정보는 하단의 메타데이터 상세를 참조하십시오. |
| 0 | createdAt |
🔴 Required 등록 일시 (ISO 8601) |
3.1.1 Metadata #
메타데이터는 결제 수단 등록 시점에 클라이언트가 전달한 부가 정보이며, 결제 수단의 특성에 따라 포함되는 필드가 다를 수 있습니다.
3.1.1.1 NAVER_PAY #
| Field | Details & Description |
|---|---|
| mid | 🔴 Required
가맹점 식별 번호 (Merchant ID) |
| productCode | 🔴 Required
등록 시 기준이 되는 상품 코드 |
| productName | 🔴 Required
등록 시 기준이 되는 상품 명칭 |
| amount | 🔴 Required
등록 또는 첫 결제 기준 금액 |
3.2 Response Samples #
Success Response #
{
"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"
}
]
}
{
"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"
}
]
}