0 Fork 0

Files

T

HeuJung 3ebbda5d86 feat(board,ecommerce,pay,verification,templates,core): 문의 답변 사슬·답글 삭제 정책·검증 계약 + 실패 사유 표면화 전수

공개 (답변 중복 등록)/(문의 삭제 시 답변 잔존) 수정과 동형 결함 전수 해소.

- 문의 답변 단일성: 1차(피벗 is_answered) + 2차(게시판 리스너 duplicate 마커) 이중 방어,
 경합 경로에서도 사유(reply_already_exists 422)가 보존되도록 훅 반환 계약 확장
- 질문·답변·피벗 생명주기 대칭: 삭제/복원/영구삭제 훅 연동 + 고아 데이터 백필 업그레이드 스텝
- 게시판별 답글 삭제 정책(cascade/block) 신설, 정렬 화이트리스트·per_page 게이트
 (전량 조회 소비처 200/999 를 수용하는 상한 999 — 조였다가 관리자 화면 2곳 422 회귀 즉시 정정)
- 결제/본인인증 플러그인 검증 계약: FormRequest 15종 승격 + 컨트롤러 catch 정합.
 거래 조회 tid 상한은 저장 컬럼(varchar 100) 기준 — 해외 CBT TID(40자) 수용
- onError 토스트 고정 문구 전수 해소(67건/50파일/15확장) — 서버 실패 사유를 그대로 표면화,
 change-password 오변수(response→error) 교정
- 코어 플러그인 설정 검증 안내의 항목 표시명이 스키마 라벨(ko/en) 폴백에 덮여 요청 로케일
 (ja) 라벨을 잃던 회귀 정정 — 번역 등록이 있으면 그것을 우선 (7.0.7 미출시 기능 자체 결함)
- 사전 결함 정리(Icon 등가표 27·darkmode 2·validated 통일), API 문서·CHANGELOG·ja 팩 동기
- develop(60652fdc0) 리베이스: getTable 정비와 병합 — 양측 의도 보존 (충돌 18파일)

2026-08-17 17:04:44 +09:00

4.4 KiB

Raw Blame History

Vbank / 통보 수신 API 레퍼런스

소유: 플러그인 sirsoft-pay_nicepayments. 이 문서는 결제대행사(나이스페이먼츠) 서버가 직접 POST 로 보내는 통보 수신 경로를 서술한다. 브라우저가 접속하는 결제 콜백과는 접근 제어가 다르다.

TL;DR (5초 요약)

1. 나이스페이먼츠 서버가 직접 보내는 가상계좌 입금통보를 받는 경로다
2. 통보 수신 경로는 나이스페이먼츠 공식 발신 IP 만 허용한다 (위변조·재처리 방어)
3. IP 화이트리스트는 코어 확장 미들웨어 self-gate 로 통보 라우트명에만 적용된다
4. 브라우저 결제 콜백(payment.callback)에는 IP 확인이 적용되지 않는다
5. 검사 동작·허용 범위는 라우트 파일 직접 부착 시절과 동일하다

통보 수신 경로

라우트명	메서드/URI	용도
`web.plugins.sirsoft-pay_nicepayments.payment.vbank-notify`	`POST /plugins/sirsoft-pay_nicepayments/payment/vbank-notify`	가상계좌 입금통보 수신

설명

위 경로는 나이스페이먼츠 서버가 구매자의 가상계좌 실입금을 가맹점에 알리기 위해 직접 POST 로 호출한다. 브라우저를 거치지 않는 서버 대 서버 통신이므로, 위변조·재처리 요청을 막기 위해 나이스페이먼츠 공식 발신 IP 만 허용한다.

이 IP 화이트리스트 검사는 코어의 확장 미들웨어 self-gate(Plugin::getMiddleware() 의 targets 로 위 통보 라우트명에만 정밀 타게팅)로 수행된다. 브라우저가 접속하는 결제 콜백(payment.callback)에는 적용되지 않는다 — 콜백은 정상 사용자의 브라우저에서 임의 IP 로 도달하므로 IP 로 제한하면 결제가 끊긴다. 검사 자체의 동작·허용 범위는 라우트 파일에서 직접 부착하던 이전 방식과 동일하다.

상세: docs/backend/middleware.md "확장 미들웨어 선언 (self-gate)".

입금 완료 건 환불 (관리자 JSON API)

POST /api/plugins/sirsoft-pay_nicepayments/admin/vbank-refund

라우트명: api.plugins.sirsoft-pay_nicepayments.vbank.refund
컨트롤러: Plugins\Sirsoft\PayNicepayments\Controllers\AdminVbankRefundController@refund
인증/권한: auth:sanctum + permission:admin,sirsoft-ecommerce.orders.update

입금이 완료된 가상계좌는 일반 환불 훅으로 처리할 수 없다 — 나이스페이먼츠가 환불받을 계좌 정보(계좌번호·은행코드·예금주)를 요구하기 때문이다. 이 경로가 해당 정보를 수집해 취소 API 를 호출하고 주문 취소·결제 상태 반영까지 수행한다.

요청 파라미터 (형식·길이 위반은 PG 호출 전에 422 — VbankRefundRequest)

이름	위치	타입	필수	허용값	용도
tid	body	string	예	max 30	거래번호(TID)
moid	body	string	예	max 64	주문번호(MOID)
cancel_amt	body	integer	예	1 ~ 999999999999	취소 금액. 결제 금액과 불일치 시 422
cancel_msg	body	string	아니오	max 100	취소 사유. 미입력 시 기본 문구 사용
refund_acct_no	body	string	예	숫자만, max 16	환불 계좌번호
refund_bank_cd	body	string	예	숫자 3자리	환불 은행코드
refund_acct_nm	body	string	예	max 10	환불 예금주명

요청 예시

POST /api/plugins/sirsoft-pay_nicepayments/admin/vbank-refund HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "tid": "nictest00m02012104191651325596",
    "moid": "ORD-20260817-000001",
    "cancel_amt": 30000,
    "cancel_msg": "구매자 요청 환불",
    "refund_acct_no": "1234567890123",
    "refund_bank_cd": "004",
    "refund_acct_nm": "홍길동"
}

응답

성공(200): common.success envelope, data 는 나이스페이 취소 API 원본 응답.
실패:

상태	조건
422	입력 형식 위반 (`VbankRefundRequest` — PG 미호출) / 결제 상태가 환불 대상 아님 / 취소 금액 불일치
404	주문번호에 해당하는 주문 없음
409	동일 건 환불이 이미 처리 중
502	PG 취소 API 실패 또는 취소 후 주문 반영 실패 (서버 로그에 원문 기록)

4.4 KiB Raw Blame History