Gnuboard5/docs/pg-easypay.md

PG별 간편결제 설정과 검증

관리자 쇼핑몰 설정 → 결제설정에서 PG사 간편결제 버튼 사용을 노출함으로 설정한 뒤, 선택한 PG와 계약한 수단만 체크한다. 계약 상태는 PG사에 직접 확인해야 하며 관리자 화면에서 자동 조회하지 않는다.

PG	개별 수단	제한
NHN KCP	PAYCO, 네이버페이, 카카오페이, 애플페이	기존 직접 호출과 네이버페이 카드·머니/포인트 분리 유지
KG이니시스	삼성페이, L.pay, 카카오페이	구 INIpay 삼성페이는 모바일만, PRO는 PC·모바일 지원. 범용 KPAY 버튼 제거
토스페이먼츠 API	토스페이, 네이버페이, 삼성페이, 애플페이, L.pay, 카카오페이, 핀페이, PAYCO, SSG페이	계약된 수단의 자체창 호출
NICEPAY	삼성페이, 네이버페이, 카카오페이, 애플페이, PAYCO, SK페이, SSG페이, L.pay	기존 요청 파라미터 유지. 네이버페이는 E020=CARD 카드 경로

애플페이는 모든 PG에서 iOS 모바일에만 표시한다. 삼성페이는 PC에서 휴대폰 연결이 가능하며 구 INIpay만 모바일 전용이다. 표시 조건은 결제 가능 여부를 보증하지 않으며, 실제 기기·브라우저·MID 계약 상태를 확인해야 한다. NICEPAY 간편결제 및 KCP 네이버페이·카카오페이는 기존 관리자 안내처럼 테스트 결제가 제한된다. 다른 수단도 PG에 테스트 지원 여부를 확인한다.

KCP 네이버페이 병용 우선순위

선택한 PG가 네이버페이를 지원하고 해당 수단을 사용 설정했다면 기본 PG만 제공한다. 기본 PG가 네이버페이를 지원하지 않거나 사용 설정하지 않았다면 병용 설정과 KCP 인증정보를 확인하여 KCP 경로를 제공한다. 중복 버튼뿐 아니라 병용 스크립트·요청 처리에도 동일한 판정을 적용한다.

기본 PG의 네이버페이가 활성화되어 있으면 KCP 머니/포인트 버튼도 숨긴다. 기본 PG마다 카드·머니 지원 범위가 다르므로, 예를 들어 NICEPAY의 카드 경로 대신 KCP 머니/포인트가 필요하다면 NICEPAY 네이버페이를 해제하고 KCP 병용과 포인트 사용을 설정한다. 기존 주문에 저장된 od_pg, 거래번호, 인증정보와 조회·영수증·취소 코드는 유지한다.

설정 저장과 배포

lib/shop.easypay.lib.php의 목록을 관리자와 PC·모바일 주문서가 함께 사용한다. de_easy_pay_services에 PG별 키를 저장한다. 첫 저장 전에는 기존 이니시스 개별 설정과 토스 PAYCO를 승계한다. 저장 후에는 inicis_configured, toss_configured 표식으로 전체 선택 해제도 보존하며, 기존 이니시스 컬럼을 동기화하여 결제 모듈과의 호환을 유지한다.

기존 설치는 새 설정을 저장하기 전에 관리자 환경설정 → DB업그레이드에서 20260909_001_pg_easypay_services를 적용한다. 저장 공간을 varchar(255)에서 varchar(1024)로 확장하며 신규 설치 SQL도 같은 크기를 사용한다. 일반 페이지 접근으로 스키마를 변경하지 않는다.

검증

DB나 외부 PG 연결 없이 실행하는 회귀 테스트:

php tests/pg_easypay.php
node tests/pg_easypay.js

• PG별 버튼과 선택값, 기본 PG 우선과 KCP 병용 전환, 인증정보 누락, 전체 비활성, 기존 설정 승계 및 명시적 선택 해제
• PC·모바일 구분, iOS·Android 애플페이, 구 INIpay 삼성페이 노출
• 토스 9개 provider의 실제 SDK 요청 생성 함수에 SDK 대역을 연결하여 직접 호출과 일반 카드 재선택 검증
• NICEPAY 직접 호출 코드와 일반 카드 재선택 시 직접 호출 옵션·에스크로 복원
• 토스 승인 성공 처리에 카드 없는 전액 머니 결제와 복합결제 응답을 투입하여 총 승인금액, provider, 승인번호, 현금영수증 저장 검증

실제 PG 네트워크 요청과 운영 DB 마이그레이션은 이 테스트에서 실행하지 않는다. 배포 검수 시 계약된 MID에서 각 수단의 성공·실패·사용자 취소·재시도, 주문내역·관리자·영수증 표시, 전액 취소·부분 취소를 확인한다. 머니/포인트 및 카드 복합결제는 실제 총액·현금영수증·부분 취소 가능 여부도 확인한다. 커스텀 스킨이 주문서를 자체 구현했다면 공통 버튼 함수와 결제수단 변경 이벤트를 반영해야 한다.

토스 자체창 요청은 SDK v2 결제창 문서의 method=CARD, card.flowMode=DIRECT, card.easyPay 규격을 사용한다. provider 코드는 토스 ENUM 문서를 따른다. 일반 카드로 변경하면 DEFAULT로 되돌리고 SDK 요청에서 easyPay를 제외한다.

결제 로고 출처

• img/tosspay-logo.svg: 토스페이 공식 연동 가이드에서 제공하는 로고 ZIP의 logo-toss-pay-blue.svg 원본.
• img/pinpay-logo.png: 스마트로페이 간편결제 안내에서 제공하는 핀페이 로고 원본.

로고의 비율과 색상을 유지하고 저장소의 로컬 파일을 사용한다. 무통장입금·가상계좌 등 일반 결제수단은 아이콘 없이 텍스트로 표시한다. 간편결제 로고는 작은 원본을 확대하지 않는다. 원본의 여백과 종횡비를 고려하여 큰 로고만 축소하고, 원본이 작은 L.pay·카카오페이·PAYCO는 원래 크기를 유지한다.