# 이니시스(INIpay) + 알림 시스템 설정 가이드

> 망보드(MangBoard) 쇼핑몰에 이니시스 PG 결제를 연동하고,  

> 카카오 알림톡(Popbill) + 텔레그램 관리자 알림을 구축하는 실전 가이드입니다.

---

## 1. PG 설정 개요

### 1.1 이니시스 연동 필수 항목

| 항목 | 발급처 | 용도 |

|------|--------|------|

| MID (가맹점 ID) | 이니시스 가맹계약 시 발급 | 결제 API 식별자 |

| API Key | 이니시스 관리자 | hashData 서명 |

| API IV | 이니시스 관리자 | hashData 서명 |

| 비밀번호 | 이니시스 관리자 | 키파일 복호화 |

| 키파일 | 이니시스 관리자에서 다운로드 | 결제 암복호화 |

### 1.2 TID prefix별 결제수단

```mermaid

flowchart LR

    A["이니시스 결제"] --> B["StdpayCARD신용카드"]

    A --> C["ININPGRPAY네이버페이"]

    A --> D["StdpayVBANK무통장입금"]

    A --> E["StdpayHPP휴대폰"]

    C -.->|"실제 카드결제"| B

    style C fill:#03C75A,color:#fff

```

| TID prefix | 결제수단 | 비고 |

|------------|---------|------|

| `StdpayCARD` | 일반 신용카드 | 가장 일반적 |

| `ININPGRPAY` | 네이버페이 (카드결제) | 네이버페이가 결제 대행 |

| `StdpayVBANK` | 무통장입금 (가상계좌) | 입금 확인 필요 |

| `StdpayHPP` | 휴대폰결제 | - |

### 1.3 테스트 모드

망보드 관리자에서 결제 플랫폼을 테스트 서버로 설정하면 `INIpayTest` MID로 테스트 결제 가능합니다.  

운영 전환 시 실 MID로 자동 변경됩니다.

---

## 2. 알림 시스템 아키텍처

### 2.1 전체 구조

```mermaid

flowchart TB

    subgraph 고객알림["고객 알림"]

        K1["카카오 알림톡(Popbill API)"]

        K2["SMS/LMS(미가입자 대체)"]

    end

    subgraph 관리자알림["관리자 알림"]

        T1["텔레그램 Bot(무료)"]

    end

    subgraph PG["이니시스 PG"]

        P1["결제 API"]

        P2["취소 API/api/v1/refund"]

    end

    subgraph 망보드["망보드 코어"]

        C1["kakao_api.php알림 발송 중앙"]

        C2["mb-commerce.php주문 API"]

        C3["inicis/functions.phpPG 연동"]

    end

    K1 --> C1

    K2 --> C1

    T1 --> C1

    P2 --> C3

    C2 --> C1

    C2 --> C3

    style 고객알림 fill:#FFF3E0

    style 관리자알림 fill:#E8F5E9

    style PG fill:#E3F2FD

```

### 2.2 알림 채널 비교

| 채널 | 대상 | 비용 | 비고 |

|------|------|------|------|

| 카카오 알림톡 (Popbill) | **고객** | ~11원/건 | 미가입자는 SMS 자동 전환 (17~36원) |

| 텔레그램 Bot | **관리자** | 무료 | 설정만 하면 즉시 사용 |

---

## 3. 관리자 결제취소 — 올바른 방법

### 3.1 취소 방법 비교

```mermaid

flowchart TD

    A["관리자가 취소 처리"] --> B{"어떤 버튼 사용?"}

    B -->|"주문 상세[결제 취소] 버튼"| C["✅ 올바른 방법"]

    B -->|"주문 목록드롭박스 [수정]"| D["❌ 잘못된 방법"]

    C --> E["이니시스 API 호출"]

    E --> F["DB 업데이트"]

    F --> G["고객 알림톡 발송"]

    G --> H["관리자 텔레그램 발송"]

    D --> I["DB만 변경"]

    I --> J["이니시스 실제 취소 안 됨"]

    J --> K["알림 발송 안 됨"]

    K --> L["⚠️ 카드사 환불 안 됨"]

    style C fill:#C8E6C9

    style D fill:#FFCDD2

```

> **반드시 주문 상세 페이지의 [결제 취소] 버튼을 사용하세요.**  

> 드롭박스 [수정]은 DB만 변경하고 실제 PG 취소를 수행하지 않습니다.

### 3.2 [결제 취소] 버튼 동작 순서

```mermaid

sequenceDiagram

    participant Admin as 관리자

    participant UI as 주문 상세 페이지

    participant MB as mb-commerce.php

    participant PG as 이니시스 API

    participant DB as 데이터베이스

    participant Notify as 알림 시스템

    Admin->>UI: [결제 취소] 클릭

    UI->>Admin: confirm 확인

    Admin->>MB: sendOrderViewData(modify_pay_cancel)

    MB->>PG: POST /api/v1/refundtype=Refund or PartialRefund

    PG-->>MB: resultCode=00 (성공)

    MB->>DB: pay_state=cancelorder_state=cancelled_payment

    MB->>Notify: do_action(mbw_commerce_modify_pay_cancel)

    Notify->>Notify: 고객 카카오 알림톡

    Notify->>Notify: 관리자 텔레그램

```

### 3.3 [결제 취소] 버튼 표시 조건

관리자가 주문 상세 페이지에서 [결제 취소] 버튼을 보려면 다음 **모든** 조건 충족:

| 조건 | 설명 |

|------|------|

| `pay_state == "complete"` 또는 `order_state == "refund_request"` | 아직 취소되지 않은 주문 |

| 결제수단이 카드/간편결제 | 무통장입금은 DB만 취소 |

| 결제일 30일 이내 | 예약상품은 60일 |

| `pay_tid`와 `order_id` 존재 | PG 거래 ID 필수 |

---

## 4. 전액 취소 vs 부분 환불

### 4.1 API 타입 분기

```mermaid

flowchart TD

    A["관리자 취소 요청"] --> B{"cancel_type == partial_refund?"}

    B -->|"NO"| C["type=Refund 전액 취소"]

    B -->|"YES"| D{"0보다 크고 pay_price보다 작은가?"}

    D -->|"YES"| E["type=PartialRefund 부분 환불"]

    D -->|"NO"| C

    style C fill:#C8E6C9

    style E fill:#FFF9C4

```

| 조건 | API type | 설명 |

|------|----------|------|

| `amt >= pay_price` | `Refund` | 전액 취소 |

| `cancel_type != partial_refund` | `Refund` | 전액 취소 |

| `cancel_type == partial_refund` AND `0 < amt < pay_price` | `PartialRefund` | 부분 환불 |

> **주의**: API 키가 설정되어 있으면 항상 부분환불 블록이 표시될 수 있습니다.  

> `amt == pay_price`일 때 `Refund`를 사용하도록 명시적으로 분기해야 합니다.

### 4.2 이니시스 API 호출 형식

**전액 취소 (Refund)**:

```

POST https://iniapi.inicis.com/api/v1/refund

Content-Type: application/x-www-form-urlencoded

type=Refund

paymethod=Card

timestamp=YYYYMMDDHHmmss (UTC)

clientIp=서버_IP

mid=가맹점ID

tid=결제TID

msg=취소사유

price=결제금액 (전액)

confirmPrice=0

hashData=sha512(apiKey + type + paymethod + timestamp + clientIp + mid + tid)

```

**부분 환불 (PartialRefund)**:

```

POST https://iniapi.inicis.com/api/v1/refund

type=PartialRefund

paymethod=Card

timestamp=YYYYMMDDHHmmss (UTC)

clientIp=서버_IP

mid=가맹점ID

tid=결제TID

msg=취소사유

price=환불금액

confirmPrice=남은금액 (결제금액 - 환불금액)

hashData=sha512(apiKey + type + paymethod + timestamp + clientIp + mid + tid + price + confirmPrice)

```

> hashData에 포함되는 파라미터 순서가 두 타입에서 다릅니다.  

> `Refund`는 `tid`까지, `PartialRefund`는 `confirmPrice`까지 포함.

### 4.3 응답 코드

| resultCode | 의미 | 조치 |

|-----------|------|------|

| `00` | 정상 처리 | 완료 |

| `01` | 실패 | 사유 확인 후 재시도 |

| `01` + `500626` | 기 취소 거래 | 이미 취소됨, 이니시스 관리자에서 원복 필요 |

---

## 5. 고객 환불/취소 플로우

### 5.1 고객이 볼 수 있는 버튼

```mermaid

flowchart TD

    A["고객 주문"] --> B{"결제수단?"}

    B -->|"무통장입금"| C["배송전[주문취소]"]

    B -->|"카드/PG"| D["배송전[환불신청]"]

    D --> E["관리자가[결제 취소] 처리"]

    F["7일 초과"] --> G["버튼 없음관리자 문의"]

    H["환불신청 상태"] --> I["[환불취소]"]

    J["반품/교환 신청"] --> K["[반품/교환 취소]"]

    style C fill:#FFF3E0

    style D fill:#FFF3E0

    style G fill:#FFCDD2

```

| 주문 상태 | 결제수단 | 고객 버튼 | 동작 |

|-----------|---------|----------|------|

| 주문완료 (무통장) | 무통장 | [주문취소] | DB 즉시 취소 (PG 호출 불필요) |

| 결제완료 (배송전) | 카드/PG | [환불신청] | DB를 `refund_request`로 변경 |

| 결제완료 (7일 초과) | 카드/PG | 버튼 없음 | 관리자에게 문의 |

| 환불신청 상태 | - | [환불취소] | `completed_payment`로 원복 |

| 반품/교환 신청 | - | [반품/교환 취소] | `completed_shipping`로 원복 |

### 5.2 중요: 환불요청 ≠ 자동 취소

고객의 [환불신청]은 **DB 상태만 변경**합니다. 실제 이니시스 결제 취소는 **관리자가 [결제 취소] 버튼으로 처리**해야 합니다.

```mermaid

flowchart LR

    A["고객 [환불신청]"] -->|"DB만 변경refund_request"| B["관리자 확인"]

    B --> C["관리자 [결제 취소]"]

    C -->|"이니시스 API 호출"| D["카드사 환불"]

    C --> E["고객 알림톡 발송"]

    C --> F["관리자 텔레그램 발송"]

```

---

## 6. 알림 발송 매핑

### 6.1 상황별 알림

| 상황 | 고객 카카오 | 관리자 텔레그램 | 비고 |

|------|-----------|---------------|------|

| 주문 접수 (PG/무통장) | ✅ 주문완료 | ✅ 주문완료 | 양쪽 모두 |

| 고객 환불요청 | ❌ 없음 | ✅ 전용 메시지 | 관리자에게만 |

| 관리자 결제취소 | ✅ 주문취소 | ✅ 주문취소 | 양쪽 모두 |

| 고객 주문취소 (무통장) | ✅ 주문취소 | ✅ 주문취소 | 양쪽 모두 |

| 고객 반품/교환 신청 | ✅ 주문취소 | ✅ 주문취소 | 양쪽 모두 |

### 6.2 알림 발송 흐름

```mermaid

flowchart TD

    A["주문 상태 변경"] --> B{"어떤 상태?"}

    B -->|"주문접수"| C["고객: 주문완료 템플릿"]

    C --> D["관리자: 주문완료 템플릿"]

    B -->|"환불요청refund_request"| E["관리자만: 전용 메시지"]

    E -.->|"고객에게는 없음"| F

    B -->|"결제취소"| F["고객: 취소 템플릿"]

    F --> G["관리자: 취소 템플릿"]

    B -->|"고객 취소/반품"| F

    style E fill:#FFF9C4

```

> `refund_request` 상태에서는 고객에게 알림을 보내지 않습니다.  

> "취소 완료" 알림은 관리자가 실제 PG 취소를 완료한 후에 발송됩니다.

---

## 7. 매입전취소 vs 매입후취소

### 7.1 타이밍에 따른 차이

```mermaid

timeline

    title 취소 타이밍에 따른 차이

    매입전취소 : 결제 당일 23시 30분 이전

               : 즉시 카드사 환불

    매입후취소 : 결제 익일 이후

               : 3~5 영업일 카드사 환불

```

| 구분 | 타이밍 | 환불 소요 |

|------|--------|----------|

| 매입전취소 | 결제 당일 23:30 이전 | **즉시** 카드 청구 취소 |

| 매입후취소 | 결제 익일 이후 | **3~5 영업일** 카드사 환불 |

> 네이버페이(`ININPGRPAY`)는 이니시스에서 실시간 매입 처리하므로,  

> 즉시 취소해도 매입후취소가 될 수 있습니다.

---

## 8. Popbill 알림톡 설정

### 8.1 필요 정보

| 항목 | 설명 |

|------|------|

| Popbill 회원가입 | https://www.popbill.com |

| 사업자등록번호 | 카카오톡 발신자 번호 인증에 사용 |

| 발신번호 | 사전 등록된 전화번호 |

| 카카오톡 발신자 번호 | 10~11자리 숫자 (하이픈 제거) |

### 8.2 템플릿

알림톡을 보내려면 카카오톡에 템플릿을 사전 등록해야 합니다.  

등록 시 발급받은 템플릿 코드를 망보드 관리자에 입력합니다.

| 템플릿 | 용도 | 대상 |

|--------|------|------|

| 주문완료 안내 | 주문 접수 시 | 고객 + 관리자 |

| 입금확인 안내 | 무통장 입금 시 | 고객 |

| 배송안내 | 배송 시작 시 | 고객 |

| 주문취소 안내 | 결제 취소 완료 시 | 고객 + 관리자 |

### 8.3 템플릿 변수

| 변수 | 의미 | 사용 템플릿 |

|------|------|-----------|

| `#{NAME}` | 고객명 | 전체 |

| `#{ORDER_NUM}` | 주문번호 | 전체 |

| `#{ORDER_DATE}` | 주문일자 | 전체 |

| `#{ORDER_PRICE}` | 주문금액 | 주문완료 |

| `#{CANCEL_PRICE}` | 취소금액 | 주문취소 |

| `#{PRODUCT_LIST}` | 주문상품 목록 | 전체 |

| `#{BANK_ACCOUNT}` | 입금계좌 | 주문완료 (무통장) |

| `#{DEPOSIT_DEADLINE}` | 입금기한 | 주문완료 (무통장) |

---

## 9. 텔레그램 관리자 알림

### 9.1 설정

| 항목 | 설명 |

|------|------|

| Bot 생성 | Telegram에서 @BotFather와 대화 → `/newbot` |

| Bot Token | BotFather가 발급 |

| Chat ID | 관리자 텔레그램에서 @userinfobot에게 메시지 전송 |

### 9.2 관리자 텔레그램 전송 원리

```mermaid

flowchart LR

    A["주문 상태 변경"] --> B["kakao_api.php"]

    B --> C{"고객 vs 관리자?"}

    C -->|"고객"| D["Popbill API카카오 알림톡"]

    C -->|"관리자"| E["wmbt_send_telegram()텔레그램 Bot API"]

    D --> F["비용 발생~11원/건"]

    E --> G["무료"]

```

### 9.3 두 가지 전송 방식

**템플릿 기반 전송** (주문접수, 결제취소 등):

```

mbw_send_admin_telegram(템플릿코드, 데이터배열)

→ 템플릿 렌더링 → HTML 태그 제거 → 텔레그램 전송

```

**직접 텍스트 전송** (환불요청 등 템플릿 없는 알림):

```

wmbt_send_telegram(문자열)

→ 텔레그램으로 직접 전송

```

---

## 10. 망보드 수정 파일 개요

### 10.1 핵심 파일

```mermaid

flowchart TD

    subgraph 주문API["mb-commerce.php"]

        A["modify_pay_cancel관리자 결제취소"]

        B["modify_order_state고객 상태변경"]

        C["multi_modify_order배치 상태변경"]

    end

    subgraph 알림["kakao_api.php"]

        D["mbw_send_admin_telegram관리자 텔레그램"]

        E["mbw_send_pay_cancel_message결제취소 알림"]

        F["mbw_send_order_state_message상태변경 알림"]

    end

    subgraph PG["inicis/functions.php"]

        G["mbw_commerce_pay_cancel_apiREST API 취소"]

        H["mbw_commerce_pay_partial_refund부분환불"]

    end

    subgraph UI["tpl.commerce.php"]

        I["관리자 [결제 취소] 버튼"]

        J["고객 [환불신청] 버튼"]

    end

    A --> G

    A --> E

    B --> F

    I --> A

    J --> B

    style 주문API fill:#E3F2FD

    style 알림 fill:#E8F5E9

    style PG fill:#FFF3E0

    style UI fill:#F3E5F5

```

### 10.2 망보드 업데이트 주의

> 망보드 플러그인 업데이트 시 위 파일들이 덮어씌워질 수 있습니다.  

> 업데이트 전 **반드시 백업**하고, 업데이트 후 diff를 확인하여 수정 사항을 재적용하세요.

---

## 11. 체크리스트

### 초기 설정

- [ ] 이니시스 가맹계약 완료 → MID, API Key, API IV, 비밀번호 발급

- [ ] 키파일 다운로드 → 서버에 배치

- [ ] 망보드 관리자에 PG 설정값 입력

- [ ] 테스트 모드로 결제/취소 정상 동작 확인

- [ ] 운영 모드 전환

### 알림 설정

- [ ] Popbill 가입 + 카카오톡 발신자 번호 등록

- [ ] 알림톡 템플릿 4종 승인 (주문완료, 입금확인, 배송안내, 주문취소)

- [ ] 망보드 관리자에 템플릿 코드 입력

- [ ] Telegram Bot 생성 → Token, Chat ID 발급

- [ ] 망보드 관리자에 Bot Token, Chat ID 입력

- [ ] 테스트 주문으로 알림 정상 수신 확인

### 관리자 운영

- [ ] 결제취소는 **반드시 주문 상세 [결제 취소] 버튼** 사용

- [ ] 드롭박스 [수정]은 DB만 변경한다는 점 숙지

- [ ] 매입전취소는 결제일 23:30 이전에 처리하면 즉시 환불

- [ ] 망보드 업데이트 전 백업 필수

---

## 12. 운영 시 자주 발생하는 실수

### 1. 드롭박스로 취소한 경우

```mermaid

flowchart TD

    A["드롭박스 [수정]상태를 취소로 변경"] --> B{"이니시스 실제 취소?"}

    B -->|"안 됨"| C["이니시스 관리자에서 수동 취소"]

    B -->|"이미 됨"| D["DB refund_price 확인 후이니시스에서 원복"]

    style A fill:#FFCDD2

```

**복구 절차**:

1. 이니시스 관리자에서 실제 취소 여부 확인

2. 취소 안 된 경우: 이니시스 관리자에서 직접 취소 또는 API 수동 호출

3. 취소된 경우: 이니시스 관리자에서 원복 처리

### 2. PartialRefund 전액 취소 불가

API 키가 설정되면 부분환불 UI가 항상 표시될 수 있으며, `amt == pay_price`일 때도 `PartialRefund`로 요청되면 실패합니다.  

`amt == pay_price` 조건을 명시적으로 체크하여 `Refund` 타입을 사용하도록 분기해야 합니다.

### 3. 알림톡 비용 누적

| 채널 | 비용/건 |

|------|--------|

| 카카오톡 알림톡 | ~11원 |

| SMS (미가입자 대체) | ~17원 |

| LMS (미가입자 대체) | ~36원 |

| 텔레그램 | **무료** |

> 관리자 알림을 카카오채널에서 텔레그램으로 전환하면 비용을 크게 절감할 수 있습니다.

---

## 13. 참고 링크

| 자료 | URL |

|------|-----|

| 이니시스 관리자 | https://iniweb.inicis.com |

| Popbill 관리 | https://www.popbill.com/ |

| 망보드 알림톡 가이드 | https://www.mangboard.com/tip/?vid=46 |