빌링계정 API - 결제 수단 조회 #
1. API Overview #
Purpose #
특정 사용자(userNo)가 등록한 결제 수단의 전체 목록과 상세 상태를 조회하는 API입니다.
주로 '내 결제 수단 관리' 화면이나 결제 단계에서 저장된 카드를 불러올 때 사용됩니다.
마스킹된 카드 번호, 카드사 정보, 결제 수단 차단 여부 등을 제공하여 사용자가 유효한 결제 수단을 식별하고 선택할 수 있도록 지원합니다.
| 항목 | 값 |
|---|---|
| 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": "dba6e05d13b7557e9efa4d414145cbfc"
}
3. Response Specification #
3.1 Response Data Schema #
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 | cardNumber |
🔴 Required 마스킹된 카드번호 (원본 PAN 미포함. 권장: 앞 6/뒤 4만 노출) |
| 0 | cardIssuer |
🔴 Required 카드 발급사 또는 브랜드명 (Visa, Mastercard 등) |
| 0 | isBlocked |
🔴 Required 차단 여부 (true=차단됨) |
| 0 | pinErrorCount |
⚪ Optional PIN 입력 오류 횟수 |
| 0 | isPinRegistered |
⚪ Optional PIN 등록 여부 |
| 0 | pgProvider |
🔴 Required 결제 대행사(PG) 코드 e.g., WORLDPAY, OMISE |
| 0 | pgChannel |
🔴 Required PG 채널 코드 e.g., WP_CARD, OMISE_CARD |
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",
"cardNumber": "************0023",
"cardIssuer": "Visa",
"isBlocked": false,
"pinErrorCount": 0,
"isPinRegistered": true,
"pgProvider": "WORLDPAY",
"pgChannel": "WP_CARD"
}
]
}