짓미페이 모듈
짓미페이는 Zittme의 결제 게이트웨이 모듈입니다. 커머스 · 예약 등 다른 모듈의 결제를 한곳에서 처리하고 결제 내역 · 취소 · 로그 관리를 제공합니다. 서드파티 모듈도 정해진 규약만 따르면 짓미페이로 결제를 붙일 수 있습니다.
설치
1. 스토어에서 짓미페이 모듈을 설치합니다.
2. 관리자 > 짓미페이에서 설정 · 게이트웨이 · 결제 내역 · 로그 탭을 사용합니다.
설정 탭 전체 항목
| 항목 | 설명 |
|---|---|
| 사용 | 결제 기능 전체 on/off |
| 테스트 모드 | 실제 승인 없이 결제 흐름 점검. 게이트웨이 키도 테스트 키를 쓰세요 |
| 통화 | 기본 KRW |
| 주문번호 접두사 | PG 관리자에서 우리 주문을 알아보기 위한 표시 (영문·숫자 8자 이내) |
| 부분 취소 허용 | 결제 금액 중 일부만 취소 가능 여부. 끄면 전액 취소만 가능합니다 |
| 취소 사유 목록 | 취소 시 고르는 사유. 한 줄에 하나씩 입력합니다 |
| PG 자동취소 기한 (일) | 결제 후 이 기간이 지나면 PG 취소를 시도하지 않고 수동 환불로 넘깁니다. 정산이 끝난 카드 결제는 PG 취소가 막히기 때문입니다. 0이면 제한 없음 |
| 확정 건 강제취소 허용 | 구매확정된 결제도 관리자가 취소할 수 있게 합니다. 끄면 확정 후에는 어떤 경로로도 취소되지 않습니다 |
| 관리자 알림 메일 | 알림 수신 주소 |
| 알림 이벤트 | 결제 완료 시 / 취소 시 각각 발송 여부 |
| 로그 보관 일수 | 결제 로그 보관 기간 (0=무기한) |
| 웹훅 IP 허용 목록 | 게이트웨이 웹훅을 받을 IP를 제한합니다. 비우면 제한 없음 |
| 결제 화면 고지 문구 | 통신판매업 신고번호 등 결제 화면 하단에 표시할 문구 |
| 결제 화면 스킨 | 결제 · 결과 화면 스킨 선택 |
게이트웨이 탭 (결제수단)
사용할 결제수단을 켜고 수단별 정보를 입력합니다.
토스페이먼츠 (카드 등)
| 항목 | 설명 |
|---|---|
| 클라이언트 키 | 토스페이먼츠 개발자센터에서 발급 |
| 시크릿 키 | 위와 동일. 절대 외부에 노출하지 마세요 |
테스트 키 + 테스트 모드로 흐름을 확인한 뒤 라이브 키로 바꾸는 순서를 권장합니다. 키 종류(테스트/라이브)와 모드가 어긋나면 승인에 실패합니다.
KG이니시스
| 항목 | 설명 |
|---|---|
| 상점아이디 (MID) | 이니시스 가맹점관리자에서 발급 |
| Sign Key | 결제창 서명에 사용 |
| INIAPI Key | 취소 · 환불 전용 키. 가맹점관리자에서 별도 발급 |
테스트 모드에서는 공개 테스트 상점(mid INIpayTest)의 키로 계약 전에도 결제창까지 확인할 수 있습니다. 승인 통신이 끊기거나 금액이 어긋나면 자동으로 망취소되어 이중 결제가 방지됩니다.
NHN KCP
| 항목 | 설명 |
|---|---|
| 사이트코드 (site_cd) | KCP에서 발급. 테스트는 T0000 |
| 서비스 인증서 | KCP 관리자 인증센터에서 받은 PEM 파일 내용을 그대로 붙여 넣습니다 |
| 상점 개인키 · 비밀번호 | 취소 · 환불 요청의 전자서명에만 사용됩니다 |
나이스페이
| 항목 | 설명 |
|---|---|
| Client ID | 나이스페이 개발자센터(developers.nicepay.co.kr)에서 발급 |
| Secret Key | 위와 동일 |
개발자센터 가입만으로 샌드박스 키를 받을 수 있어 계약 전에도 결제 · 취소 흐름을 테스트할 수 있습니다. 테스트 모드가 켜져 있으면 샌드박스 서버로 자동 연결됩니다.
포트원 (V2)
| 항목 | 설명 |
|---|---|
| Store ID | 포트원 콘솔(portone.io)에서 발급 |
| 채널 키 | 어느 PG로 결제할지는 포트원 콘솔의 채널 설정에서 정합니다 |
| V2 API Secret | 서버 승인 · 취소에 사용 |
드라이버 하나로 포트원에 연결된 여러 PG를 쓸 수 있습니다. 테스트는 테스트 채널의 키를 넣으면 됩니다.
PayPal (해외 결제)
| 항목 | 설명 |
|---|---|
| Client ID · Secret | 페이팔 개발자 콘솔(developer.paypal.com)의 앱에서 발급. 테스트 모드에서는 샌드박스 앱 키를 사용 |
| 결제 통화 | 페이팔은 KRW를 지원하지 않습니다. 원화 주문을 이 통화로 환산해 결제합니다 (기본 USD) |
환산에는 아래 공용 환율이 사용되며, 환불은 결제 당시 환율로 처리됩니다. 외화 주문(커머스 다통화)은 환산 없이 해당 통화로 직접 결제됩니다.
무통장 입금
| 항목 | 설명 |
|---|---|
| 입금 계좌 | 은행 · 계좌번호 · 예금주를 여러 개 등록. 구매자가 주문 시 계좌를 고릅니다 |
| 입금 기한 (일) | 1~30일. 기한이 지난 미입금 건은 자동 취소 대상이 됩니다 |
입금 확인은 결제 내역에서 관리자가 처리하며, 확인 시 연동 모듈의 주문이 결제완료로 넘어갑니다.
공용 환율
게이트웨이 탭에서 통화별 환율(1 통화당 KRW)을 관리합니다. 짓미페이의 결제 환산과 커머스 모듈의 다통화 가격이 이 값을 함께 참조하는 단일 기준입니다.
| 항목 | 설명 |
|---|---|
| 환율 표 | 통화 코드(USD 등)와 환율을 등록합니다 |
| 수동 고정 | 체크한 통화는 자동 갱신이 덮지 않습니다 |
| 자동 갱신 | 하루 1회 갱신. 출처는 open.er-api.com(키 불필요) 또는 한국수출입은행(API 키 필요) 중 선택 |
자동 갱신이 실패해도 마지막 성공값이 유지되며, 주문에는 결제 시점 환율이 저장되어 이후 환율 변동의 영향을 받지 않습니다.
외화 결제
커머스 등 연동 모듈이 외화 주문을 넘기면 그 통화로 결제합니다. 주문 통화를 지원하지 않는 결제수단은 결제 화면에 나타나지 않습니다 (국내 PG는 KRW 전용, PayPal은 주요 24개 통화 지원). 금액 표기는 통화 기호와 자릿수에 맞게 자동 처리됩니다.
결제 흐름
1. 연동 모듈(커머스 등)의 주문서에서 결제수단을 고르고 결제하기를 누릅니다.
2. 카드: 토스페이먼츠 결제창에서 승인 → 결과 화면. / 무통장: 계좌 안내와 입금 기한이 표시된 결과 화면 → 관리자 입금 확인 시 결제완료.
3. 결제 상태 변경은 연동 모듈에 즉시 반영되고, 게이트웨이 웹훅으로도 이중 확인합니다.
주문번호와 결제번호
구매자에게 번호가 두 개 보이면 혼란스럽기 때문에 다음 원칙으로 표기합니다.
| 번호 | 발급 | 표기 |
|---|---|---|
| 주문번호 | 결제를 요청한 모듈 (커머스 · 예약 등) | 결제 화면 · 결과 화면 · 내역에서 대표로 크게 |
| 결제번호 | 짓미페이 | 보조로 작게. 결제 문의 · 취소 처리의 기준 |
결제 내역과 취소
- 결제 내역: 전체 결제 건을 상태 · 기간 · 결제수단으로 검색하고, 건별로 승인 정보 · 연동 모듈의 주문번호 · 처리 이력을 봅니다.
- 취소: 건에서 전액 또는 부분 취소(허용 시)를 실행합니다. 카드 결제는 게이트웨이로 취소가 전달되고, 무통장은 환불 처리로 기록합니다. 취소 사유는 설정의 사유 목록에서 고릅니다.
- PG 자동취소 기한이 지난 건: PG 취소 대신 수동 환불로 처리하도록 안내됩니다.
- 로그: 게이트웨이 요청/응답과 웹훅 수신이 기록되며 보관 기간이 지나면 정리됩니다. 결제 문제를 조사할 때 봅니다.
서드파티 모듈 연동 (개발자)
다른 모듈에서 짓미페이로 결제를 붙이는 규약은 간단합니다.
1. 결제 생성(createOrder) 호출 시 source_code 파라미터에 자기 모듈의 주문번호를 넘깁니다.
2. 그러면 결제 화면 · 결과 화면 · 관리 내역에서 그 번호가 "주문번호"로 대표 표시되고, 짓미페이 코드는 "결제번호"로 표기됩니다.
3. 결제 완료 · 취소 콜백에서 자기 모듈의 주문 상태를 갱신합니다.
커머스와 예약 모듈이 이 규약의 참조 구현입니다. 모듈 개발 일반 규약은 개발자 가이드의 "모듈 제작" 문서를 함께 보세요.
자주 묻는 질문
- 테스트 결제가 안 돼요: 테스트 모드 여부와 토스페이먼츠 키가 테스트 키인지 확인하세요.
- 무통장 주문이 계속 결제대기예요: 무통장은 관리자가 입금 확인을 눌러야 결제완료가 됩니다. 입금 기한을 설정해 두면 방치된 미입금 건이 자동 정리됩니다.
- 부분 취소 버튼이 안 보여요: 설정에서 부분 취소 허용이 꺼져 있으면 전액 취소만 가능합니다.
- 오래된 카드 결제 취소가 실패해요: PG 정산이 끝난 건은 카드 취소가 막힙니다. PG 자동취소 기한 설정에 따라 수동 환불로 처리하세요.
- 웹훅이 안 들어와요: 웹훅 IP 허용 목록에 게이트웨이 IP가 빠져 있지 않은지 확인하세요. 비우면 제한 없이 받습니다.
- 새 결제수단이 결제 화면에 안 보여요: 게이트웨이 탭에서 해당 수단을 켜고 키까지 입력해야 나타납니다. 키가 비어 있으면 목록에 표시되지 않습니다.
- PayPal이 비활성이에요: Client ID · Secret과 함께 공용 환율에 결제 통화(기본 USD)의 환율이 등록되어 있어야 합니다.
- 결제 화면 스킨을 바꿔도 원래대로 돌아가요: 0.2.0에서 수정되었습니다. 모듈을 업데이트하세요.