Overview
시작 전에 확인하세요
포트원(구 아임포트)은 여러 PG를 하나의 API로 추상화해주는 서비스입니다. 포트원 자체는 무료지만, 각 PG와 별도 계약이 필요합니다. 신규 프로젝트는 V2(GraphQL/REST)를 권장하며, 기존 V1도 계속 지원됩니다.
사업자등록 완료
개인·법인 모두 가능.
PG 선택
토스·KG이니시스·NICE 등.
V2 vs V1 결정
신규는 V2 권장.
웹훅 수신 서버
HTTPS 엔드포인트 필요.
Step by Step
단계별 가이드
SIGNUP
포트원 계정 생성
admin.portone.io에서 가입.
- 이메일 가입 또는 카카오 로그인
- 사업자 정보 입력 (사업자번호·대표자명·주소)
- 계약 담당자 정보 등록
- 심사 없이 즉시 테스트 환경 사용 가능
PG
PG사 선택 & 계약
실결제를 위한 PG사 계약. 포트원 콘솔에서 신청 가능.
- 지원 PG: 토스·KG이니시스·NICE·카카오페이·네이버페이·페이팔 등
- 포트원 콘솔 > PG 신청에서 간편 접수
- PG사 심사 2–5영업일 소요
- 수수료는 PG별 상이 (일반 카드 2.5~3.5%)
- 정산 주기 선택 (D+1 / D+3 등)
TEST
테스트 스토어 설정
실계약 전에 테스트로 연동을 완성합니다.
- 테스트 상점 기본 제공 (KCP·이니시스·토스 테스트 키)
- 테스트 카드번호 문서 제공 (docs.portone.io)
- 실 계좌이체·가상계좌·휴대폰 결제 등 방식별 테스트
- 프론트·서버 플로우 전체를 테스트 환경에서 완성
KEYS
V2 API 키 발급
신규 프로젝트는 V2를 사용하세요.
- Store ID: 상점 식별자 (공개 가능)
- API Secret: 서버 전용 · 절대 노출 금지
- .env로 분리 저장
- V2는 GraphQL + REST 모두 제공
- 채널 키(Channel Key): PG·결제수단 조합별 식별
CHANNEL
결제 채널 등록
실결제로 전환할 때 실 채널 등록.
- 콘솔 > 결제 연동 > 채널 추가
- PG사·MID(상점 ID)·PG 제공 키 입력
- 카드·계좌이체·간편결제별로 각각 채널 등록
- 라이브·테스트 채널을 분리
- 채널 별칭으로 프론트에서 선택 가능
CLIENT
결제 요청 구현
프론트엔드에서 결제창 호출.
- 브라우저 SDK: @portone/browser-sdk
- PortOne.requestPayment({ storeId, channelKey, paymentId, ... })
- paymentId: 주문 고유 ID (내부에서 생성, UUID 권장)
- 결제 완료 시 프론트로 결과 콜백
- React Native: @portone/react-native-sdk
VERIFY
서버 검증 & 주문 확정
프론트 결과만 믿지 말고 서버에서 재확인.
- 프론트 결제 완료 → 서버에 paymentId 전송
- 서버에서 포트원 API로 결제 정보 조회
- amount·currency·paymentStatus 검증
- 예상 금액과 일치하면 주문 확정
- 금액 조작 시도를 막는 핵심 단계
WEBHOOK
웹훅 등록
결제 상태 변경을 즉시 수신.
- 콘솔 > 웹훅 > 엔드포인트 추가
- HTTPS URL 필수, 3초 이내 200 응답
- 이벤트: Paid · Cancelled · Failed · VirtualAccountIssued
- X-PortOne-Signature 서명 검증 필수
- 취소·환불 흐름은 웹훅 기반으로 처리 권장
Pitfalls
자주 막히는 부분
프론트 결제 결과만 신뢰
브라우저 콘솔에서 결과를 조작할 수 있으니, 반드시 서버에서 포트원 API로 재조회해 금액을 검증하세요.
API Secret 노출
.env 대신 하드코딩했다가 GitHub에 올리는 사고가 자주 있습니다. 노출 시 즉시 재발급.
테스트·라이브 채널 혼용
테스트 키로 라이브 채널을 호출하면 실패, 반대도 마찬가지. 환경변수로 구분.
웹훅 서명 검증 생략
누구나 웹훅 엔드포인트에 POST를 쏠 수 있습니다. 서명 검증 없이 상태 업데이트하면 주문 위조 가능.
V1 문서만 보고 개발
인터넷에 있는 자료 중 다수가 V1 기준입니다. 신규 프로젝트는 V2 문서를 우선 보세요.