# Payment Flow

## 1. 결제 상태 흐름도

```mermaid
stateDiagram-v2
    state "결제요청 (1)" as 1
    state "결제완료 (2)" as 2
    state "결제취소 (3)" as 3
    state "결제실패 (4)" as 4
    state "결제대기 (5)" as 5
    state "결제대기취소 (6)" as 6
    state "부분취소 (7)" as 7
    state "결제등록 (9)" as 9

    [*] --> 1
    1 --> 4
    1 --> 5
    1 --> 2 : 국내 신용카드는 바로 결제 완료됨
    1 --> 9
    1 --> [*]

    5 --> 6
    5 --> 2 : 대기 상태에서 캡처 / 입금
    5 --> [*]

    6 --> [*]

    2 --> 3 : 결제 건 전체 취소
    2 --> 7 : 결제 건 일부 취소
    2 --> [*]

    7 --> 7 : 전체 취소 시까지 계속 취소 가능
    7 --> 3 : 전체 취소 완료 시 결제취소 상태로 전환
    7 --> [*]

    3 --> [*]
    4 --> [*]
    9 --> [*]
```

## 2. 일반 결제 흐름도

### 주요 단계 설명

1.  **결제 의사 생성 (Payment Intent)**: 상점 서버에서 EBP를 통해 PG사의 세션 및 인증 정보를 미리 확보하는 단계입니다.
2.  **사용자 인증 (Authentication)**: EBP 결제 화면으로 Redirect(2-1) 하거나, 상점에서 직접 PG SDK를 구현(2-2)하여 인증을 수행합니다.
3.  **결제 생성 (Payment Creation)**: 인증된 데이터를 바탕으로 실제 결제를 승인하고 생성하는 단계입니다.
    *   **3-1. API 방식**: 상점이 브라우저에서 인증 데이터를 확보한 뒤, EBP의 **결제 생성 API**를 호출하여 즉시 승인을 완료합니다. 이후 상점은 사용자를 Success URL로 리다이렉트합니다.
    *   **3-2. Webhook 방식**: 사용자가 PG 화면(또는 SDK)에서 직접 결제를 승인하고, PG가 이를 확정 처리합니다. 이후 PG는 사용자를 상점의 Success URL로 리다이렉트합니다.
4.  **승인 결과 알림 (Webhook)**: 결제 확정 방식과 관계없이, EBP는 PG로부터 수신한 최종 결과를 처리한 후 상점으로 **승인 완료 Webhook**을 발송합니다. 상점은 이 알림을 수신하여 최종적으로 주문 처리를 마감하고 사용자에게 결제 완료를 안내합니다.

```mermaid
sequenceDiagram
    actor User
    participant Store
    participant EBP as EBP
    participant PG

    rect var(--mermaid-rect-gray)
        autonumber 1
        Note over User, PG: 1. 결제 의사 생성 (Payment Intent)
        User->>Store: 상품 주문 및 결제 버튼 클릭
        Store->>EBP: 결제 의사 생성 요청 (POST /api/v2/payment-intents)
        activate EBP
        EBP->>PG: 결제 준비 및 세션 정보 요청
        PG-->>EBP: 인증 정보 응답 (pgResponse)
        EBP-->>Store: paymentUrl 및 pgResponse 응답
        deactivate EBP
    end

    rect var(--mermaid-rect-blue)
        Note over User, PG: 2. 사용자 인증 (Authentication)
        alt 2-1. EBP 결제 페이지 Redirect
        autonumber 1
            Store-->>User: EBP 결제 페이지(paymentUrl)로 리다이렉트
            User->>EBP: EBP 화면 접속 및 인증 정보 입력
            EBP->>EBP: EBP Iframe
            EBP->>PG: 결제 인증 수행 요청
        else 2-2. 상점 직접 PG SDK 구현
        autonumber 1
            Store->>Store: Store Iframe
            Store->>PG: Store Iframe을 통해 인증 정보 입력 및 인증 수행 요청
        end
    end
    
    rect var(--mermaid-rect-green)
        Note over User, PG: 3. 결제 생성 (Payment Creation)
        alt 3-1. API 방식 (상점이 결제 생성 API 호출)
        autonumber 1
            PG-->>User: 인증 데이터 전달
            User->>Store: 인증 데이터 전달 및 결제 완료 요청
            Store->>EBP: 결제 생성 API 호출 (POST /api/v2/payments)
            EBP->>PG: 최종 승인 요청
            PG-->>EBP: 승인 결과 응답
            EBP-->>EBP: 승인 내역 처리
            EBP-->>Store: 승인 결과 응답
            Store-->>User: Success URL로 리다이렉트
        else 3-2. Webhook 방식 (사용자가 PG를 통해 직접 결제 생성)
        autonumber 1
            PG->>PG: 결제 승인
            PG-->>User: 상점 Success URL로 리다이렉트
        end
    end

    rect var(--mermaid-rect-brown)
        autonumber 1
        Note over User, PG: 4. 승인 결과 알림 (Webhook)
        PG->>EBP: 승인 결과 알림 (Webhook)
        EBP->>EBP: 승인 내역 처리
        EBP->>Store: 승인 결과 알림 (Webhook)
    end
```

---

### 2.3. 매입을 통한 최종 결제 완료

```mermaid
sequenceDiagram
    autonumber 1
    participant Store
    participant EBP
    participant PG

    rect var(--mermaid-rect-green)
        Store->>EBP: 결제 매입 요청 API 호출 (POST /api/v2/payments/capture)
        activate Store
        activate EBP
        EBP->>PG: 매입 요청
        activate PG
        PG-->>EBP: 매입 결과 응답
        deactivate PG
        EBP-->>EBP: 매입 처리
        EBP-->>Store: 매입 결과 응답
        deactivate EBP
        deactivate Store
    end
```

---

## 3. 저장된 결제 수단 결제 흐름도

### 3.1. 결제 수단 등록 흐름

[context]
**결제 수단 등록:** 사용자가 상점에서 결제 수단 등록을 요청하면 EBP를 거쳐 PG 인증 화면이 호출됩니다.
[/context]

```mermaid
sequenceDiagram
    actor User
    participant Store
    participant EBP
    participant PG
    autonumber
 
    rect var(--mermaid-rect-blue)
        Note over User, PG: 1. 결제 수단 등록 준비 및 초기화 (Initialization)
        User->>Store: 결제 수단 등록 요청
        activate Store
        Store->>EBP: 결제 수단 등록 API 호출 (POST /api/v2/payment-methods)
        activate EBP
        EBP->>PG: 결제 준비 및 세션 정보 요청
        PG-->>EBP: 인증 정보 응답 (pgResponse)
        EBP-->>Store: registrationUrl 및 pgResponse 응답
        deactivate EBP
        deactivate Store
    end
 
    rect var(--mermaid-rect-blue)
        Note over User, PG: 2. 사용자 인증 (Authentication)
        alt 2-1. EBP 결제 수단 등록 페이지 Redirect
            Store-->>User: EBP 결제 페이지(registrationUrl)로 리다이렉트
            User->>EBP: EBP 화면 접속 및 인증 정보 입력
            EBP->>PG: 결제 인증 수행 요청
        else 2-2. 상점 직접 PG SDK 구현
            Store->>User: 상점 페이지 내 PG UI 렌더링
            User->>PG: 상점 화면 내 컴포넌트를 통해 인증 정보 입력 및 인증 수행 요청
        end
    end
    
    rect var(--mermaid-rect-green)
        Note over User, PG: 3. 결제 수단 등록 (Payment Method Registration)
        alt 3-1. API 방식 (상점에서 결제 수단 등록 완료 API 호출)
            PG-->>User: 인증 데이터 전달
            User->>Store: 인증 데이터 전달 및 결제 완료 요청
            Store->>EBP: 결제 수단 등록 완료 API 호출 (POST /api/v2/payment-methods/{paymentMethodId}/complete)
            EBP->>PG: 최종 승인 요청
            PG-->>EBP: 승인 결과 응답
            EBP-->>EBP: 승인 내역 처리
            EBP-->>Store: 승인 결과 응답
            Store-->>User: Success URL로 리다이렉트
        else 3-2. Webhook 방식 (사용자가 PG를 통해 직접 결제 수단 생성)
            PG->>PG: 결제 수단 등록 승인
            PG-->>User: 상점 Success URL로 리다이렉트
        end
    end

    rect var(--mermaid-rect-brown)
        Note over User, PG: 4. 결제 수단 등록 결과 알림 (Webhook)
        PG->>EBP: 결제 수단 등록 결과 알림 (Webhook)
        EBP->>EBP: 결제 수단 등록 내역 처리
        EBP->>Store: 결제 수단 등록 결과 알림 (Webhook)
    end

    rect var(--mermaid-rect-pink)
        Note over User, PG: 5. PIN 번호 등록 (Optional: 상점 필요 시)
        User->>Store: PIN 번호 등록 
        Store->>EBP: 암호화하여 PIN 번호 등록 요청
        EBP->>Store: 등록 결과 응답
    end
```

### 3.2. 저장된 결제 수단 결제

#### 3.2.1. Customer-Initiated Payment

```mermaid
sequenceDiagram
    actor User
    participant Store
    participant EBP
    participant PG
    autonumber
 
    rect var(--mermaid-rect-green)
        Note over User, PG: PIN 번호 인증
        User ->> Store: PIN 번호 입력
        activate Store
        Store ->> EBP: PIN 번호 검증 API 호출 (POST /api/v2/payment-methods/pin/verification)
        EBP -->> EBP: PIN 번호 검증
        EBP -->> Store: PIN 번호 검증 결과 응답
    end

    rect var(--mermaid-rect-pink)
        Note over User, PG: 결제 진행
        Store ->> EBP: 결제 의사 생성 API 호출 (POST /api/v2/payment-intents)
        EBP -->> EBP: 결제 정보 저장
        EBP -->> Store: 결제 의사 생성 응답
        Store -->> EBP: 결제 생성 API 호출 (POST /api/v2/payments)
        EBP -->> PG: 결제 승인 요청
        PG -->> EBP: 결제 승인 결과 응답
        EBP -->> Store: 결제 승인 결과 응답
        Store -->> User: 결제 승인 결과 응답
    end
```

#### 3.2.2. Merchant‑Initiated Subscription Payment

```mermaid
sequenceDiagram
    participant Store
    participant EBP
    participant PG
    autonumber
 
    rect var(--mermaid-rect-blue)
        Note over Store, PG: 1. 결제 의사 생성
        activate Store
        Store ->> EBP: 결제 의사 생성 API 호출 (POST /api/v2/payment-intents)
        activate EBP
        EBP->>EBP: 결제 준비 주문 정보 저장
        deactivate EBP
        EBP-->>Store: 결제 의사 생성 결과 응답
        deactivate Store
    end

    rect var(--mermaid-rect-green)
        Note over Store, PG: 2. 결제 생성
        Store->>EBP: 결제 생성 API 호출 (POST /api/v2/payments)
        EBP->>PG: 최종 승인 요청
        PG-->>EBP: 승인 결과 응답
        EBP-->>EBP: 승인 내역 처리
        EBP-->>Store: 승인 결과 응답
    end
```

### 3.3. 저장된 결제 수단 삭제

**저장된 결제 수단 삭제:** 사용자의 요청에 따라 저장된 결제 수단을 삭제합니다.

```mermaid
sequenceDiagram
    autonumber 1
    actor User
    participant Store
    participant EBP
    participant PG

    rect var(--mermaid-rect-blue)
        User->>Store: 저장된 결제 수단 삭제 요청
        activate Store
        Store->>EBP: 저장된 결제 수단 삭제 API 호출 (POST /api/v2/payment-methods/delete)
        activate EBP
        EBP->>PG: 저장된 결제 수단 삭제 요청
        PG-->>PG: 저장된 결제 수단 삭제
        activate PG
        PG-->>EBP: 저장된 결제 수단 삭제 응답
        deactivate PG
        EBP-->>EBP: 저장된 결제 수단 삭제 처리
        EBP-->>Store: 저장된 결제 수단 삭제 결과 응답
        deactivate EBP
        Store-->>User: 저장된 결제 수단 삭제 결과 응답
        deactivate Store
    end
```

### 3.4. 저장된 결제 수단 조회

**결제 수단 조회:** 사용자가 저장한 결제 수단 목록을 조회합니다.

```mermaid
sequenceDiagram
    autonumber 1
    actor User
    participant Store
    participant EBP

    rect var(--mermaid-rect-blue)
        User->>Store: 저장된 결제 수단 조회 요청
        activate Store
        Store->>EBP: 저장된 결제 수단 조회 API 호출 (POST /api/v2/payment-methods/query)
        activate EBP
        EBP->>EBP: 저장된 결제 수단 조회
        EBP-->>Store: 저장된 결제 수단 조회 결과 응답
        deactivate EBP
        Store-->>User: 저장된 결제 수단 조회 결과 응답
        deactivate Store
    end
```