# 빌링계정 API - 결제 사양 조회

## 1. API 개요

### 목적

[context]
가맹점(스토어 ID, 채널코드, 국가코드 등)의 계약 설정을 기반으로 현재 제공 가능한 **결제 수단 목록**과 **지원하는 PG 정보**, 그리고 해당 PG의 **결제 수단별 상세 연동 사양(예: 태국 은행별 할부 개월 수 등)**을 사전에 조회하는 API입니다.<br>
이 API는 결제창 구성 전 가맹점 화면에 어떤 결제수단을 어떻게 노출할지 동적으로 제어하고 필요한 부가 사양 정보를 제공하기 위해 사용됩니다.
[/context]

### 상세 정보

[table:key-value]
| 항목 | 값 |
| :-------------- | :-------------------------- |
| **API Name**    | 결제 사양 조회 |
| **API Path**    | /api/v2/payments/capacity |
| **API ID**      | EBP_API_240 |
| **HTTP Method** | [badge:GET,blue,lg]        |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]

## 2. 요청 규격

### 2.1 요청 헤더

@@include:common-headers-link.md@@

### 2.2 요청 데이터 스키마 (Query Parameter)

| 필드명 | 상세 내용 및 설명 |
| :--- | :--- |
| paymentMethod | [type:string] [req:Optional] [desc:특정 결제 수단 필터링 조회 시 전달 (미지정 시 가맹점에 매핑된 전체 결제수단 반환)] [eg:INSTALLMENT] |

---

## 3. 응답 규격

### 3.1 응답 데이터 스키마

@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:조회 결과 데이터] |
| 0 | paymentMethods | [type:array] [req:Yes] [desc:사용 가능한 결제 수단 목록] |
| 1 | paymentMethod | [type:string] [req:Yes] [desc:EBP 표준 결제 수단 코드] [eg:CARD, INSTALLMENT] |
| 1 | pgProviders | [type:array] [req:Yes] [desc:결제 수단을 지원하는 PG 목록] |
| 2 | pgProvider | [type:string] [req:Yes] [desc:결제 대행사(PG) 고유 코드] [eg:WORLDPAY_AWP, OMISE, CHECKOUTCOM] |
| 2 | displayName | [type:string] [req:Yes] [desc:PG사 화면 표시명] |
| 2 | specifications | [type:object] [req:Yes] [desc:PG사 및 결제 수단별 가변 사양 정보. 상세 구조는 하단의 **PG 부가 정보 사양**을 참조하십시오.] |

### 3.1.1 PG 부가 정보 사양 (specifications)

`specifications` 객체 내부 데이터는 국가, 결제 수단 및 매핑된 PG 특성에 따라 유연한 스키마 구조를 가집니다.

#### 3.1.1.1 태국 할부 결제 (INSTALLMENT - OMISE PG 예시)

태국 할부 결제(INSTALLMENT) 진행 시 최소 한도 정보와 지원 가능한 금융사(은행) 및 할부 개월 수 정보를 상세 반환합니다.

| depth | 필드명 | 상세 내용 및 설명 |
|:------| :--- | :--- |
| 0     | min | [type:number] [req:Yes] [desc:할부 적용을 위한 최소 총 주문 금액 (통화별 최소 단위 기준, 예: 2000.00 THB -> 200000)] |
| 0     | installmentSources | [type:array] [req:Yes] [desc:할부 지원 은행(Source) 및 조건 목록] |
| 1     | installmentSource | [type:string] [req:Yes] [desc:할부 지원 은행 고유 식별 코드] [eg:installment_bay, installment_kbank] |
| 1     | installmentTerm | [type:array] [req:Yes] [desc:지원 가능한 할부 개월 수 배열] [eg:&#91;3, 4, 6, 10&#93;] |
| 1     | currencies | [type:array] [req:Yes] [desc:해당 수단에서 지원 가능한 거래 통화 목록] [eg:&#91;"THB"&#93;] |

---

## 3.2 응답 샘플

#### 성공 응답 예시 (Success Response)

[tabs]
[tab: 신용 카드 (Credit Card)]

```json
{
  "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"
          }
        ]
      }
    ]
  }
}
```

[tab: 할부 및 기타 (Thailand Omise)]

```json
{
  "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
          }
        ]
      }
    ]
  }
}
```

[/tabs]