빌링계정 API - 결제 사양 조회 #
1. API 개요 #
목적 #
가맹점(스토어 ID, 채널코드, 국가코드 등)의 계약 설정을 기반으로 현재 제공 가능한 결제 수단 목록과 지원하는 PG 정보, 그리고 해당 PG의 결제 수단별 상세 연동 사양(예: 태국 은행별 할부 개월 수 등)을 사전에 조회하는 API입니다.
이 API는 결제창 구성 전 가맹점 화면에 어떤 결제수단을 어떻게 노출할지 동적으로 제어하고 필요한 부가 사양 정보를 제공하기 위해 사용됩니다.
상세 정보 #
| 항목 | 값 |
|---|---|
| API Name | 결제 사양 조회 |
| API Path | /api/v2/payments/capacity |
| API ID | EBP_API_240 |
| HTTP Method | GET |
| Region | Global |
2. 요청 규격 #
2.1 요청 헤더 #
상세한 헤더 정보는 Common Headers 문서를 참고하세요.
2.2 요청 데이터 스키마 (Query Parameter) #
| 필드명 | 상세 내용 및 설명 |
|---|---|
| paymentMethod |
⚪ Optional 특정 결제 수단 필터링 조회 시 전달 (미지정 시 가맹점에 매핑된 전체 결제수단 반환) e.g., INSTALLMENT |
3. 응답 규격 #
3.1 응답 데이터 스키마 #
| 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 | paymentMethods |
🔴 Required 사용 가능한 결제 수단 목록 |
| 1 | paymentMethod |
🔴 Required EBP 표준 결제 수단 코드 e.g., CARD, INSTALLMENT |
| 1 | pgProviders |
🔴 Required 결제 수단을 지원하는 PG 목록 |
| 2 | pgProvider |
🔴 Required 결제 대행사(PG) 고유 코드 e.g., WORLDPAY_AWP, OMISE, CHECKOUTCOM |
| 2 | displayName |
🔴 Required PG사 화면 표시명 |
| 2 | specifications |
🔴 Required PG사 및 결제 수단별 가변 사양 정보. 상세 구조는 하단의 PG 부가 정보 사양을 참조하십시오. |
3.1.1 PG 부가 정보 사양 (specifications) #
specifications 객체 내부 데이터는 국가, 결제 수단 및 매핑된 PG 특성에 따라 유연한 스키마 구조를 가집니다.
3.1.1.1 태국 할부 결제 (INSTALLMENT - OMISE PG 예시) #
태국 할부 결제(INSTALLMENT) 진행 시 최소 한도 정보와 지원 가능한 금융사(은행) 및 할부 개월 수 정보를 상세 반환합니다.
| depth | 필드명 | 상세 내용 및 설명 |
|---|---|---|
| 0 | min |
🔴 Required 할부 적용을 위한 최소 총 주문 금액 (통화별 최소 단위 기준, 예: 2000.00 THB -> 200000) |
| 0 | installmentSources |
🔴 Required 할부 지원 은행(Source) 및 조건 목록 |
| 1 | installmentSource |
🔴 Required 할부 지원 은행 고유 식별 코드 e.g., installment_bay, installment_kbank |
| 1 | installmentTerm |
🔴 Required 지원 가능한 할부 개월 수 배열 e.g., [3, 4, 6, 10] |
| 1 | currencies |
🔴 Required 해당 수단에서 지원 가능한 거래 통화 목록 e.g., ["THB"] |
3.2 응답 샘플 #
성공 응답 예시 (Success Response) #
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06F4W5V4F1DA47BH58VVMD95VC",
"timestamp": "2026-05-22T05:10:16.445222700Z",
"data": {
"paymentMethods": [
{
"paymentMethod": "OPEN_BANKING",
"pgProviders": [
{
"pgProvider": "WORLDPAY",
"displayName": "Worldpay"
}
]
},
{
"paymentMethod": "GOOGLE_PAY",
"pgProviders": [
{
"pgProvider": "WORLDPAY",
"displayName": "Worldpay"
}
]
},
{
"paymentMethod": "AFTER_PAY",
"pgProviders": [
{
"pgProvider": "WORLDPAY",
"displayName": "Worldpay"
}
]
},
{
"paymentMethod": "CARD",
"pgProviders": [
{
"pgProvider": "WORLDPAY_AWP",
"displayName": "Worldpay Access"
}
]
},
{
"paymentMethod": "APPLE_PAY",
"pgProviders": [
{
"pgProvider": "CHECKOUT_COM",
"displayName": "Checkout.com"
}
]
}
]
}
}
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06F4W0040755WD29TBYFE8VWNR",
"timestamp": "2026-05-22T04:44:45.010Z",
"data": {
"paymentMethods": [
{
"paymentMethod": "INSTALLMENT",
"pgProviders": [
{
"pgProvider": "OMISE",
"displayName": "Omise",
"specifications": {
"min": 200000,
"installmentSources": [
{
"installmentSource": "installment_bay",
"installmentTerm": [3, 4, 6, 9, 10],
"currencies": ["THB"]
}
]
}
}
]
},
{
"paymentMethod": "DIRECT_DEBIT",
"pgProviders": [
{
"pgProvider": "OMISE",
"displayName": "Omise",
"specifications": null
}
]
},
{
"paymentMethod": "CARD",
"pgProviders": [
{
"pgProvider": "OMISE",
"displayName": "Omise",
"specifications": null
}
]
},
{
"paymentMethod": "BANK_TRANSFER",
"pgProviders": [
{
"pgProvider": "OMISE",
"displayName": "Omise",
"specifications": null
}
]
}
]
}
}