PORTONE (原 Iamport)
PortOne
统一 PG 接入
PortOne 通过一套 API 对接韩国多个 PG(Toss、KG Inicis、NICE、Kakao Pay、Naver Pay 等)。 本指南覆盖注册、PG 签约、渠道登记与 V2 API 调用。
平台费用
免费(仅 PG 手续费)
支持 PG
15+
所需材料
营业执照、PG 合同
Overview
开始前请确认
PortOne(原 Iamport)用一套 API 抽象了多家 PG。PortOne 自身免费,但需分别与各 PG 签约。新项目建议使用 V2(GraphQL/REST),V1 也仍在支持。
已完成事业者登记
个人与法人均可。
选择 PG
Toss、KG Inicis、NICE 等。
V2 还是 V1
新项目建议 V2。
Webhook 接收服务器
需 HTTPS 接口。
Step by Step
分步指南
01
SIGNUP
注册 PortOne 账号
在 admin.portone.io 注册。
- 邮箱注册或 Kakao 登录
- 填写事业者信息(营业号、法人、地址)
- 登记合同联系人
- 无需审核即可立即使用测试环境
02
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 等
03
TEST
配置测试商户
正式签约前先在测试环境跑通接入。
- 默认提供测试商户(KCP、Inicis、Toss 测试密钥)
- 测试卡号在文档中公开(docs.portone.io)
- 可测试账户转账、虚拟账户、手机支付等方式
- 在测试环境完整跑通前端与服务端流程
04
KEYS
签发 V2 API 密钥
新项目请使用 V2。
- Store ID:商户标识(可公开)
- API Secret:仅服务端使用,严禁泄露
- 放入 .env 隔离保存
- V2 同时提供 GraphQL 与 REST
- Channel Key:区分 PG 与支付方式的组合
05
CHANNEL
注册支付渠道
切换到正式收款时登记真实渠道。
- 控制台 > 支付接入 > 添加渠道
- 填写 PG、MID(商户号)、PG 颁发的密钥
- 按卡、账户转账、简易支付分别登记渠道
- 区分 Live 与 Test 渠道
- 通过渠道别名让前端选择
06
CLIENT
实现支付请求
从前端调起支付窗口。
- Browser SDK:@portone/browser-sdk
- PortOne.requestPayment({ storeId, channelKey, paymentId, ... })
- paymentId:订单唯一 ID(内部生成,建议 UUID)
- 支付完成后回调到前端
- React Native:@portone/react-native-sdk
07
VERIFY
服务端校验与订单确认
不能只信前端,要在服务端复核。
- 前端支付完成 → 向服务端发送 paymentId
- 服务端通过 PortOne API 查询支付信息
- 校验 amount、currency、paymentStatus
- 金额与预期一致才确认订单
- 阻止金额篡改的关键步骤
08
WEBHOOK
注册 Webhook
即时接收支付状态变化。
- 控制台 > Webhook > 添加端点
- 必须为 HTTPS URL,3 秒内返回 200
- 事件:Paid、Cancelled、Failed、VirtualAccountIssued
- 必须校验 X-PortOne-Signature
- 取消和退款流程建议基于 Webhook 处理
Pitfalls
常见卡点
只信前端支付结果
浏览器控制台可以篡改结果,务必在服务端通过 PortOne API 再次查询并校验金额。
API Secret 泄露
常见事故是硬编码后推到 GitHub,一旦泄露请立即重新签发。
混用测试与正式渠道
测试密钥调用正式渠道会失败,反之亦然,请用环境变量区分。
跳过 Webhook 签名校验
任何人都能向 Webhook 端点 POST,未校验签名直接更新状态可能被伪造订单。
只看 V1 文档开发
网上资料多以 V1 为主,新项目请优先查看 V2 文档。