결제·환불·정산 확장

결제 계층

src/Payment는 결제사 어댑터·설정·원장·환불·정산 계약을 제공합니다. src/Shop의 주문 서비스가 업무 상태·재고·반품·알림을 연결합니다. PG별 HTTP 세부를 주문 컨트롤러에 복사하지 않습니다.

브라우저 인증 성공과 서버 승인 성공을 구분합니다. 콜백은 세션 없이도 인증되어야 하고 주문·금액·통화·상점·환경과 서명/키를 확인합니다. 사용자 전달 금액을 승인 기준으로 그대로 신뢰하지 않습니다.

외부 승인과 DB

PG 승인 뒤 DB 저장이 실패하면 외부 거래는 DB 롤백으로 사라지지 않습니다. 구현된 보상 취소와 오류 원장을 확인합니다. 승인 상태가 불명확하면 거래 조회와 재처리 정책을 사용하고 새 승인으로 덮어쓰지 않습니다.

같은 거래·주문·취소 키의 요청은 중복 처리하지 않습니다. 네트워크 타임아웃을 무조건 실패로 간주해 결제·환불을 재요청하지 않습니다.

취소와 반품

회원 취소는 지원 상태와 소유권을 검사합니다. 결제 완료 카드 주문은 PG 전액 취소 결과를 받은 후 취소 상태·재고를 변경합니다. 무통장 실제 이체는 GNUCMS의 환불 기록과 별개입니다.

반품 완료는 회수 확인, 남은 결제액 환불, 판매수량 조정과 선택적 재고 복원을 연결합니다. 요청 종료는 환불 전만 허용하고 반복 완료에서 환불·재고·알림을 중복하지 않습니다. 부분 반품·교환 기능을 지원한다고 노출하지 않습니다.

정산 어댑터

SettlementAdapter 계약의 표준 형식으로 정산 CSV를 처리합니다. 결제사·환경·상점·거래 키를 복합 식별해 중복을 차단합니다. 수수료·지급액·매출일·지급일과 payment/refund의 부호를 유지합니다.

PG별 정산 API는 해당 권한·인증과 어댑터 구현을 추가해야 합니다. API 접수 비용이나 주문 매출을 실제 은행 지급액으로 간주하지 않습니다.

새 결제사 등록 계약

$app->paymentProviders()->register(new YourProvider());

YourProvider는 Provider를 구현해 고유 ID·표시명·설정 항목·검증·지원 수단·부분 환불 여부·결제창 조각 이름과 gateway(Settings)를 제공합니다. 고유 ID는 소문자로 시작하는 소문자·숫자·밑줄 32자 이하이며 중복 등록은 거절합니다. 사용자 입력으로 클래스나 템플릿 파일을 선택하지 않습니다.

query의 valid는 PG에서 조회한 상점·주문·금액·통화가 실제 주문과 모두 같을 때만 true입니다. 취소별 이력이 있으면 id·amount·at를 보존합니다. 환불 응답이 불확실하면 예외로 원장 보류를 유지합니다.

신규 온라인 주문은 카드만 지원합니다. 계좌이체·가상계좌·휴대폰·에스크로를 새 제공자 등록만으로 주문서에 추가하지 않습니다. 복합과세 PG 필드는 TaxAdapter에 추가하고 세금 계산을 게이트웨이에 중복 구현하지 않습니다. 외부 HTTPS 요청은 공식 주소·TLS·응답·인증을 검사하고 리다이렉트로 비밀키를 전달하지 않습니다.