Next.js와 포트원을 이용한 결제 시스템을 구축하고자 한다. 이 부분에서 진행되는 흐름을 글로 작성하고자 한다. 이 글이 다른 사람들에게도 도움이 되면 좋을 것 같다. 참고로 테스트 용도이다. 실제 결제 시스템은 이것보다는 조금 더 복잡하긴 하다...
시작하기 전에..
시간이 흐름에 따라 나의 글은 "옛날 말"이 될 가능성이 있다. 버전의 차이. 혹은 Next.js의 업데이트 등등이 있을 것 같다. 이 점을 참고해 주길 바란다. 또한. 이 글은 조금씩 추가 및 수정 가능성이 포함되어 있다.
시작.
코드 샘플이 있어서 쉽다. 코드 샘플은 밑 링크를 참고하라.
https://github.com/portone-io/portone-sample/tree/main/nextjs
portone-sample/nextjs at main · portone-io/portone-sample
Contribute to portone-io/portone-sample development by creating an account on GitHub.
github.com
여기에 샘플 코드가 있어서, 일단 이 코드를 따라서 작성해 주면 대략적으로 코드를 알 수 있다.
버전은 v2를 사용하였다.
프로젝트 세팅
비주얼 스튜디오 코드를 열어서 다음 명령어를 세팅하라.
npx create-next-app@latest이후 다음 명령어가 나온다. 상황에 맞게 세팅하자.
What is your project named? portone
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to use Turbopack for `next dev`? No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*나는 테일윈드 css를 사용하지 않았다. 나머지는 전부 yes를 엔터 해주었다. 특히, 타입스크립트는 무조건 사용해 주자.
실행
이후 실행하고 싶다면 다음 명령어를 사용하라.
cd portone
npm run dev본인 프로젝트로 디렉토리를 변경하고 npm run dev를 작성해 주면 실행이 된다.
실행하고 다음 url로 접속한다. (브라우저에 url를 입력하거나, 에디터에 있는 링크를 열면 된다.)
> http://localhost:3000
폴더의 구조
폴더의 구조는 다음과 같다.
일단. app이 메인 폴더이다. public에는 당신이 팔고 싶은 "슈즈" 사진이 들어 있다. app에 있는 favicon.png는 우리 프로젝트의 favicon 이미지이다. lib 폴더 안에는 랜덤 한 수를 던지는 함수가 존재하며, ui 폴더 안에는 결제를 위한 form UI가 존재한다.
그것을 우리 메인 화면 page.tsx에 그려낼 것이고, layout.tsx는 모든 페이지에 영향을 준다. globals.css는 모든 css에 적용되는 css가 된다.
나머지 .env는 우리가 세팅할 환경변수이다.
주의 사항
주의할 것이 있다. 실제로 당신은 .env로 올리면 안되고, .env에 있는 환경변수 값을 복사한 이후, 당신의 프로젝트에 .env.local 파일을 만들고 이 파일 안에 삽입하라. 이래야 당신의 환경변수가 노출되지 않는다.
샘플 코드처럼 .env로 올려버리면 당신의 코딩 인생은 끝날 수 있으니 조심 또 조심하자.
이후 .gitignore나 .prettierrc는 딱히 안 건드려도 괜찮다. 나머지 env.d.ts는 인터페이스를 선언하는 파일이고, 나머지 파일들은 무엇인지 다들 알 것이다. 디테일한 건 샘플 코드를 보면 된다.
코드를 세팅하기 전에 설정할 명령어.
추후에 코드를 import를 할 것인데, 그전에 명령어 2개는 기본적으로 npm 설치해주어야 한다.
명령어는 다음과 같다.
npm i @portone/browser-sdk
npm install --save @portone/server-sdk처음 명령어는 브라우저 SDK을 설치하는 것. 두 번째 명령어는 서버 SDK 레퍼런스를 설치하는 것이다. 관련 링크 2개는 다음과 같다. 참고하자.
https://developers.portone.io/sdk/ko/v2-sdk/readme?v=v2
JavaScript SDK 레퍼런스
결제창 연동시 사용되는 SDK에 대한 설명 문서입니다.
developers.portone.io
https://developers.portone.io/sdk/ko/v2-server-sdk/readme?v=v2
서버 SDK 레퍼런스
웹훅 및 REST API 연동시 사용되는 SDK에 대한 설명 문서입니다.
developers.portone.io
이 2개를 깔아야 코드가 정상 작동한다.
두 개의 npm를 깔면 package.json에 다음과 같이 떠야 한다.
....
"dependencies": {
"@portone/browser-sdk": "^0.0.17",
"@portone/server-sdk": "^0.14.0",
"next": "15.3.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
....버전은 살짝 다르겠지만,
@portone/browser-sdk랑 @portone/server-sdk가 설치되어 있으면 오케이이다. (당신이 추가하고 싶은 기능이 있다면, 여기에 추가로 npm 버전이 기입될 것이다.)
시크릿 키
시크릿 키는 포트원에서 확인이 가능하다. 결제 연동 정보로 가면 채널 관리 및 식별코드/API 키가 있다. 여기에서 채널을 관리도 할 수 있고 키도 확인이 가능하다.
테스트로 나는 토스페이먼츠를 선택하였고, 일반결제로 선택했다. 이후 생성을 하였다.
상점 아이디는 콘솔 화면 보면 가장 최상단 오른쪽에 "상점 아이디"라고 있다. 이걸 키 값으로 넣어줘야 한다.
(이건 내 경험인데, MID를 상점 아이디 값으로 착각했다.... ㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋ 이 부분만 조심하면 될 듯하다. 나머지 값들은 헷갈릴 가능성이 없으니 걱정은 ㄴㄴ)
확인 이후에 .env.local에 기입하라.
API키는 절대로 외부로 노출시키지 말아라. (특히 시크릿)
(여기에 추가로 실결제에서는 사업자 등록증도 만들어야 한다.)
참고로 테스트에서는 따로 사업자 등록은 필요 없다. 그러나 실결제에서는 무조건 필요하고 PG사의 시스템 검사도 필요하다.
무조건 API키 까지 연동해야 작동 가능하다. 코드만 있어서는 작동이 안 됨! 이 부분 조심.
코드를 그대로 따라 한다면?
시크릿 키를 설정해 두었고, 코드를 그대로 따라 해서 작성해 두었다면, 제대로 작동될 것이다.
코드는 샘플코드에 전부 있으며 천천히 따라 하면 무조건 구현할 수 있다.
import 제대로하고, npm 라이브러리 2개 깔면 기본적인 테스트는 할 수 있다.
구현된 샘플 화면 >
테스트 결제이니 진짜로 결제는 안된다.
(결제 성공과 실패 둘 다 화면에 잘 뜸.)
'FE > Next.js' 카테고리의 다른 글
| Next.js에서 'use client'를 사용하는 경우 (0) | 2025.04.24 |
|---|---|
| Next.js에서 shadcn 사용하기 (0) | 2025.04.22 |
| Next.js의 Dynamic API 처리 (1) | 2025.04.06 |
| Next.js의 기존 프로젝트에서 ts 추가하는 법 (0) | 2025.03.28 |
| Next.js의 다이나믹 라우팅 (0) | 2025.03.22 |
