포트원(PortOne) 결제 연동 가이드

해당 연동 가이드는 포트원 결제모듈 v2를 기준으로 합니다.

0. 기존 설정대로 빠르게 테스트만 해보는 경우

0.1 포트원 관리자 콘솔 접속

1. 관리자 콘솔 (opens in a new tab) 접속
2. 회원가입 및 로그인
3. [결제 연동] > [연동 정보] > 테스트 활성화
4. 우측 상단에 대표 상점 아이디(store_id) .env.local 파일에 입력
5. pg사 토스페이먼츠 선택 > 채널키 복사 > .env.local 파일에 입력
6. 식별코드. API Keys 이동 > V2 API Secret Key 생성 > .env.local 파일에 입력
7. 결제 테스트 해보기

1. 포트원 계정 설정

1.1 계정 생성 및 관리자 콘솔 접속

1. 포트원 홈페이지 (opens in a new tab) 접속
2. 회원가입 및 로그인
3. 관리자 콘솔 (opens in a new tab) 접속

1.2 상점 정보 등록

1. 관리자 콘솔 → [상점관리] → [상점 정보]
2. 필수 정보 입력:

   - 상호명
   - 사업자등록번호
   - 대표자명
   - 전화번호
   - 사업장 주소
   - 고객센터 연락처

1.3 결제 연동 정보 확인

1. 관리자 콘솔 → [결제연동] → [연동 정보]
2. 중요 정보 저장:

   - 가맹점 식별코드 (IMP_UID)
   - REST API 키
   - REST API Secret

2. PG사 계약 및 설정

2.1 PG사 선택 및 계약

1. 관리자 콘솔 → [결제연동] → [PG설정]
2. PG사 선택 (예: 토스페이먼츠, KG이니시스 등)
3. 선택한 PG사와 계약 진행
4. 계약 완료 후 PG사 제공 정보 입력:

   - PG상점아이디
   - PG상점 키
   - 기타 PG사별 필수 정보

2.2 테스트 모드 설정

1. 관리자 콘솔 → [결제연동] → [테스트 결제]
2. 테스트 모드 활성화
3. 테스트용 카드 정보 확인

3. 프로젝트 설정

3.1 포트원 SDK 설치

npm install portone-sdk
# 또는
yarn add portone-sdk

3.2 환경변수 설정

.env.local 파일에 추가:

NEXT_PUBLIC_PORTONE_IMP_UID=your_imp_uid
PORTONE_REST_API_KEY=your_api_key
PORTONE_REST_API_SECRET=your_api_secret

3.3 포트원 스크립트 추가

pages/_document.js 또는 결제 페이지에 추가:

<script src="https://cdn.portone.io/v2/browser-sdk.js"></script>

4. 결제 테스트

4.1 테스트 결제 카드 정보

카드번호: 4242-4242-4242-4242
유효기간: 아무 미래 날짜
CVC: 아무 3자리 숫자
비밀번호: 아무 숫자 앞 2자리

4.2 결제 테스트 모드 구분

실 결제 환경: https://service.portone.io
테스트 환경: https://service.test.portone.io

5. 실 운영 전 체크리스트

5.1 기본 설정 확인

• PG사 계약 완료 및 정보 등록
• 상점 정보 등록 완료
• 결제 수단 설정 완료
• 웹훅 URL 설정 (필요한 경우)

5.2 보안 설정

• API 키 보안 처리
• 결제 위변조 검증 로직 구현
• 결제 금액 검증 로직 구현

5.3 에러 처리

• 결제 실패 시 에러 처리
• 네트워크 오류 처리
• 결제 취소 처리

주의사항

보안

1. API 키 노출 주의

   - REST API Secret은 절대 프론트엔드에 노출되지 않도록 주의
   - 환경변수 관리 철저

2. 결제 검증

   - 결제 완료 후 반드시 서버에서 결제 금액 검증
   - 위변조 여부 확인

결제 테스트

1. 테스트 모드에서 충분한 테스트 진행
2. 실제 결제 전환 시 테스트 모드 비활성화 확인
3. 각 결제 수단별 테스트 진행

실 운영

1. 결제 취소 및 환불 정책 수립
2. 고객 지원 체계 구축
3. 결제 로그 관리 방안 수립