This skill should be used when the user asks about "포트원 연동", "PortOne integration", "결제 연동", "PG 연동", "billing key", "빌링키", "정기결제", "웹훅", "payment API", or needs guidance on implementing payment functionality with PortOne. Provides comprehensive guidance for V1 and V2 API integration.
포트원(PortOne) 결제 연동에 필요한 핵심 개념과 MCP 도구 활용법을 안내한다. 구현이 필요하면 payment-code-generator 에이전트를, 검증이 필요하면 integration-validator 에이전트를 사용한다.
포트원은 온라인 결제, 본인인증, 파트너 정산 자동화를 위한 API와 SDK를 제공하는 서비스이다. 다양한 PG사(결제대행사)를 하나의 통합 API로 연동할 수 있어 개발 복잡도를 크게 줄일 수 있다.
PortOne 인증 스킴 우선 사용사용자가 버전을 지정하지 않은 경우, 신규 프로젝트면 V2를, 기존 코드가 있으면 해당 버전을 따른다.
결제 유형을 선택할 때 다음 설명을 참고하여 사용자에게 안내한다:
포트원 MCP 서버가 제공하는 도구들을 적극 활용한다.
V2 코드 작성 전 반드시 예시 코드 조회:
mcp__portone__readPortoneV2FrontendCode
- framework: react, html 중 선택
- pg: toss, nice, inicis 등
- pay_method: card, virtualAccount, easyPay 등
mcp__portone__readPortoneV2BackendCode
- framework: express, fastapi, flask, spring-kotlin 중 선택
- pg: 사용할 PG사
- pay_method: 결제 수단
mcp__portone__listPortoneDocs
- 문서 목록 조회
- dev_docs, help_docs, release_notes 필터링
mcp__portone__readPortoneDoc
- 개별 문서 내용 조회
- path, fields 지정
mcp__portone__regexSearchPortoneDocs
- 정규식 기반 문서 검색
- 키워드로 관련 문서 찾기
mcp__portone__readPortoneOpenapiSchemaSummary
- V1/V2 API 전체 요약
mcp__portone__readPortoneOpenapiSchema
- 특정 API 상세 스키마
- yaml_path로 경로 지정
mcp__portone__listStores
- 연결된 상점 정보
mcp__portone__getChannelsOfStore
- 상점의 채널 목록
mcp__portone__listSharedTestChannels
- 테스트용 공유 채널
readPortoneV2FrontendCode, readPortoneV2BackendCode 사용readPortoneDoc으로 관련 문서 조회SDK 로드 (V2):
import * as PortOne from "@portone/browser-sdk/v2";
결제 요청:
const response = await PortOne.requestPayment({
storeId: "store-id",
channelKey: "channel-key",
paymentId: `payment-${crypto.randomUUID()}`,
orderName: "주문명",
totalAmount: 1000,
currency: "KRW",
payMethod: "CARD",
});
결제 검증 (V2):
const response = await fetch(
`https://api.portone.io/payments/${paymentId}`,
{
headers: {
Authorization: `PortOne ${PORTONE_API_SECRET}`,
},
}
);
중요: V2 API 호출 시 Bearer 대신 PortOne 인증 스킴 우선 사용.
.env 파일).gitignore)if (response.code) {
// 에러 발생
console.error(response.message);
// 사용자에게 적절한 메시지 표시
}
app.post("/webhook", async (req, res) => {
const { payment_id, status } = req.body;
// 결제 상태 업데이트
// 주문 처리
res.status(200).send("OK");
});
mcp__portone__listSharedTestChannels로 테스트 채널 조회references/v2-integration-details.md - V2 연동 상세 가이드references/webhook-patterns.md - 웹훅 처리 패턴포트원 MCP 서버 도구를 통해 최신 문서와 API 스키마를 항상 조회할 수 있다. 코드 작성 전 반드시 예시 코드와 문서를 확인한다.