KG 이니시스 관련 기록

2026.04.28

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

망보드(MangBoard) 쇼핑몰에 이니시스 PG 결제를 연동하고,
카카오 알림톡(Popbill) + 텔레그램 관리자 알림을 구축하는 실전 가이드입니다.


1. PG 설정 개요

1.1 이니시스 연동 필수 항목

항목 발급처 용도
MID (가맹점 ID) 이니시스 가맹계약 시 발급 결제 API 식별자
API Key 이니시스 관리자 hashData 서명
API IV 이니시스 관리자 hashData 서명
비밀번호 이니시스 관리자 키파일 복호화
키파일 이니시스 관리자에서 다운로드 결제 암복호화

1.2 TID prefix별 결제수단

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 전체 구조

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 취소 방법 비교

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 [결제 취소] 버튼 동작 순서

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_tidorder_id 존재 PG 거래 ID 필수

4. 전액 취소 vs 부분 환불

4.1 API 타입 분기

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에 포함되는 파라미터 순서가 두 타입에서 다릅니다.
Refundtid까지, PartialRefundconfirmPrice까지 포함.

4.3 응답 코드

resultCode 의미 조치
00 정상 처리 완료
01 실패 사유 확인 후 재시도
01 + 500626 기 취소 거래 이미 취소됨, 이니시스 관리자에서 원복 필요

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

5.1 고객이 볼 수 있는 버튼

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 상태만 변경합니다. 실제 이니시스 결제 취소는 관리자가 [결제 취소] 버튼으로 처리해야 합니다.

flowchart LR
    A["고객 [환불신청]"] -->|"DB만 변경refund_request"| B["관리자 확인"]
    B --> C["관리자 [결제 취소]"]
    C -->|"이니시스 API 호출"| D["카드사 환불"]
    C --> E["고객 알림톡 발송"]
    C --> F["관리자 텔레그램 발송"]

6. 알림 발송 매핑

6.1 상황별 알림

상황 고객 카카오 관리자 텔레그램 비고
주문 접수 (PG/무통장) ✅ 주문완료 ✅ 주문완료 양쪽 모두
고객 환불요청 ❌ 없음 ✅ 전용 메시지 관리자에게만
관리자 결제취소 ✅ 주문취소 ✅ 주문취소 양쪽 모두
고객 주문취소 (무통장) ✅ 주문취소 ✅ 주문취소 양쪽 모두
고객 반품/교환 신청 ✅ 주문취소 ✅ 주문취소 양쪽 모두

6.2 알림 발송 흐름

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 타이밍에 따른 차이

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 관리자 텔레그램 전송 원리

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 핵심 파일

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. 드롭박스로 취소한 경우

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
▣ 마크 다운(Markdown) 문서(Mermaid 포함) 지원합니다.
정보 문서
No image
secret 기술노트 wweb 상용화 작업계획서 new
비밀글입니다
lordly20:040
No image
웰컴스 Tools 설명서 시각적 CSS 편집기 — 그라데이션·그림자·폰트 실시간 미리보기
## CSS 코드, 눈으로 확인하면서 작성하고 싶지 않으세요?그라데이션 배경을 만들고 싶은데 CSS 값을 수정하면서 새로고침 반복이 번거롭죠.> 💡 **Well Design(웰 디자인)이 딱이에요.** 시각적으로 CSS를 조절하면서 실시간 미리보기로 확인하고 코드를 바로 복사!👉 [**Well Design 바로 사용하기 →**](https://www.wel..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 이모지 검색기 — 한글·영어로 원하는 이모지 1초 만에 찾고 복사
## 이모지 찾기, 번거롭지 않으세요?SNS에 올릴 이모지를 찾고 싶은데 한글로 검색이 안 되죠.> 💡 **Well Emoji(웰 이모지)가 딱이에요.** 한글·영어로 1,800개 이상 이모지를 1초 만에 찾고 클릭 한 번으로 복사!👉 [**Well Emoji 바로 사용하기 →**](https://www.wellcoms.co.kr/emoji/)![이모지 검..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 무료 달력 생성기 — 2026 공휴일·음력 달력 인쇄용으로 바로 출력
## 예쁜 달력 인쇄하고 싶지 않으세요?공휴일과 음력이 같이 표시된 달력을 찾기 어렵죠.> 💡 **Well Calendar(웰 캘린더)가 딱이에요.** 공휴일, 음력이 자동 표시되는 달력을 원클릭 생성!👉 [**Well Calendar 바로 사용하기 →**](https://www.wellcoms.co.kr/calendar/)![달력 생성기 메인 화면](/w..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 무료 PDF 도구 — 합치기·분할·압축·변환 설치 없이 바로 사용
## PDF 파일 처리, 번거롭지 않으세요?여러 PDF를 합쳐야 하는데 유료 프로그램은 사기 싫고 무료 사이트는 불안하죠.> 💡 **Well PDF(웰 PDF)가 딱이에요.** 설치 없이 브라우저에서 바로 쓰는 무료 PDF 도구. **서버 업로드 없이** 처리됩니다.👉 [**Well PDF 바로 사용하기 →**](https://www.wellcoms.co...
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 숫자야구 온라인 — 무료 야구 게임으로 두뇌 훈련하세요
## 숫자야구 게임 좋아하시나요?친구들이랑 숫자야구 하고 싶은데 시간 맞추기 어렵고 혼자 연습하고 싶은데 상대가 없죠.> 💡 **Well Baseball(웰 베이스볼)이 딱이에요.** 설치 없이 브라우저에서 바로 즐기는 무료 숫자야구 게임!👉 [**Well Baseball 바로 사용하기 →**](https://www.wellcoms.co.kr/basebal..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 무료 스도쿠 온라인 — 초보도 쉽게 푸는 꿀팁과 4단계 난이도
## 스도쿠 좋아하시나요?출퇴근길에 스도쿠 하나 풀고 싶은데 앱 설치하기는 귀찮고 인쇄하기는 번거롭죠.> 💡 **Well Sudoku(웰 스도쿠)가 딱이에요.** 설치 없이 브라우저에서 바로 즐기는 무료 온라인 스도쿠. 초보부터 최고난이도까지 4단계!👉 [**Well Sudoku 바로 사용하기 →**](https://www.wellcoms.co.kr/sud..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 오늘의 운세 & 타로 카드 — 무료로 매일 운세 뽑기
## 오늘 운이 좋을까, 궁금하지 않으세요?아침에 일어나서 오늘 하루 운이 어떨까 궁금하고, 타로 카드 한 장 뽑아보고 싶고, 이번 주 재물운은 어떨지 알고 싶죠.> 💡 **이럴 때 Well Fortune(웰 포춘)이 딱이에요.** 매일 갱신되는 무료 운세, 타로 카드, 띠별·별자리 운세를 설치 없이 바로 확인할 수 있어요.## Well Fortune이 뭐..
웰컴스2026-06-100
No image
웰컴스 Tools 설명서 만세력 사주팔자 — 무료 명리학 사주·대운·궁합·택일 한곳에서 보기
## 내 사주팔자가 궁금하지 않으세요?올해 운이 좋을까? 내 사주팔자는 어떨까? 대운이 언제 들어올까? 궁금한데 점집에 가기는 번거롭고, 유료 사주 사이트는 믿기 어렵죠.> 💡 **이럴 때 Well Saju(웰 사주)가 딱이에요.** 생년월일만 입력하면 명리학 기반 사주팔자, 십성, 오행, 12운성, 대운, 세운, 신살까지 무료로 분석해줍니다. 궁합과 택일..
웰컴스2026-06-101
No image
secret 기술노트 WWeb 캔바 스타일 에디터 개발계획서
비밀글입니다
lordly2026-06-101