PG와 온라인 결제 (feat. 토스 페이먼츠)

Y·2025년 1월 2일

이번에 토스페이먼츠를 사용하여 온라인 결제를 연동하게 되었습니다.
따라서 온라인 결제 과정을 이해하기 위해서 정리해봅니다.
토스 페이먼츠 개발자 문서에 너무 잘 정리되어있어서 이를 참고하며 함께 정리하였습니다.

PG란?

우선 PG란 무엇인지 알아봅니다.
PG는 'Payment Gateway'의 줄임말로 '결제를 위한 관문'을 뜻합니다. 매장에 가면 결제를 위한 ‘계산대'가 있듯이, PG사는 온라인 쇼핑몰의 계산대 역할을 합니다.
PG사는 카드 결제, 간편결제, 계좌이체, 가상계좌(무통장입금), 상품권 결제, 휴대폰 결제 등 다양한 결제 방식을 사용할 수 있게 연결해주는 역할을 합니다. 온라인 결제를 대신해 주기 때문에 PG사는 결제대행사, '전자결제 지급대행사'라고도 부릅니다.

PG사는 온라인 사업자를 대신해 여러 곳의 결제 기관과 결제 데이터를 안정적으로 주고받고 매출 정산 서비스를 제공해줍니다. PG사 한곳과 계약하면 여러 카드사, 은행과 계약한 효과를 누릴 수 있습니다. 편리한 결제 서비스를 제공하는 PG사는 사업자의 매출의 일부를 수수료로 받습니다.

왜 PG사가 필요한가요?

PG사 없이는 직접 여러 카드사와 계약을 맺고, 결제를 관리하고, 정산 받는 업무를 관리하려면 큰 비용과 시간이 듭니다. 이런 번거로움을 해결하기 위해 PG사가 필요합니다. PG사와 한 번 계약을 맺으면 여러 카드사, 은행 등 금융기관과 간편하게 거래를 할 수 있고 약속된 정산일에 한 번에 매출액을 정산 받을 수 있습니다. 카드사마다 다른 매출액 지급일에 혼란을 없애고, 현금흐름을 쉽게 파악할 수 있게 해줍니다.

결제 흐름 이해하기

카드 결제 과정의 세 가지 핵심 단계인 요청, 인증, 승인을 이해하고 결제 정보를 검증하는 방법을 알아봅시다.

요청, 인증, 승인

1. 결제 요청

구매자:
주문서의 상품 정보, 결제 금액을 확인하고 '결제하기' 버튼을 클릭합니다.
Client:
'결제하기' 버튼의 클릭 이벤트로 토스페이먼츠 SDK의 결제 요청 메서드를 호출합니다.
결제 요청 메서드는 구매자가 선태간 결제수단의 결제창을 엽니다.

결제 요청 메서드의 파라미터로 주문번호(orderId), 성공 및 실패 URL(successUrl, failUrl)을 정의할 수 있습니다.

2. 구매자 정보 인증

구매자:
결제창에 카드 번호, 만료일, CVC 등의 결제 정보를 직접 입력하거나 앱 카드, 간편결제 앱으로 결제 정보를 불러옵니다.
카드사:
카드사는 구매자가 입력한 결제 정보를 확인하면서 구매자를 카드소유자로 인증 합니다. 인증 과정은 구매자와 상점을 보호하고, 부정거래나 사기 등을 방지하기 위해 꼭 필요합니다.

3. 인증 결과 확인

인증이 성공하면 구매자 입장에서는 모든 과정이 끝난 것처럼 보입니다. 하지만 개발자는 결제를 마무리하려면 아직 할 일이 남았습니다. 인증이 성공하면 토스페이먼츠에서 결제 기록을 생성하고, 결제 키(paymentKey)를 발급합니다. 결제 키는 각 결제에 고유한 값이고, 결제 인증이 끝나면 자동으로 발급됩니다.
그리고 토스페이먼츠에서 앱을 성공 url로 리다이렉트 합니다. 성공 url은 백엔드의 엔드포인트로 설정해도 되고, 프론트엔드 페이지로 설정해도 됩니다. 성공 url은 쿼리 파라미터에는 결제 키(paymentKey), 주문번호(orderId) 등의 결제 정보가 있습니다. 다음 단계에서 결제를 승인할 때 필요한 값입니다.

4. 결제 승인

Server:
인증된 결제를 승인해야 결제가 마무리됩니다. 성공 url의 쿼리 파라미터 값이 결제 요청에 보낸 값과 동일한지 확인하고, 결제 승인 API를 호출합니다.
카드사:
카드사는 결제 금액을 구매자의 카드 한도 또는 은행 계좌에서 차감합니다. 최종 결제 결과는 API 응답으로 확인할 수 있습니다. 실제로 결제 금액이 구매자의 결제수단에서 차감됐기 때문에 이제 상품 및 서비스를 구매자에게 제공해주세요.

paymentKey는 왜 필요한가요?

paymentKey는 각 결제를 식별하는 값입니다. 결제 인증이 완료되면 토스페이먼츠에서 고유한 paymentKey를 발급해서 성공 url의 쿼리파라미터로 내려줍니다. 결제 승인, 결제 취소, 결제 조회할 때 필요한 중요한 값입니다. 그렇기 때문에 결제 승인 이후에 응답 받는 Payment 객체에서 paymentKey는 반드시 데이터베이스에 저장해주세요. paymentKey는 외부에 노출되어도 괜찮습니다. 성공 url로 구매자에게 노출될 수도 있고요. 시크릿 키가 없다면 paymentKey로 아무런 API를 호출할 수 없기 때문입니다.

결제 정보 검증하기

토스페이먼츠를 사용할 때 요청과 승인 과정 사이에서 직접 결제 정보 검증을 구현하는 흐름입니다.

결제 요청 전에: 결제할 데이터 저장하기

구매자의 결제 정보는 결제 요청 전에 저장해야 합니다.
결제 요청 전후의 데이터가 바뀌지 않았는지(데이터 무결성) 확인하기 위함입니다.
또, 주문서 페이지에서 적립금이나 쿠폰을 적용했다면 최종 결제 금액을 서버에 저장하는 등의 작업도 필요합니다.
구매자에게 적립금이나 쿠폰이 없는데 요청과 승인 사이에 적립금을 사용한다고 악의적으로 결제 금액을 수정할 수 있기 때문입니다.
orderId(주문번호)와 amount(최종 결제 금액)을 클라이언트에서 서버로 보내 임시로 저장합니다.

구매자가 주문서에서 '결제하기' 버튼을 클릭해 결제를 요청합니다.
주문번호와 최종 결제 금액을 서버 세션이나 데이터베이스에 임시로 저장해주세요.
결제 정보가 잘 저장되었다면 결제를 요청하세요.

결제 승인 전에: 승인할 데이터 검증하기

결제 요청, 인증까지 성공했다면 승인 요청을 하기 전에 정보를 검증합니다.
앞서 요청할 때 저장해 둔 정보와 인증 결과로 돌아온 정보가 같은지 검증하는 과정입니다.
클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.

결제 인증이 완료되면 성공 URL에 들어온 값을 확인합니다. paymentKey, orderId, amount는 항상 돌아옵니다.
orderId로 결제 요청 전에 저장해 둔 임시 정보를 불러옵니다.
적립금 및 쿠폰을 사용할 수 있는지, 적립금과 쿠폰을 적용한 최종 결제 금액이 토스페이먼츠에서 돌아온 성공 리다이렉트 URL을 통해 받은 금액과 같은지 확인해보세요.
문제가 없다면 돌아온 데이터를 사용해서 결제 승인을 요청하세요.

[추가 설명]

리다이렉트 url로 결제정보를 받는 방법

리다이렉트 URL은 결제 요청 결과를 알려주고, 성공하거나 실패한 후에 사용자가 돌아갈 수 있는 웹사이트의 URL을 뜻합니다. 결제 연동 과정에서 요청 결과를 확인할 때 사용합니다.

결제 요청과 리다이렉트

결제를 요청할 때 가맹점 쇼핑몰의 URL 오리진을 포함한 성공, 실패 URL을 각각 successUrl 또는 failUrl의 값으로 설정합니다.
결제 요청을 하고 나면 토스페이먼츠에서 가맹점이 결제를 요청할 때 설정한 리다이렉트 URL로 이동시킵니다.
이동되는 리다이렉트 URL에는 요청 결과와 함께 관련 데이터가 쿼리 파라미터로 전달됩니다.
결제 요청에 성공했을 때는 결제 정보, 실패했을 때는 에러 정보가 전달됩니다.
결제 요청에 성공했다면 돌아온 값들로 결제 승인 API를 호출할 수 있고, 실패했다면 에러를 확인하고 문제를 해결해야 합니다. 이렇게 리다이렉트 URL은 결제 요청 결과를 알려주고, 그 결과로 결제 승인까지 할 수 있는 중간 역할을 하기 때문에 중요합니다.

리다이렉트 흐름

결제 요청에 성공했다고 가정하고 전체 흐름을 보겠습니다.

구매자가 주문서 페이지에서 결제에 필요한 정보를 입력합니다.
결제를 요청하면 주문서 페이지의 결제 정보가 PG사로 전송됩니다.
PG사는 카드사에 결제 정보에 대한 인증을 요청하고, 인증 결과를 받아 리다이렉트 URL 쿼리 파라미터로 포함한 뒤 이동시킵니다.
인증에 성공해서 성공 리다이렉트 URL로 이동했다면 URL에 포함된 파라미터를 사용해 결제 승인을 요청합니다.
결제 승인 결과를 확인합니다. 승인 요청에 성공했다면 돌아온 결제 정보를 저장하고 구매자를 성공 페이지로 이동시키세요. 실패했다면 에러 메시지를 확인하고 문제가 되는 부분을 수정해주세요.

3번과 4번 과정에 대해 자세히 설명하자면, 결제를 요청하면 차례로 인증과 승인 과정이 진행됩니다.
인증은 결제를 승인하기 전 결제 정보가 올바른지 검증하는 과정입니다.
승인은 인증에 성공한 결제를 최종 승인하는 과정입니다. 승인 요청에 성공하면 결제 요청 과정이 끝납니다.

이 인증과 승인 사이에 리다이렉트 과정이 있습니다.
두 단계로 나누어져 있는 결제 요청 과정에서 첫 번째 단계인 인증 결과를 받아 다음 단계로 넘어가기 위해 리다이렉트 URL이 필요합니다.
토스페이먼츠에서 요청된 결제의 인증 결과를 URL의 쿼리 파라미터에 담아 리다이렉트하면, 상점에서는 리다이렉트 URL을 통해 인증 결과를 확인할 수 있습니다.

인증에 성공했다면 성공 리다이렉트 URL(successUrl)에 쿼리 파라미터로 담긴 결제 정보를 이용해 승인 API를 호출합니다. 인증에 실패했다면 이동한 실패 리다이렉트 URL(failUrl)에 쿼리 파라미터로 담긴 에러 정보를 보며 디버깅합니다.

왜 이 방식을 사용하나요?

리다이렉트 URL 방식을 사용하는 이유는 몇 가지가 있습니다. 사용자가 결제를 완료하거나 결제가 실패한 후 원래 쇼핑 중이었던 앱이나 웹사이트로 돌아가면 사용자 경험이 향상됩니다. 사용자가 추가적인 조치를 취할 필요 없이 결제 상태를 쉽게 확인할 수도 있습니다.

PG에서는 사용자의 브라우저를 원래 사이트로 다시 이동시키면서 결제 결과(성공 또는 실패)에 대한 정보를 전달할 수 있습니다. 이 정보로 웹사이트는 결제 상태를 업데이트하고, 필요한 경우 사용자에게 추가 정보를 제공할 수 있어 편리한 방법입니다.

승인까지 마치려면 어떻게 해야 하나요?

인증 결과로 돌아온 결제 정보를 이용해 결제 승인 API를 호출하면 결제 요청 과정이 끝납니다. 10분 내에 결제 승인 API를 호출하지 않으면 결제가 취소되니 유의하세요.

리다이렉트 url 설정하는 방법

리다이렉트 URL은 어떤 URL로 설정해야 될까요? 클라이언트 페이지? 서버의 엔드포인트? 정답은 원하는 방식대로입니다. 가맹점 결제, 주문 시스템 및 기술 스택에 가장 적합한 방법을 선택하면 되는데요. successUrl을 다르게 설정할 수 있는 방법 세 가지를 알아보겠습니다.

방법1. 결제 성공 페이지

가장 직관적인 방법은 successUrl을 결제 완료 페이지로 설정하는 겁니다.
하지만 승인까지 끝나야 결제가 최종적으로 완료되죠. 클라이언트가 결제 완료 페이지에서 서버를 호출합니다.
서버에서 승인을 요청한 뒤에 데이터를 처리하고요.

승인이 완료되기 전까지 구매자에게 '결제 완료' 메시지가 보이지 않게끔 조건부 렌더링을 사용해주세요. 승인 요청이 성공하면 '결제 완료' 메시지를 구매자에게 보여주고, 만약 실패하면 '결제 실패' 메시지를 보여주던가 결제 실패 페이지로 리다이렉트 시켜주세요.

장점: 구현이 비교적 간단하기 때문에 관리 및 유지보수가 수월합니다.
단점: 구매자가 성공 페이지를 새로고침하면 다시 결제 승인이 호출되어 오류가 발생할 수 있습니다. 저장한 데이터로 결제 상태를 확인하거나, 멱등키를 활용해야 됩니다. ALREADY_PROCESSED_PAYMENT와 같이 중복 처리와 관련된 에러를 무시하는 로직을 추가할 수도 있습니다.

방법2. 로딩 페이지

조건부 렌더링이나 승인 중복 문제가 어렵게 느껴지면 successUrl을 결제 로딩 페이지로 설정하세요.

로딩 페이지에서 서버를 호출하고 결제 승인을 요청하세요.
승인 결과에 따라 클라이언트를 실패, 성공 페이지로 리다이렉트해주세요.
성공 페이지 방법보다 구현해야 되는 화면은 늘지만 결제 과정의 로직은 더 간단합니다.
구현 예시는 토스페이먼츠 개발자센터 샌드박스에서 확인할 수 있습니다. 다만 샌드박스는 결제 과정의 이해를 도우려고 수동으로 승인을 요청하고 있기 때문에 참고만 해주세요.

장점: 승인이 중복 호출될 위험이 없습니다. 구매자에게 결제 단계를 자세히 안내할 수 있습니다.
단점: 로딩 페이지, 리다이렉트 과정을 추가해야 됩니다.

방법3. 서버 엔드포인트

마지막 방법은 successUrl을 서버에 있는 엔드포인트로 설정하는 것입니다.

클라이언트를 거치지 않고 결제 요청이 성공하면 바로 서버 엔드포인트가 호출됩니다.
해당 서버 엔드포인트에서는 결제 승인 API를 호출하고 필요한 주문 및 결제 데이터를 처리합니다.
서버는 승인 결과에 따라 클라이언트를 결제 성공, 실패 페이지로 리다이렉트 시켜줍니다.

장점: 클라이언트에 새로운 페이지가 필요 없고 승인이 두 번 호출되는 위험도 없습니다.
단점: 승인을 호출하는 과정이 오래 걸리면 구매자는 같은 페이지를 계속 보고 있게 됩니다. 백엔드 로직이 복잡해집니다.

다음 포스팅에서는 토스페이먼츠의 테스트 키로 적용해보는 과정을 공유하겠습니다.

기록중

이전 포스트

react-hook-form 제대로 사용하기

다음 포스트