안녕하세요, 결제 인프라 솔루션 ‘포트원’입니다.
PG사 결제 연동, 개발자라면 한 번쯤은 겪어봤을 도전 과제입니다. 서비스 성장의 핵심인 결제 시스템, 하지만 대부분의 개발자들은 런칭 직전 촉박한 일정에 쫓기며 결제 연동을 시작합니다. PG사마다 제각각인 연동 방식과 부실한 개발 문서를 마주하면서 허비하는 시간은 물론, 여러 PG사를 동시에 연동해야 하는 상황이라면 그 부담은 더욱 가중되죠.
포트원은 이러한 개발자들의 고충을 해결하기 위해 개발자센터를 전면 개편했습니다. 개발 문서들을 체계적으로 정리하고, 실제 코드와 결과를 실시간으로 확인할 수 있는 퀵 가이드를 도입했으며, SDK 문서를 더욱 직관적으로 개선했습니다.
포트원을 통해 단 한 번의 연동으로 다양한 PG사와 간편결제를 모두 커버할 수 있습니다. 개발자센터에서는 결제 연동에 필요한 모든 정보를 한눈에 확인하고, 실시간으로 테스트까지 가능해 런칭 일정에 대한 부담도 크게 줄일 수 있죠. 개발자의 시간과 리소스를 아끼면서도 안정적인 결제 시스템을 구축할 수 있도록, 포트원이 새롭게 준비한 개발자센터 2.0를 소개합니다.
주요 변화 요약
- 퀵 가이드 도입: 결제 연동 과정을 간소화하고, 개발 환경에 맞춘 실시간 가이드를 제공
- SDK 문서 개편: 자동 생성 문서와 직관적인 UI를 적용하여 개발 경험 개선
- 레이아웃 개선: 가독성과 접근성을 강화해 필요한 정보를 빠르게 찾을 수 있도록 구성
(1) 퀵 가이드 도입 – 한 페이지에서 끝내는 결제창 연동
결제 연동을 더욱 직관적이고 간편하게 진행할 수 있도록 퀵 가이드 기능을 새롭게 도입했습니다. 퀵 가이드는 문서와 코드를 한 페이지에서 동시에 확인할 수 있는 구조로 설계되어, 개발자들이 빠르고 효율적으로 결제 연동을 완료할 수 있도록 돕습니다.
퀵 가이드 주요 특징
- 모든 정보를 한 페이지에서 확인
- 기존처럼 문서와 코드가 분리된 방식이 아니라, 좌측에는 설명 문서, 우측에는 관련 코드가 표시되는 구조로 개편했습니다.
- 개발 환경에 맞춰 자동 변경
- 상단에서 결제 대행사, 결제 수단, 개발 언어를 선택하면 해당 설정에 맞춰 문서와 코드가 자동으로 변경됩니다.
- 실제 결제 테스트 가능
- 미리보기 기능을 통해 결제 테스트가 가능하도록 구현하여, 개발자가 코드 적용 후 예상 결과를 즉시 확인할 수 있습니다.
예제: 토스페이먼츠 / 카드결제 / React / Express 선택 시
- 문서에서는 토스페이먼츠 카드결제 연동 시 필요한 SDK 파라미터 설정 방법과 주의사항이 제공됩니다.
- Express 백엔드 연동을 위한 설치 방법과 코드 예제가 표시됩니다.
- 우측 코드 영역에서는 선택한 환경에 맞는 코드가 자동 표시되며, 이를 바로 복사하여 적용할 수 있습니다.
- 결제 버튼을 누르면 실제 결제창이 실행되며, 결제 테스트까지 즉시 진행할 수 있습니다.
원하는 정보를 클릭하면 코드를 자동 확인
문서 내 특정 항목을 클릭하면 우측 코드 영역에서 해당 코드가 자동 강조되어 보다 직관적인 개발 경험을 제공합니다.
결제 대행사 및 결제 수단 테스트 간소화
미리보기 영역에서는 상단에서 선택한 결제 대행사와 결제 수단을 직접 테스트할 수 있어, 다양한 환경에서 결제 연동을 빠르게 검증할 수 있습니다.
(2) SDK 가이드 개편 – 개발자 친화적 UI로 개발 효율 극대화
SDK 문서는 개발자들에게 필수적인 문서 중 하나입니다. 그러나 기존 문서는 Markdown 형식으로 작성되어 있어 코드 파라미터를 이해하는 데 어려움이 있었습니다. 이번 개편을 통해 더욱 직관적이고 개발자 친화적인 UI를 적용하여, 가독성과 사용성을 대폭 개선했습니다.
SDK 문서 개편 내용
- 개발자 친화적인 파라미터 디자인
- 기존 Markdown 형식 대신, 가독성을 높인 직관적인 UI를 도입했습니다. 파라미터 목록을 계층적으로 정리해 필요한 정보를 빠르게 찾을 수 있으며, Collapsible 기능을 추가해 불필요한 정보는 접어두고 필요한 부분만 확인할 수 있도록 개선했습니다.
- 자동 생성되는 파라미터 문서
- 실제로 사용해야 하는 파라미터의 타입과 문서에 기술된 파라미터의 타입이 다르거나 누락되어 있어 오류 발생 가능성이 높았습니다. 이제 SDK 문서가 자동으로 생성되어 실제 SDK와 일관된 정보를 제공하며, 오류를 최소화할 수 있습니다.
- 유형별 가이드 제공
- 예제 코드, 필수 및 선택 파라미터 구분, API 응답 형식 등을 더욱 명확하게 정리하여, 문서를 읽는 것만으로도 쉽게 이해할 수 있도록 개선했습니다.
개발자 친화적 파라미터 디자인
개발자들에게 익숙한 방식으로 SDK 파라미터를 직관적으로 보여주는 새로운 디자인을 도입했습니다. 기존에는 다른 개발자센터 문서들과 동일한 Typo 시스템을 사용했지만, Markdown 방식의 표현은 SDK 파라미터와 같은 코드 중심 문서를 설명하는 데 한계가 있었습니다.
새로운 디자인은 가독성을 높이고, 정보 밀도를 최적화했으며, Collapsible 기능을 추가해 필요한 부분만 선택적으로 확인할 수 있도록 개선되었습니다.
yaml 스키마를 통한 자동 문서 생성
- SDK와 동일한 데이터 기반으로 생성되어 정보의 정확성을 보장합니다.
- 중복된 설명을 줄이고, 깔끔하고 체계적인 문서 구조를 제공합니다.
PaymentResponse:
type: object
description: |
iframe/popup 방식으로 PG사 창이 렌더링 된 경우
프로세스 종료 후, 콜백 함수로 전달 될 결제 정보 데이터
properties:
transactionType:
type: stringLiteral
value: PAYMENT
description: |
**트랜잭션 유형**
- 일반결제의 경우 무조건 `PAYMENT`로 전달됩니다.
txId:
type: string
description: |
**결제 시도 고유 번호**
- 포트원에서 채번하는 결제 시도 고유 번호입니다.
paymentId:
type: string
description: |
**결제 ID**
- 결제 요청에 전달된 결제 ID입니다.기존에는 개발자가 문서를 직접 작성해야 해 필수 정보가 누락되거나 오류가 발생할 위험이 있었습니다. 이제 자동 생성된 문서가 실제 SDK의 타입을 그대로 반영하기 때문에, 이러한 문제를 근본적으로 해결할 수 있습니다.
호버 기능 구현
마우스를 올리면 해당 파라미터의 타입 정의를 즉시 확인할 수 있는 호버 기능이 추가되었습니다. 이를 통해 개발자들은 문서를 보다 빠르고 효율적으로 탐색할 수 있습니다.
(3)레이아웃 개편 – 가독성과 접근성 향상
기존 개발자센터는 원하는 정보를 찾기 어려운 구조였습니다. 이번 개편을 통해 디자인과 문서 구조를 전면 개선하여 개발자들이 더욱 빠르고 효율적으로 정보를 찾을 수 있도록 했습니다.
주요 변경 사항
- 가독성 향상 및 일관성 강화
- 불필요한 요소를 정리하고, 폰트 크기와 레이아웃을 최적화하여 정보를 더욱 명확하게 전달할 수 있도록 개선했습니다.
- 상단 내비게이션 확장
- 기존보다 넓은 2단 구성의 상단 바를 적용하여 주요 문서에 빠르게 접근할 수 있도록 했습니다. 첫 번째 줄에는 전반적인 카테고리를 배치하고, 두 번째 줄에서는 개발자가 자주 찾는 핵심 문서를 바로 확인할 수 있도록 구성했습니다.
- 검색 기능 강화
- 기존에는 특정 문서 내에서만 검색할 수 있었으나, 이제 개발자센터 전체에서 통합 검색이 가능하며, 어디서든 상단 바를 통해 원하는 정보를 빠르게 찾을 수 있습니다.
이번 개편을 통해 직관적인 문서 탐색이 가능해져 불필요한 클릭을 줄이고, 개발자 경험(DX)이 더욱 향상될 것입니다.
이제 포트원 개발자센터에서는 단 한 번의 연동만으로 여러 PG사와 간편결제를 모두 활용할 수 있습니다. 여러 PG사의 산재된 연동 방식을 하나로 통합하고, 실시간 테스트까지 가능하도록 구현해 압도적인 결제 연동 경험을 제공합니다.
비즈니스의 성장은 안정적인 결제 시스템에서 시작됩니다. 포트원은 개발자가 복잡한 결제 연동에 들이는 시간을 줄이고, 보다 가치 있는 개발에 집중할 수 있도록 지원하겠습니다. 지금 바로 새로워진 개발자센터에서 더 나은 결제 연동 경험을 시작해보세요.
개발자센터 2.0 둘러보기