PortOne
統合PG連携
韓国国内の複数PG(Toss・KG Inicis・NICE・Kakao Pay・Naver Payなど)を1つのAPIでつなぐPortOne連携ガイドです。 アカウント作成からPG契約、チャンネル登録、V2 API呼び出しまでご案内します。
利用料
無料(PG手数料のみ)
対応PG
15以上
必要書類
事業者登録証・PG契約
Overview
始める前にご確認ください
PortOne(旧 Iamport)は複数のPGを1つのAPIで抽象化するサービスです。PortOne自体は無料ですが、各PGとの個別契約が必要です。新規プロジェクトはV2(GraphQL/REST)を推奨し、V1も継続サポートされています。
事業者登録が完了
個人・法人いずれも可。
PGを選択
Toss・KG Inicis・NICEなど。
V2 vs V1の判断
新規はV2推奨。
Webhook受信サーバー
HTTPSエンドポイントが必要。
Step by Step
ステップ別ガイド
SIGNUP
PortOneアカウント作成
admin.portone.ioで登録します。
- メール登録またはKakaoログイン
- 事業者情報を入力(事業者番号・代表者名・住所)
- 契約担当者情報を登録
- 審査なしで即テスト環境を利用可能
PG
PGの選択 & 契約
実決済のためのPG契約。PortOneコンソールから申請できます。
- 対応PG: Toss・KG Inicis・NICE・Kakao Pay・Naver Pay・PayPalなど
- PortOneコンソール > PG申請から手軽に提出
- PG審査は2–5営業日
- 手数料はPGにより異なる(一般カードで2.5–3.5%)
- 精算サイクルを選択(D+1 / D+3など)
TEST
テストストアの設定
本契約前にテストで連携を完成させます。
- テスト店舗が標準で提供される(KCP・Inicis・Tossのテストキー)
- テストカード番号のドキュメントあり(docs.portone.io)
- 実口座振替・仮想口座・携帯電話決済などの方式別テスト
- フロントとサーバーのフロー全体をテスト環境で完成させる
KEYS
V2 APIキー発行
新規プロジェクトはV2を使ってください。
- Store ID: 店舗識別子(公開OK)
- API Secret: サーバー専用・絶対に公開しない
- .envに分離して保存
- V2はGraphQL + RESTの両方を提供
- Channel Key: PGと決済手段の組み合わせを識別
CHANNEL
決済チャンネル登録
実決済への切り替え時に実チャンネルを登録します。
- コンソール > 決済連携 > チャンネル追加
- PG・MID(店舗ID)・PG発行キーを入力
- カード・口座振替・簡単決済ごとにチャンネルを登録
- ライブとテストのチャンネルを分離
- チャンネルエイリアスでフロントから選択可能
CLIENT
決済リクエストの実装
フロントエンドから決済ウィンドウを呼び出します。
- Browser SDK: @portone/browser-sdk
- PortOne.requestPayment({ storeId, channelKey, paymentId, ... })
- paymentId: 注文の固有ID(内部で生成、UUID推奨)
- 決済完了時にフロントへ結果コールバック
- React Native: @portone/react-native-sdk
VERIFY
サーバー検証 & 注文確定
フロントの結果だけを信じず、サーバーで再確認します。
- フロント決済完了 → サーバーにpaymentIdを送信
- サーバーからPortOne APIで決済情報を取得
- amount・currency・paymentStatusを検証
- 想定金額と一致すれば注文を確定
- 金額改ざんを防ぐ核となる工程
WEBHOOK
Webhook登録
決済ステータスの変化を即座に受信します。
- コンソール > Webhook > エンドポイント追加
- HTTPS URL必須、3秒以内に200応答
- イベント: Paid・Cancelled・Failed・VirtualAccountIssued
- X-PortOne-Signatureの署名検証が必須
- 取消・返金フローはWebhookベースで処理を推奨
Pitfalls
詰まりやすいポイント
フロントの結果のみ信頼
ブラウザコンソールで結果を改ざんできるので、必ずサーバーからPortOne APIで再照会して金額を検証してください。
API Secretの露出
.env代わりにハードコードしてGitHubへ上げる事故が多発します。露出時は即再発行。
テストとライブのチャンネル混在
テストキーでライブチャンネルを呼ぶと失敗、逆も同じ。環境変数で区別してください。
Webhook署名検証の省略
誰でもWebhookエンドポイントへPOSTできます。署名検証なしに状態を更新すると注文偽造が可能です。
V1文書のみで開発
ネット上の情報は多くがV1基準です。新規プロジェクトはV2文書を優先してください。