korean-payment-gateway

Korean Payment Gateway Integration (PortOne V2 SDK)

Overview

PortOne (포트원, formerly 아임포트) is a Korean payment gateway aggregator. It unifies multiple PG providers (KG이니시스, NHN KCP, 토스페이먼츠, etc.) under a single JavaScript SDK.

This skill covers the PortOne V2 SDK (@portone/browser-sdk) integration into a vanilla JS SPA (no bundler).

Architecture

Browser SPA ──PortOne.requestPayment()──▶ PortOne Cloud ──PG routing──▶ PG provider
     │                                          │
     │ txId + paymentId                         │ PortOne API verify
     ▼                                          ▼
Your Backend ◀──── payment/verify API ─────── PortOne server SDK

Step 1: SDK Loading

CDN (Vanilla JS — no bundler)

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

This sets window.PortOne globally.

NPM (Bundler — Vite, webpack, etc.)

npm i @portone/browser-sdk

import PortOne from '@portone/browser-sdk/v2';

Step 2: Configuration

Two values from PortOne Admin Console → 결제 연동 → 연동 정보:

Key	Description	Format
storeId	상점 아이디	store-abc123
channelKey	채널 키 (per-channel)	channel-key-xxxxx

const PORTONE_CONFIG = {
  storeId: 'store-YOUR_STORE_ID',
  channelKey: 'channel-key-YOUR_CHANNEL_KEY',
};

Step 3: Payment Request

Basic Card Payment

const response = await window.PortOne.requestPayment({
  storeId: PORTONE_CONFIG.storeId,
  channelKey: PORTONE_CONFIG.channelKey,
  paymentId: `ORDER-${Date.now()}-${Math.random().toString(36).slice(2,8)}`,
  orderName: 'Premium Report',
  totalAmount: 10000,          // Integer (KRW = 1×)
  currency: 'KRW',
  payMethod: 'CARD',
});

NaverPay / KakaoPay (Easy Pay)

const response = await window.PortOne.requestPayment({
  storeId: PORTONE_CONFIG.storeId,
  channelKey: PORTONE_CONFIG.channelKey,
  paymentId: `ORDER-${Date.now()}`,
  orderName: 'Premium Report',
  totalAmount: 10000,
  currency: 'KRW',
  payMethod: 'EASY_PAY',
  easyPay: { easyPayProvider: 'NAVERPAY' }, // or 'KAKAOPAY'
});