# 빌링계정 API - 결제 수단 등록 완료

## 1. API Overview

### Target Coverage

<table>
  <thead>
    <tr>
      <th style="width: 30%;">PG</th>
      <th>결제 수단 (Payment Method)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="center"><b>Omise</b></td>
      <td>
        [badge:Card,indigo-subtle]
      </td>
    </tr>
  </tbody>
</table>

### Purpose

[context]
결제 수단 등록 API 응답의 `nextStep` 필드 값이 `CLIENT_ACTION`이고, `completionMethod` 필드 값이 `API`인 경우 호출하는 API입니다.
현재 시스템에서는 **Omise PG의 카드(CARD) 결제 수단 등록** 시에만 이 API 호출이 필요합니다.
지시된 클라이언트 액션(카드 토큰화)을 수행 완료한 후 그 결과값(token)을 서버에 전달하여 결제 수단을 최종 확정합니다.
[/context]

### Details

[table:key-value]
| 항목            | 값                           |
| :-------------- | :--------------------------- |
| **API Name**    | 결제 수단 등록 완료              |
| **API Path**    | /api/v2/payment-methods/{paymentMethodId}/complete |
| **API ID**      | EBP_API_121                  |
| **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@@

#### Custom Headers

| Field | Details & Description |
| :--- | :--- |
| x-ebp-context | [type:string] [req:Yes] [desc:결제 수단 생성 API(`EBP_API_120`) 응답 데이터의 `paymentHeaderContext` 값을 이 헤더에 포함하여 전달해야 합니다.] |

### 2.2 Path Parameters

| Field | Details & Description |
| :--- | :--- |
| paymentMethodId | [type:string] [req:Yes] [desc:등록을 완료할 결제 수단 ID (Register API 응답값)] |

### 2.3 Request Data Schema

| depth | Field | Details & Description |
| :--- | :--- | :--- |
| 0 | paymentMethod | [type:string] [req:Yes] [desc:결제 수단 코드] [eg:CARD] |
| 0 | paymentInstrumentId | [type:string] [req:Yes] [desc:PG사 SDK를 통해 획득한 일회성 토큰 ID] |
| 0 | paymentInstrumentType | [type:string] [req:Yes] [desc:결제 수단 정보의 유형] [eg:ONE_TIME_TOKEN] |
| 0 | paymentMethodContext | [type:string] [req:Yes] [desc:결제 수단 등록 API 응답에서 받은 암호화된 컨텍스트 데이터] |

### 2.4 Request Examples

[tabs]
[tab:카드 토큰화 완료]
```json
{
  "paymentMethod": "CARD",
  "paymentInstrumentId": "tok_test_5w6v4d1d4c1...",
  "paymentInstrumentType": "ONE_TIME_TOKEN",
  "paymentMethodContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwidG9rZW4iOiJ0b2tf..."
}
```
[/tabs]

## 3. Response Specification

### 3.1 Response Data Schema

#### Response Data Schema

@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:응답 데이터 (비즈니스 결과물)] |
| 0 | paymentMethodId | [type:string] [req:Yes] [desc:결제 수단 고유 식별자] |
| 0 | status | [type:string] [req:Yes] [desc:현재 결제 수단 상태] [eg:ACTIVE] |
| 0 | paymentUrl      | [type:string] [req:Optional] [desc:추가 인증(HPP 등)이 필요한 경우 사용자를 리다이렉트시킬 EBP 표준 URL입니다.] |
| 0 | pgResponse      | [type:object] [req:Optional] [desc:PG사 응답 상세 정보 객체] |
| 1 | resultCode      | [type:string] [req:Optional] [desc:PG사 자체 응답 코드] |
| 1 | pgProvider      | [type:string] [req:Optional] [desc:PG사 식별자] [eg:OMISE] |
| 1 | data            | [type:object] [req:Optional] [desc:PG사 응답 데이터 상세. 상세 내용은 하단의 <a href="#3-2-pg-pgresponse"><b>PG별 상세 응답 안내</b></a>를 참조하십시오.] |
| -1 | instructions | [type:object] [req:Yes] [desc:후속 처리를 위한 지침 (프로세스 제어)] |
| 0 | nextStep | [type:string] [req:Yes] [desc:추가 인증이 필요한 경우의 다음 행동 지시] [eg:NONE] |
| 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:클라이언트 추가 액션(HPP 이동 등)이 필요한지 여부] |
| 0 | clientAction    | [type:object] [req:Optional] [desc:클라이언트의 추가 액션 지시 정보 객체.]        |
| 1 | type            | [type:string] [req:Optional] [desc:클라이언트 액션 유형] [eg:REDIRECT_TO_HPP]    |
| 1 | pgProvider        | [type:string] [req:Optional] [desc:액션을 처리할 PG사]              |
| 0 | requiresFollowUpApi | [type:boolean] [req:Yes] [desc:후속 API 호출이 필수인지 여부] |
| 0 | followUpApi     | [type:object] [req:Optional] [desc:추가 액션 완료 후 호출해야 할 후속 API 정보.] |

> **참고**: 현재 시스템에서는 본 API 호출 후 추가적인 클라이언트 액션이나 후속 API 호출이 필요한 케이스는 존재하지 않습니다. (`instructions.requiresClientAction`, `instructions.requiresFollowUpApi`는 항상 `false`, `instructions.nextStep`은 항상 `NONE`) 다만, 다른 API와의 일관성 및 향후 확장성을 위해 해당 필드들을 포함하고 있습니다.

### 3.2 PG별 상세 응답 (pgResponse) 안내

PG사 및 결제 수단별로 `pgResponse.data` 객체의 구성이 상이합니다.

#### Omise - Card (카드)
| Field      | Details & Description                                              |
|:-----------|:-------------------------------------------------------------------|
| type       | [type:string] [req:Yes] [desc:응답 데이터 유형] [eg:OMISE_CARD_CUSTOMER]  |
| cardId     | [type:string] [req:Yes] [desc:PG사 카드 식별 ID (뒤 5자리 마스킹 처리)]          |
| customerId | [type:string] [req:Yes] [desc:PG사 고객 식별 ID (뒤 5자리 마스킹 처리)]          |
| createdAt  | [type:string] [req:Yes] [desc:데이터 생성 시각] [eg:2026-04-09T14:13:44Z] |

### 3.3 Response Samples

#### Success Case: 카드 등록 즉시 완료 (Active)

```json
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EQ59HTGK7KYSEHV68ZZEY1C0",
  "timestamp": "2026-04-09T14:29:50.381Z",
  "data": {
    "paymentMethodId": "7967a291ff954b23acca7e0caeb648b9",
    "status": "ACTIVE",
    "paymentUrl": null,
    "pgResponse": {
      "resultCode": "OK",
      "pgProvider": "OMISE",
      "data": {
        "type": "OMISE_CARD_CUSTOMER",
        "cardId": "card_test_67as23ugo5x0of*****",
        "customerId": "cust_test_67as22ax1gdv91*****",
        "createdAt": "2026-04-09T14:13:44Z"
      }
    }
  },
  "instructions": {
    "nextStep": "NONE",
    "requiresClientAction": false,
    "requiresFollowUpApi": false
  }
}
```