https://github.com/gnuboard/g7/issues/125 — 상품 상세설명을 HTML 로 저장할 때 HTMLPurifier 가 모듈 vendor 폴더 안에 정의 캐시를 만들려다 실패해 저장이 매번 500 으로 끝나던 문제를 고친다. vendor 를 읽기 전용으로 두는 표준 배포에서 그 쓰기는 예외가 아니라 PHP 경고로 나오고 Laravel 이 이를 ErrorException 으로 승격시킨다. 캐시는 설정 해시당 1회만 기록되므로 캐시가 영영 생기지 않아 재시도해도 같은 결과였다. 캐시 경로를 storage 아래로 옮기고, 그 경로마저 확보하지 못하면 캐시만 끄고 정화는 그대로 수행한다 — 캐시는 성능 장치이고 정화는 보안 장치라, 전자의 실패가 후자를 건너뛰게 만들면 안 된다. 저장은 성공하므로 운영자에게 도달하는 흔적이 로그 하나뿐이라 error 수준으로 남긴다 (출하 기본 로그 수준이 error 라 warning 은 기본 설치 상태에서 파일에 남지 않는다). 그 과정에서 갈라져 있던 두 축을 코어 한 곳으로 모은다. - 쓰기 디렉토리 확보: 억제 생성·chmod·setgid·소유권 상속·쓰기 판정 절차가 정적 게시와 정의 캐시 두 곳에 서로 다른 하드닝으로 복제돼 있었다(억제 mkdir·setgid·clearstatcache 가 사본마다 한쪽씩 빠져 있었다). FilePermissionHelper 의 ensureWritableDirectory 와 hardenDirectory 로 통합하고, 실패 사유는 out 파라미터로 올려 정책(조용한 성능 저하 대 시끄러운 실패)은 호출부가 정하게 둔다. - 확장 저장 경로: storage_path('app/modules/…') 손조립이 30곳에 흩어져 있어 테스트 격리 분기를 넣으려면 사본마다 복제해야 했고, 한 곳만 빠뜨려도 그 확장의 테스트가 운영 설정 파일을 덮어쓴다. 디스크 root 를 단일 출처로 읽는 ExtensionStoragePath 로 전환하고 테스트 분기는 config/filesystems.php 한 줄에서 끝낸다. 함께 고친 것 - 테스트가 운영 라우트 캐시로 부팅해 확장 allowlist 가 라우트 축에서 통째로 무력화되던 문제. 삭제가 아니라 경로를 돌린다 — 라우트 캐시는 확장 작업 전까지 재생성되지 않아, 삭제하면 운영 사이트가 그때까지 라우트 파일 스캔 경로로 떨어진다. - PHPUnit 프로세스가 확장 vendor 의 제3자 composer 패키지를 오토로드하지 않아 그 패키지를 쓰는 코드 경로가 통째로 테스트 불가였던 문제. 확장 자신의 오토로더를 그대로 쓰면 활성 디렉토리가 _bundled 를 이기고 base path 유추까지 깨지므로, 생성된 맵에서 제3자 항목만 골라 별도 로더로 등록한다. - 게시 폴더가 setgid 를 갖지 않아, 명령줄과 웹이 번갈아 만든 하위 폴더를 다른 쪽이 쓰지 못하던 문제. - 관리자 템플릿이 HTML 정화 라이브러리를 직접 지정하지 않아 전이 의존으로 딸려온 구버전이 쓰이던 문제. 동반 산출물 - 규정 표(·AGENTS.md) 6행 + storage-driver/service-repository/testing-guide 문서 - audit 룰 2종 + coverage 6항목. 저장소가 이미 전량 전환돼 전수 실행이 공허 통과하므로 판정식은 픽스처 36건이 잠근다 - INSTALL.md 에 설치 후 파일 권한 절 추가 (vendor 쓰기 권한 불요를 명시)
NicePayments Plugin for G7
나이스페이먼츠(NicePayments) PG 연동 플러그인입니다. G7 플랫폼의 sirsoft-ecommerce 모듈과 함께 동작합니다.
지원 결제 수단
| 결제 수단 | PayMethod |
|---|---|
| 신용카드 | CARD |
| 가상계좌 | VBANK |
| 계좌이체 | BANK |
| 휴대폰결제 | CELLPHONE |
설치
# 플러그인 디렉토리에 배치 후
composer install
npm install && npm run build
설정
관리자 → 플러그인 → NicePayments 설정에서 구성합니다.
| 항목 | 설명 |
|---|---|
| 테스트 모드 | 활성화 시 나이스페이먼츠 공용 테스트 MID를 사용합니다. 실제 카드 승인/출금 알림이 발생할 수 있으며, 테스트 계정 결제는 당일 23:30경 일괄 자동 취소됩니다. |
| 테스트 MID | 테스트 가맹점 ID (nicepay00m 기본값) |
| 테스트 가맹점 키 | 나이스페이 공용 테스트 키 |
| 라이브 MID | 실서비스 가맹점 ID |
| 라이브 가맹점 키 | 실서비스 가맹점 키 (외부 노출 금지) |
| 결제 성공 URL | 결제 완료 후 리다이렉트 경로 ({orderId} 치환 지원) |
| 결제 실패 URL | 결제 실패 후 리다이렉트 경로 |
테스트 모드 주문은 실제 배송하지 마세요. 실제 카드 승인/출금 알림이 발생할 수 있으며, 테스트 계정 결제는 당일 23:30경 일괄 자동 취소됩니다.
웹훅 (가상계좌 입금 통보)
나이스페이먼츠 관리자에서 가상계좌 입금 통보 URL을 아래로 설정하세요:
https://your-domain.com/plugins/sirsoft-pay_nicepayments/payment/vbank-notify
IP 화이트리스트
나이스페이먼츠 서버 IP만 허용됩니다. 로컬/테스트 환경에서는 자동으로 우회됩니다.
| IP |
|---|
| 121.133.126.10 |
| 121.133.126.11 |
| 211.33.136.39 |
결제 흐름
PC / 모바일 결제 (인증 + 승인 2단계)
브라우저 → goPay(form) / 모바일 결제창 form POST
결제창 → POST /payment/callback → authCallback() (1단계 인증)
서버 → POST NextAppURL → 승인 API 호출 (2단계)
승인 완료 → completePayment() → 성공 페이지 리다이렉트
결제창 취소 / 인증 실패
모바일 결제창에서 사용자가 취소버튼을 누르거나 PG 가 인증을 거부하면 (AuthResultCode != '0000') 결제 승인 (NextAppURL 호출) 이전이므로 사용자에게 generic 오류 메시지를 띄우지 않고 체크아웃으로 silent redirect 합니다. 운영 가시성은 로그(auth_result_code / auth_result_msg) 로 보존됩니다. 2단계 이후 hard failure (signature / mid / amount / authorize) 는 종전대로 ?error= 쿼리 부착하여 안내합니다.
결제 취소 / 부분취소
관리자 주문 취소 요청 (cancel_pg=true)
→ 코어가 sirsoft-ecommerce.payment.refund 필터 훅 발화
→ PaymentRefundListener 가 NicePayments cancelPayment API 호출
· 전액취소: isPartial=0
· 부분취소: isPartial=1
→ 코어가 환불 레코드 생성 + 쿠폰 / 마일리지 / 재고 복원
→ CancelActivityLogListener 가 PG 응답 시각·취소 TID를 활동 로그에 기록
배송비가 포함된 주문은 전체취소 시 배송비도 함께 환불 레코드에 반영되고, 쿠폰이 적용된 주문은 실결제금액(쿠폰 차감 후) 이 PG cancelAmt 로 전달됩니다. 부분취소 시 쿠폰 최소 주문금액 조건을 더 이상 충족하지 못하면 코어가 취소 자체를 거부 (422) 하여 PG 호출이 발생하지 않습니다. 가상계좌 입금 완료 건은 환불 계좌 정보가 필요해 일반 취소 API 가 아닌 별도 어드민 환불 계좌 API 경로로 처리됩니다.
가용 훅 (Hook)
다른 플러그인이나 리스너에서 아래 훅에 연결할 수 있습니다.
액션 훅
| 훅 이름 | 시점 | 인수 |
|---|---|---|
sirsoft-pay_nicepayments.payment.before_authorize |
서버 승인 API 호출 직전 | Order $order, array $pgParams |
sirsoft-pay_nicepayments.payment.after_authorize |
서버 승인 API 응답 직후 | Order $order, array $pgResponse |
sirsoft-pay_nicepayments.payment.before_cancel |
NicePayments 취소 API 호출 직전 | Order $order, OrderPayment $payment, float $refundAmount |
sirsoft-pay_nicepayments.payment.after_cancel |
NicePayments 취소 API 호출 직후 | Order $order, OrderPayment $payment, array $pgResponse |
sirsoft-pay_nicepayments.payment.refund_failed |
환불 API 호출 실패 시 | Order $order, OrderPayment $payment, array $context |
refund_failed context 구조
[
'tid' => string, // 나이스페이 거래번호
'cancel_amt' => int, // 환불 시도 금액 (원)
'error' => string, // 오류 메시지
]
훅 등록 예시
use App\Extension\HookManager;
HookManager::addAction(
'sirsoft-pay_nicepayments.payment.refund_failed',
function (Order $order, OrderPayment $payment, array $context) {
// 예: Slack 알림 발송
SlackNotifier::send("환불 실패: 주문 #{$order->order_number}, 오류: {$context['error']}");
},
priority: 10
);
API 단건 조회
NicePaymentsApiService::queryTransaction(string $tid): array 메서드로 거래 상태를 조회할 수 있습니다.
$apiService = app(\Plugins\Sirsoft\PayNicepayments\Services\NicePaymentsApiService::class);
$result = $apiService->queryTransaction('NICE_TID_12345');
// $result['ResultCode'], $result['Amt'], ...
과세 처리
결제 요청 시 주문의 total_tax_amount, total_vat_amount, total_tax_free_amount 값을 자동으로 나이스페이 폼에 포함합니다. 세 값이 모두 0이면 과세 필드를 생략합니다.
테스트 실행
cd c:/g7
php artisan test --filter=Nicepayments
라이선스
MIT