PortOne Integration Guide

포트원(PortOne) 결제 연동에 필요한 핵심 개념과 MCP 도구 활용법을 안내한다. 코드 생성에는 payment-code-generator 에이전트를, 코드 검증에는 integration-validator 에이전트를 사용한다.

Overview

포트원은 온라인 결제, 본인인증, 파트너 정산 자동화를 위한 API와 SDK를 제공하는 서비스이다. 다양한 PG사(결제대행사)를 하나의 통합 API로 연동할 수 있어 개발 복잡도를 크게 줄일 수 있다.

Version Selection: V1 vs V2

V2 (권장)

• 신규 프로젝트에 권장
• 최신 SDK와 API 설계
• 더 나은 타입 안전성
• Bearer/PortOne 인증 스킴 지원
• V2 API 호출 시 PortOne 인증 스킴 우선 사용

V1

• 레거시 프로젝트 지원
• 기존 연동 유지보수
• 일부 PG사 V1 전용 기능 존재

사용자가 버전을 지정하지 않은 경우, 신규 프로젝트면 V2를, 기존 코드가 있으면 해당 버전을 따른다.

Payment Types

결제 유형을 선택할 때 다음 설명을 참고하여 사용자에게 안내한다:

일반결제 (인증결제)

• PG사 결제창을 통한 결제
• 카드, 계좌이체, 가상계좌, 휴대폰 결제 등
• 일회성 결제에 적합
• 사용 시점: 쇼핑몰, 단건 상품 구매

정기결제 (빌링키 결제)

• 빌링키 발급 후 정기적으로 결제
• 구독 서비스, 월정액 서비스에 적합
• 사용 시점: SaaS, 구독 서비스, 정기 배송

수기결제 (키인결제)

• 카드 정보 직접 입력 결제
• 고객 인증 없이 결제 가능
• B2B 거래, 전화 주문에 적합
• 사용 시점: 콜센터, B2B 거래

본인인증

• 휴대폰/신용카드 본인인증
• 회원가입, 성인인증에 사용
• 사용 시점: 회원가입, 연령 제한 서비스

MCP Tools Usage

포트원 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
- 정규식 기반 문서 검색
- 키워드로 관련 문서 찾기

API 스키마 조회

mcp__portone__readPortoneOpenapiSchemaSummary
- V1/V2 API 전체 요약

mcp__portone__readPortoneOpenapiSchema
- 특정 API 상세 스키마
- yaml_path로 경로 지정

상점/채널 정보

mcp__portone__listStores
- 연결된 상점 정보

mcp__portone__getChannelsOfStore
- 상점의 채널 목록

mcp__portone__listSharedTestChannels
- 테스트용 공유 채널

Integration Workflow

1. 환경 파악

• 프론트엔드/백엔드 프레임워크 확인
• 포트원 버전 결정 (V1/V2)
• 결제 유형 결정

2. 예시 코드 조회

• V2의 경우 readPortoneV2FrontendCode, readPortoneV2BackendCode 사용
• V1의 경우 readPortoneDoc으로 관련 문서 조회

3. 코드 생성

• 예시 코드를 프로젝트 구조에 맞게 수정
• 환경 변수로 API 키 관리
• 에러 핸들링 추가

4. 웹훅 연동

• 결제 상태 변경 알림 처리
• 가상계좌 입금 통보 등

Code Generation Guidelines

프론트엔드

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 인증 스킴 우선 사용.

Security Considerations

API 키 관리

• API Secret은 절대 클라이언트에 노출하지 않음
• 환경 변수로 관리 (.env 파일)
• 커밋에서 제외 (.gitignore)

결제 검증

• 프론트엔드 결제 완료 후 반드시 서버에서 검증
• 금액 일치 여부 확인
• 결제 상태 확인

웹훅 검증

• 웹훅 시그니처 검증
• 중복 처리 방지 (멱등성)

Error Handling

일반적인 에러 케이스

• 사용자 결제 취소
• 카드 한도 초과
• 네트워크 오류
• PG사 오류

에러 응답 처리

if (response.code) {
  // 에러 발생
  console.error(response.message);
  // 사용자에게 적절한 메시지 표시
}

Webhook Integration

웹훅 설정

• 포트원 콘솔에서 웹훅 URL 등록
• HTTPS 필수
• 타임아웃 고려

웹훅 처리

app.post("/webhook", async (req, res) => {
  const { payment_id, status } = req.body;
  // 결제 상태 업데이트
  // 주문 처리
  res.status(200).send("OK");
});

Common Integration Patterns

일반결제 플로우

1. 클라이언트: SDK로 결제창 호출
2. 사용자: 결제 진행
3. 클라이언트: 결제 결과 수신
4. 서버: 결제 검증 API 호출
5. 서버: 주문 상태 업데이트

정기결제 플로우

1. 클라이언트: 빌링키 발급 창 호출
2. 서버: 빌링키 저장
3. 서버: 정기 스케줄에 따라 결제 API 호출
4. 서버: 결제 결과 처리

Testing

테스트 환경

• 포트원 테스트 채널 사용
• 실제 결제 없이 연동 테스트
• mcp__portone__listSharedTestChannels로 테스트 채널 조회

테스트 카드

• PG사별 테스트 카드 번호 사용
• 문서에서 테스트 정보 확인

Additional Resources

Reference Files

• references/v2-integration-details.md - V2 연동 상세 가이드
• references/webhook-patterns.md - 웹훅 처리 패턴

MCP Documentation

포트원 MCP 서버 도구를 통해 최신 문서와 API 스키마를 항상 조회할 수 있다. 코드 작성 전 반드시 예시 코드와 문서를 확인한다.