portone-payment-integration

PortOne V2 Payment Integration (Korean PG)

Overview

PortOne (포트원, formerly 아임포트/I'mport) is a Korean payment gateway aggregator. This skill covers integration with a Cloudflare Workers backend and vanilla JS SPA frontend, using the PortOne V2 SDK (@portone/browser-sdk).

When to Use

• Adding Korean PG payment (KG이니시스, 카카오페이, 토스페이먼츠, etc.) to a web app
• Need per-entity/per-record purchase tracking (not per-account)
• Integrating with Cloudflare Workers + D1 database
• Setting up payment verification backend

Core Architecture

Data Flow

User → SPA (PaymentView) → PortOne SDK → PG 결제창
                                          ↓ 성공
                                    SPA → POST /api/payment/verify
                                          ↓
                                    CF Worker → PortOne API 검증
                                          ↓
                                    D1 purchases 테이블 저장
                                          ↓
                                    SPA localStorage 캐시 (fallback)

Required Configuration

const PORTONE_CONFIG = {
  storeId: 'store-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',  // PortOne admin console
  channelKeys: {
    naverpay: 'channel-key-...',   // KG이니시스 (네이버페이)
    kakaopay: 'channel-key-...',   // 카카오페이
    card: 'channel-key-...',       // 한국결제네트웍스
  },
};

Frontend Integration

SDK Loading

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

The SDK exposes window.PortOne.requestPayment().

Payment Request

const response = await window.PortOne.requestPayment({
  storeId: PORTONE_CONFIG.storeId,
  channelKey: PORTONE_CONFIG.channelKeys[selectedMethod],
  paymentId: `ORDER-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
  orderName: config.title,
  totalAmount: config.amount,      // integer (KRW = 1x)
  currency: 'KRW',
  customer: {
    email: user?.email || '',
    fullName: user?.name || '',
    phoneNumber: payerPhone || undefined,
  },
  redirectUrl: window.location.href,
  payMethod: 'EASY_PAY',           // 'CARD' | 'EASY_PAY' | 'TRANSFER' | etc.
  easyPay: { easyPayProvider: 'NAVERPAY' },
});