웹사이트 결제 연동은 결제 서비스 가입·전자결제 신청, 테스트 키로 연동, 결제 요청·인증·승인 구현, 라이브 키로 전환하는 순서로 진행합니다. 2026년 10월 21일 토스페이먼츠와 포트원 공식 개발자 문서를 직접 읽고, 단계마다 어느 문서에 적힌 내용인지 밝혀 정리했습니다.
결제 연동은 내 사이트의 「결제하기」 버튼을 PG(전자지급결제대행)사의 결제창과 잇는 작업입니다. 개발을 맡기는 사장님도 이 순서를 알아 두면 진행 상황을 묻기 쉽습니다.
1. 결제 연동, 웹사이트에 붙이는 순서는?
가입과 신청이 먼저입니다. 포트원 「결제 연동 준비하기」 문서는 연동 개발이 처음이면 이 네 단계를 따르라고 안내합니다.
- 포트원 회원가입 하기
- 전자결제 신청하기(사업자 정보 등록 후 결제대행사·결제수단 신청)
- 결제대행사 채널 설정하기(테스트 또는 실연동)
- 포트원 연동정보 확인하기(상점 아이디, V2 API Secret)
포트원 문서는 KG이니시스, NHN KCP, 토스페이먼츠 등 여러 결제대행사 가운데 골라 연동하는 방법을 안내합니다. 토스페이먼츠처럼 PG사와 바로 연동한다면, 토스페이먼츠 시작하기 문서가 연동 전에 내 업종이 입점 불가 업종이거나 제한 업종인지 확인하라고 적어 두었습니다.
2. 테스트 키로 먼저 연동합니다
토스페이먼츠는 라이브 환경과 비슷한 테스트 환경을 제공합니다. 환경 설정 문서에 따르면 테스트 환경에서는 실제 카드 번호를 넣어도 결제가 가상으로 승인되고, 돈이 출금되지 않습니다.
키 이름으로 구분합니다. 배포 체크리스트 문서는 라이브 키 앞에 live_, 테스트 키 앞에 test_가 붙는다고 적었습니다.
테스트 결제 내역은 개발자센터의 테스트 결제내역 메뉴에서, 라이브 결제 내역은 상점관리자에서 봅니다. 포트원은 전자결제 신청 전이라도 연동 모드를 「테스트」로 두고 채널을 추가해 시험할 수 있다고 안내합니다.
테스트 환경이 라이브와 다르게 움직이는 곳도 있습니다. 예를 들어 페이코는 테스트 키로 연동할 수 없어 라이브 키로 테스트하라고 문서에 적혀 있습니다.
3. 결제는 요청·인증·승인 세 단계로 이뤄집니다
토스페이먼츠 「결제 흐름 이해하기」 문서는 온라인 결제를 요청·인증·승인 세 단계로 설명합니다.
- 결제 요청: 구매자가 「결제하기」를 누르면 SDK의 결제 요청 메서드가 결제창을 엽니다
- 구매자 정보 인증: 카드사가 구매자를 카드 소유자로 인증합니다
- 인증 결과 확인: 결제 키(
paymentKey)가 발급되고 성공 URL로 돌아옵니다 - 결제 승인: 서버가 결제 승인 API를 호출해 결제를 마무리합니다
구매자 화면에서는 인증이 끝나면 결제가 끝난 것처럼 보이지만, 서버가 승인 API를 호출해야 결제가 마무리됩니다.
같은 문서는 금액 조작을 막기 위해 결제 요청 전에 주문번호와 최종 결제 금액을 서버에 저장하고, 승인 전에 돌아온 값과 같은지 확인하라고 권합니다.
4. 시크릿 키는 서버에만 둡니다
결제 연동에는 브라우저에서 쓰는 값과 서버에서만 쓰는 값이 있습니다. 포트원 문서는 V2 API Secret을 이렇게 설명합니다.
API Secret은 결제 거래 건을 컨트롤할 수 있는 민감 정보로 고객사 서버에서만 사용되어야 하며, 브라우저 등 외부에 노출되어서는 안 됩니다.
포트원 API Secret은 발급 직후에만 값을 볼 수 있어, 잊어버리면 새로 발급해야 합니다. 토스페이먼츠 배포 체크리스트도 시크릿 키가 코드 저장소 등 외부에 노출되지 않게 주의하라고 적었습니다.
5. 라이브 전환 전에 확인할 것
토스페이먼츠 배포 체크리스트는 연동을 마친 뒤 라이브 환경에서 쓸 준비가 됐는지 확인하는 문서입니다. 핵심만 옮기면 이렇습니다.
- 코드에 넣은 키가 내 상점의 라이브 키인지
- 카드사 심사·이동 통신사 심사 등 결제수단 심사를 통과했는지
- 결제창 실행부터 결제 완료까지 흐름 전체가 동작하는지
- 취소와 부분 취소가 모두 잘 동작하는지
- 지원하는 데스크톱 브라우저와 Android·iOS에서 각각 동작하는지
카드 결제를 열려면 카드사 심사를 통과해야 하므로, 개발 일정과 별도로 심사 기간을 잡아 두는 것이 안전합니다. 문서는 카드사 심사를 각 카드사가 판매 방식을 확인하고 카드 결제를 허용하는 과정이라고 설명합니다.
이 블로그를 운영하는 AiApp에서는 백엔드 기능에 결제가 들어 있어, 카카오페이·네이버페이·토스 같은 국내 결제와 신용카드·계좌이체·간편결제를 사이트에 붙일 수 있습니다. 문자·카카오 알림톡도 서비스 안에서 보낼 수 있고, 요금은 요금제 페이지에 있습니다.
6. 결제 연동 순서 한눈에 정리
- 결제 서비스에 가입하고 전자결제(PG 계약)를 신청합니다
- 테스트 키(
test_)나 테스트 채널로 결제창을 연동합니다 - 요청·인증·승인을 구현하고 승인 전 금액을 검증합니다
- 시크릿 키는 서버에만 두고 외부에 노출하지 않습니다
- 결제수단 심사와 배포 체크리스트를 마친 뒤 라이브 키(
live_)로 바꿉니다
토스페이먼츠의 결제수단별 수수료는 토스페이먼츠 수수료, 결제수단별 정리에, 해외 결제 서비스 Stripe를 한국 사업자가 쓸 수 있는지는 stripe 결제 연동, 한국 사업자도 될까?에 정리했습니다. 쇼핑몰 비용 전체는 쇼핑몰 제작 비용, 항목별 총정리를 참고하세요.
참고자료 (모두 2026년 10월 21일 확인)
- 포트원 개발자센터 「결제 연동 준비하기」 — developers.portone.io/opi/ko/integration/ready/readme
- 토스페이먼츠 개발자센터 「시작하기」 — docs.tosspayments.com/guides/v2/get-started
- 토스페이먼츠 개발자센터 「환경 설정하기」 — docs.tosspayments.com/guides/v2/get-started/environment
- 토스페이먼츠 개발자센터 「결제 흐름 이해하기」 — docs.tosspayments.com/guides/v2/get-started/payment-flow
- 토스페이먼츠 개발자센터 「배포 체크리스트」 — docs.tosspayments.com/guides/v2/deploy-checklist
#결제연동 #PG연동 #토스페이먼츠 #포트원 #쇼핑몰만들기
