포트원 실전 가이드: 1인 개발자를 위한 한국 결제 연동의 정석

한국 결제 연동의 현실

한국에서 서비스를 만들고 결제를 붙이려는 순간, 현실의 벽에 부딪힌다.

PG사가 뭔지 알아야 한다. 카드사 직접 계약과 PG 계약의 차이도 파악해야 한다. 카카오페이는 KCP나 나이스페이를 통해야 하는 경우도 있고, 토스페이먼츠는 직접 계약이 가능하다. 결제 위젯 SDK는 각 PG사마다 다르고, 보안 요구사항도 제각각이다.

해외처럼 "Stripe 하나로 끝"이 안 되는 구조다.

포트원(구 아임포트)은 이 문제를 정면 돌파한다. PG사 25개를 하나의 SDK로 추상화해서, 개발자가 각 PG사의 SDK를 따로 공부하지 않아도 되게 만든다. 서비스에서 결제 수단을 바꾸거나 추가할 때도 코드 변경을 최소화한다.

---

포트원이 뭔가

포트원은 2014년 "아임포트"라는 이름으로 시작한 결제 연동 미들웨어다. 2023년 포트원으로 브랜드를 바꾸고 V2 아키텍처를 새로 출시했다.

핵심 역할은 결제 연동 레이어다. 서비스(앱)와 PG사 사이에서 통신을 중계하고, PG사별 SDK 차이를 흡수하고, 결제 검증을 처리한다.

서비스(앱)
    ↓ 포트원 SDK
포트원 서버
    ↓ PG사별 API
카카오페이 / 토스페이먼츠 / KG이니시스 / 나이스페이 / ...

개발자 입장에서는 포트원 SDK만 알면 된다. PG사를 바꿔도 코드를 크게 수정할 필요가 없다.

---

V2 아키텍처: 뭐가 달라졌나

포트원 V1과 V2는 설계 철학부터 다르다.

REST API + channelKey 기반

V1은 IMP.request_pay()처럼 JavaScript 함수 호출 방식이었다. V2는 REST API + channelKey 기반으로 완전히 재설계됐다.

// V1 방식 (구 아임포트)
IMP.request_pay({
  pg: 'kcp',
  pay_method: 'card',
  merchant_uid: 'order_001',
  name: '테스트 상품',
  amount: 10000,
}, callback);

// V2 방식 (포트원 V2)
import PortOne from "@portone/browser-sdk/v2";

const response = await PortOne.requestPayment({
  storeId: "store-xxx",
  channelKey: "channel-xxx",   // PG사 채널 식별자
  paymentId: `payment-${Date.now()}`,
  orderName: "테스트 상품",
  totalAmount: 10000,
  currency: "KRW",
  payMethod: "CARD",
});

channelKey는 포트원 콘솔에서 PG사 채널을 추가할 때 발급되는 식별자다. 코드에 PG사 이름을 직접 박지 않아도 되고, PG사를 바꿀 때 콘솔에서 채널만 교체하면 된다.

TypeScript 타입 완비

V2의 가장 큰 변화다. SDK 전체에 TypeScript 타입이 제공된다.

import type { PaymentRequest } from "@portone/browser-sdk/v2";

const paymentRequest: PaymentRequest = {
  storeId: "store-xxx",
  channelKey: "channel-xxx",
  paymentId: "payment-001",
  orderName: "구독권",
  totalAmount: 9900,
  currency: "KRW",
  payMethod: "CARD",
};

payMethod에 오타를 내거나, currency에 지원하지 않는 값을 넣으면 컴파일 에러가 난다. V1 시절에는 런타임에서야 알던 버그들이 개발 단계에서 잡힌다.

서버 사이드 검증

결제는 클라이언트 단에서 금액을 위변조할 수 있기 때문에, 서버 사이드 검증이 필수다. V2는 REST API로 결제 내역을 조회하는 방식이 깔끔하다.

// 서버 사이드: 결제 완료 검증
const paymentResponse = await fetch(
  `https://api.portone.io/payments/${paymentId}`,
  {
    headers: {
      Authorization: `PortOne ${process.env.PORTONE_API_SECRET}`,
    },
  }
);

const payment = await paymentResponse.json();

// 금액 검증
if (payment.amount.total !== expectedAmount) {
  throw new Error("결제 금액 불일치");
}

// 상태 검증
if (payment.status !== "PAID") {
  throw new Error("결제 미완료");
}

V1에서는 아임포트 자체 검증 API를 쓰거나, 각 PG사 API를 직접 호출해야 했다. V2는 포트원 단일 API로 통일된다.

---

핵심 기능 5가지

1. 멀티 PG 지원

포트원이 지원하는 PG사 목록은 방대하다. 국내 주요 PG사부터 간편결제, 해외 결제까지 커버한다.

국내 PG사: KG이니시스, NHN KCP, 나이스페이, KICC, 웰컴페이먼츠, 스마트로, 토스페이먼츠, 카카오페이, 네이버페이, 페이코 등

해외: PayPal, Stripe, Alipay, WeChat Pay

코드 레벨에서는 channelKey만 바꾸면 PG사가 바뀐다. 마케팅 목적으로 특정 카드사 프로모션을 활용하거나, PG사 수수료를 비교해서 더 저렴한 곳으로 갈아타는 전략이 가능해진다.

2. 정기결제 / 구독 지원

SaaS나 구독 서비스를 만드는 1인 개발자에게 핵심 기능이다. 반복결제에 특화된 대안으로는 페이플도 있다.

// 빌링키 발급 (카드 정보 토큰화)
const billingKeyResponse = await PortOne.requestIssueBillingKey({
  storeId: "store-xxx",
  channelKey: "channel-xxx",
  billingKeyMethod: "CARD",
  issueId: `issue-${Date.now()}`,
  issueName: "구독 카드 등록",
});

// 빌링키로 정기 결제 (서버 사이드)
await fetch("https://api.portone.io/payments/schedule", {
  method: "POST",
  headers: {
    Authorization: `PortOne ${PORTONE_API_SECRET}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment: {
      billingKey: billingKeyResponse.billingKey,
      orderName: "월 구독",
      amount: { total: 9900 },
      currency: "KRW",
    },
    timeToPay: nextBillingDate.toISOString(),
  }),
});

빌링키는 카드 번호 원본을 저장하지 않고 토큰 형태로 관리하는 방식이다. PCI-DSS 인증 부담을 포트원이 흡수해준다.

3. 스마트 라우팅

같은 결제 요청을 여러 PG사 중 조건에 맞는 곳으로 자동 라우팅하는 기능이다. Growth 플랜 이상에서 사용 가능하다.

• 수수료 최저 경로로 자동 선택
• 특정 PG사 장애 시 다른 PG사로 폴오버
• 카드사별 최적 PG사 매핑

1인 개발자에게는 당장 필요 없을 수 있지만, 결제 규모가 커지면 수수료 절감 효과가 유의미하다.

4. 파트너 정산 자동화

마켓플레이스나 플랫폼 서비스처럼 판매자와 구매자를 중개하는 모델에서 유용한 기능이다.

• 판매자별 정산 금액 자동 계산
• 수수료 공제 후 정산
• 정산 내역 리포트

1인 개발자가 직접 정산 로직을 구현하려면 상당한 공수가 들어간다. 포트원이 이걸 처리해준다.

5. 결제 분석 대시보드

포트원 콘솔에서 결제 현황을 실시간으로 모니터링할 수 있다.

• 결제 성공/실패 비율
• PG사별 성공률 비교
• 결제 수단별 통계
• 이상 거래 감지

별도 분석 도구를 붙이지 않아도 기본적인 결제 데이터 파악이 가능하다.

---

요금제

포트원은 2025년 유료 전환을 단행했다. 기존에는 거의 무제한 무료였지만, 현재는 결제 규모에 따라 플랜이 나뉜다.

플랜	월 요금	결제 한도	특징
Free	무료	월 5천만 원 미만	기본 PG 연동, 표준 지원
Growth	10~50만 원	제한 없음	스마트 라우팅, 파트너 정산, 우선 지원
Enterprise	별도 협의	제한 없음	커스텀 계약, 전담 지원

PG사 수수료는 별도다. 포트원 요금과 관계없이 각 PG사 계약에 따라 수수료가 부과된다. 카드 결제 기준 PG사 수수료는 보통 1~3% 수준이다.

---

V1 → V2 마이그레이션 주의사항

기존에 아임포트(V1)를 쓰고 있다면 V2 마이그레이션 전에 알아야 할 것들이 있다.

혼재 시 검증 오류

V1과 V2는 결제 검증 API가 완전히 다르다. 같은 서비스 내에서 V1 결제는 V1 API로, V2 결제는 V2 API로 검증해야 한다. 코드베이스에 두 버전이 혼재하면 검증 실수가 발생하기 쉽다.

API 키 체계 변경

V1은 imp_uid + merchant_uid 체계였다. V2는 paymentId + storeId + channelKey 체계로 바뀐다. DB 스키마와 결제 내역 조회 로직을 함께 수정해야 한다.

웹훅 형식 변경

V1 웹훅과 V2 웹훅은 페이로드 구조가 다르다. 웹훅을 수신해서 처리하는 서버 로직도 마이그레이션 대상이다.

---

실전 연동: Next.js + 포트원 V2

실제 Next.js 프로젝트에 포트원 V2를 붙이는 패턴이다.

npm install @portone/browser-sdk

// app/payment/page.tsx (클라이언트 컴포넌트)
"use client";
import PortOne from "@portone/browser-sdk/v2";

export default function PaymentPage() {
  const handlePayment = async () => {
    const response = await PortOne.requestPayment({
      storeId: process.env.NEXT_PUBLIC_PORTONE_STORE_ID!,
      channelKey: process.env.NEXT_PUBLIC_PORTONE_CHANNEL_KEY!,
      paymentId: `payment-${Date.now()}`,
      orderName: "Agentic30 구독",
      totalAmount: 99000,
      currency: "KRW",
      payMethod: "CARD",
      customer: {
        email: "user@example.com",
      },
    });

    if (response?.code !== undefined) {
      alert(`결제 실패: ${response.message}`);
      return;
    }

    // 서버 사이드 검증 요청
    const verifyResponse = await fetch("/api/payment/verify", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ paymentId: response.paymentId }),
    });

    if (verifyResponse.ok) {
      alert("결제 완료!");
    }
  };

  return (
    <button onClick={handlePayment}>
      결제하기
    </button>
  );
}

// app/api/payment/verify/route.ts (서버 사이드 검증)
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const { paymentId } = await request.json();

  // 포트원 API로 결제 정보 조회
  const paymentResponse = await fetch(
    `https://api.portone.io/payments/${paymentId}`,
    {
      headers: {
        Authorization: `PortOne ${process.env.PORTONE_API_SECRET}`,
      },
    }
  );

  const payment = await paymentResponse.json();

  // 금액 및 상태 검증
  if (payment.status !== "PAID" || payment.amount.total !== 99000) {
    return NextResponse.json({ error: "결제 검증 실패" }, { status: 400 });
  }

  // DB에 결제 내역 저장
  // await savePaymentRecord(payment);

  return NextResponse.json({ success: true });
}

---

장단점 정리

아쉬운 점

포트원도 단점이 있다. 솔직하게 짚어본다.

유료 전환 충격: 완전 무료였던 시절과 달리, 지금은 규모에 따라 월 10~50만 원이 든다. 소규모 프로젝트라면 Free 플랜으로 해결되지만, 성장하면 비용이 늘어난다.

V1/V2 혼재 혼란: V1을 쓰는 레거시 서비스가 많다. 구글링하면 V1 예제가 V2보다 훨씬 많이 나온다. V2로 새로 시작하면서 V1 예제를 따라가다가 혼선이 생기기 쉽다.

설정 복잡도: PG사 계약 → 포트원 콘솔에서 채널 추가 → channelKey 발급 → 코드 연동. 단계가 여러 개다. Stripe처럼 "회원가입하고 API 키 받으면 끝"이 아니다.

PG사 계약은 별도: 포트원은 연동 레이어일 뿐이다. 실제 결제를 받으려면 PG사와 별도 계약을 맺어야 한다. 사업자 등록도 필요하다. 포트원 가입만으로 결제를 받을 수 있는 게 아니다.

---

포트원이 맞는 경우

1인 개발자 관점에서 포트원을 선택하면 좋은 경우와 아닌 경우를 구분해보면:

포트원을 선택해야 할 때

• 한국 사용자를 대상으로 하는 서비스
• 여러 PG사나 결제 수단을 지원해야 하는 경우
• 카드 정기결제(구독)가 필요한 경우
• V2를 새로 시작하는 프로젝트

다른 옵션을 고려할 때

• 글로벌 결제만 필요한 경우 → Stripe 직접 연동이 더 단순 (SaaS 과세 대행까지 원하면 Paddle 검토)
• 국내 카드 결제만 필요하고 PG사 하나로 충분할 때 → 토스페이먼츠나 카카오페이 직접 연동도 가능
• 결제 규모가 커서 포트원 Growth 비용이 부담될 때 → PG사 직접 계약 비교 필요

---

한국 PG 한눈에 비교

항목	토스페이먼츠	포트원	페이플	PAYAPP
성격	PG 직영	PG 통합 미들웨어	스타트업 특화 PG	비사업자 결제
카드 수수료(영세)	0.8%	PG사별 (1.6~1.7%)	1.0%	1.9%
정산 주기	D+2~5일	PG사 따름	D+5 (D+1 멤버십)	D+5
플랫폼 요금	없음	Free~50만/월	가입비 22만	무료 이벤트
글로벌 결제	제한적	PayPal/Stripe 등	해외카드 5%	미지원
추천	단일 PG+빠른 정산	멀티 PG 전략	구독 SaaS	사업자 전용

언제 무엇을 선택할까

• 여러 PG를 하나로 관리하고 싶다 → 포트원
• PG 하나로 빠르게 시작 → 토스페이먼츠
• 카드+계좌 정기결제 특화 → 페이플
• 사업자 없이 디지털 콘텐츠 판매 → 그로블 (PAYAPP 라이트 종료)

---

결론

포트원은 한국 결제 연동의 복잡성을 가장 체계적으로 추상화한 도구다. 국내 PG사 25개를 하나의 SDK로 다루는 건 포트원 외에는 대안이 없다.

V2 아키텍처는 설계가 탄탄하다. TypeScript 타입 완비, REST API 기반 검증, channelKey로 PG사를 분리하는 구조 — 코드 품질 관점에서 V1보다 훨씬 낫다.

단, 포트원은 연동 레이어다. 포트원을 쓴다고 PG사 계약이나 사업자 등록 문제가 사라지지 않는다. 처음 결제 시스템을 붙이는 경우라면 PG사 계약부터 시작해야 한다.

Free 플랜 범위(월 5천만 원)에서는 충분히 무료로 운영할 수 있다. 사이드 프로젝트나 초기 스타트업에는 포트원 V2로 시작하는 것이 현재 시점에서 한국 결제 연동의 가장 합리적인 선택이다.

---

포트원 공식 문서: developers.portone.io