포트원 결제 연동: V1·V2 차이와 결제 검증·웹훅 처리

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

포트원은 여러 PG사의 결제 기능을 공통된 SDK와 API로 연결하는 서비스입니다. 아임포트는 이전 브랜드명이며, 현재 개발 문서는 V1과 V2로 구분됩니다. 오늘은 버전별 차이와 V2 결제 요청, 서버 검증, 웹훅 흐름을 알아보겠습니다.

포트원 결제 연동, PG 위에 한 겹을 얹는 구조입니다

PG마다 SDK와 API 규격이 달라 PG를 하나 더 붙이면 결제 코드도 한 벌 늘어납니다. 포트원은 그 사이에 들어가는 통합 레이어라서 서비스는 포트원만 호출하고, 결제는 콘솔에 연결해 둔 KG이니시스, NHN KCP, 토스페이먼츠 같은 PG로 나갑니다. PG를 옮길 때도 주로 콘솔 설정과 채널 키를 바꿉니다.

아임포트와 포트원 V2, 무엇이 달라졌나

포트원 개발자센터는 지금도 V1과 V2 문서를 따로 두는데, SDK도 서버 인증도 다릅니다.

V1은 아임포트 시절 방식을 이어갑니다.

cdn.iamport.kr에서 SDK를 불러와 IMP.init()에 고객사 식별코드를 넣고 IMP.request_pay()로 결제창을 엽니다. 서버는 api.iamport.kr에서 액세스 토큰부터 받은 뒤 imp_uid로 결제를 조회합니다.

V2는 Store ID와 채널 키로 결제를 구분합니다.

@portone/browser-sdk의 PortOne.requestPayment()를 쓰고 결제 건은 고객사가 만든 paymentId로 추적합니다. 서버는 토큰 없이 V2 전용 API Secret을 헤더에 넣어 api.portone.io를 부릅니다. 새 연동에서는 V2의 지원 PG와 필요한 기능을 확인해 버전을 선택합니다.

포트원 V2 결제 요청과 서버 처리 흐름

콘솔에 가입하고 PG 채널을 연결합니다.

관리자 콘솔 가입은 무료입니다. [결제 연동] → [연동 관리] → [채널 관리]에서 결제대행사와 결제 모듈을 고르면 채널이 생기고, 전자결제 신청 전에도 테스트 채널로 개발할 수 있습니다.

Store ID와 채널 키를 확인합니다.

콘솔 결제 연동 페이지에서 두 값을 확인합니다. 채널 키가 연결할 PG를 지정합니다. PG를 변경할 때는 지원 결제수단과 추가 파라미터, 환불·정기결제 동작도 함께 확인합니다.

브라우저에서 결제를 요청합니다.

paymentId는 결제 건을 구분하는 식별자입니다. 서버에서 주문과 연결하고, 같은 주문이 여러 결제 건으로 처리되지 않도록 중복 처리도 관리합니다. 아래는 SDK를 불러온 뒤 실행하는 요청 예시입니다.

const response = await PortOne.requestPayment({
  storeId: "store-...",
  channelKey: "channel-key-...",
  paymentId: `payment-${crypto.randomUUID()}`,
  orderName: "예시 상품",
  totalAmount: 1000,
  currency: "CURRENCY_KRW",
  payMethod: "CARD",
});

서버에서 결제 단건 조회로 금액을 검증합니다.

브라우저를 거친 금액은 조작될 수 있으니 서버가 결제를 다시 조회해 금액이 같고 상태가 PAID일 때만 주문을 확정합니다.

const res = await fetch(
  `https://api.portone.io/payments/${encodeURIComponent(paymentId)}`,
  { headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` } },
);
const payment = await res.json();
// HTTP 응답 성공 여부를 먼저 확인합니다.
// 서버에 저장한 주문의 금액·통화·paymentId와 비교하고
// payment.status가 "PAID"인지 확인한 뒤 중복 없이 주문을 확정합니다.

웹훅으로 놓친 결과를 받아 냅니다.

네트워크가 끊기면 결과가 누락되기도 해서 콘솔 [결제알림(Webhook) 관리]에 URL을 등록해 둡니다. Transaction.Paid 같은 이벤트가 서버로 오면 서명은 웹훅 시크릿으로 검증합니다. 같은 알림이 재전송되어도 주문 처리와 권한 지급은 한 번만 이루어지도록 구성합니다.

직접 PG 연동과 포트원, 비용까지 비교하면

포트원 공식 요금 페이지 기준으로 Free 플랜은 월 순거래액 5,000만 원 미만까지 무료이고, 그 위는 거래액 구간별 Growth 1~3이 월 10만·30만·50만 원(부가세 별도)입니다. PG를 여러 개 붙여도 이용료는 같고 PG 가입비와 수수료는 따로 냅니다. 대신 중간 계층이 늘어 포트원 장애에도 영향을 받습니다. PG가 하나뿐이고 바꿀 계획도 없다면 직접 연동이 더 단순합니다.

세부 항목과 최신 적용 조건은 포트원 V2 개발 가이드를 참고해 보세요.

결제창부터 주문 확인까지, 하나의 흐름으로

결제 흐름을 하나씩 붙이다 보면 화면뿐 아니라 데이터와 운영 방식도 함께 살펴보게 됩니다. 지금 서비스에 필요한 범위부터 차근차근 정리해볼 수 있습니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 사용자가 이용하는 화면과 운영에 필요한 기능을 연결해 서비스를 만들어가는 과정을 돕습니다.

결제 흐름을 준비하면서 궁금한 점이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)