토스페이먼츠 시리즈 (1)

티스토리 뷰

프로젝트/토스페이먼츠 PG 연동 시리즈

토스페이먼츠 시리즈 (1) _ 도입

구름뭉치 2022. 3. 31. 15:19

결제 시스템 도입

https://onboarding.tosspayments.com/81403/integration?merchantAccountId=129226

토스페이먼츠 전자결제

onboarding.tosspayments.com

결제가 필요한 앱 서비스를 제작하게 되면서 결제 시스템을 도입해야 했다. KG이니시스, 다날 페이먼트, 토스 페이먼츠 등 다양한 결제 서비스를 제공하는 업체들이 존재한다. 수수료나 가입비들은 다 고만고만하니 더 쉽고 편하게 도입할 수 있는 업체를 고르기로 하였고 이에 토스 페이먼츠로 결정됐다.

홈페이지에 들어가서 전자결제 무료신청을 누르면 위와 같이 결제 서비스 신청하기 창이 뜬다. 그러면 사업자등록번호를 입력하라고 나오는데..! 아직 발급이 되지 않은 관계로 밑에 보이는 개발 테스트로 구현부터 먼저 해보도록 하겠다.

개발 테스트로 들어가면 API 키(클라이언트, 시크릿), 응답버전(1.3 선택), 가상계좌 입금 알림 URL, Webhook 콜백 URL 등을 사용할 수 있게 제공한다. 이를 이용해서 토스 페이먼츠에서 제공하는 API 테스트기와 연동해서 작업을 할 수 있다.

토스페이먼츠는 결제시스템을 연동하기 위해 필요한 자료들을 https://docs.tosspayments.com 에 자세하게 정리해놓았다. 이 문서를 참고해가면서 도입해보도록 한다.

결제 흐름

1. 결제 시 클릭하는 버튼

토스페이먼츠(이하 토스)에서 친절하게도 결제를 위한 SDK를 메서드를 통해 띄울수 있도록 제공하는데 이때 필요한 값들을 같이 넘겨주면 이제 결제는 나의 서비스와 관계없이 소비자와 결제시스템 간 통신으로 이뤄지게 된다.

토스에서 제공하는 코드를 HTML에 복붙 후 열어보자.

<html>
<head>
    <meta charset="utf-8">
    <script src="https://js.tosspayments.com/v1"></script>
</head>
<body>
<section>
    <!-- ... -->
    <span>총 주문금액</span>
    <span>35,000 원</span>
    <button id="payment-button">35,000원 결제하기</button>
</section>
<script>
    var clientKey = 'test_ck_클라이언트_키'
    var tossPayments = TossPayments(clientKey)
    var button = document.getElementById('payment-button') // 결제하기 버튼
    button.addEventListener('click', function () {
        tossPayments.requestPayment('카드', {
            amount: 35000,
            orderId: '서비스에서_정한_주문_고유번호',
            orderName: --상품명--
            customerName: --고객명--
            successUrl: 'http://localhost:8080/success',
            failUrl: 'http://localhost:8080/fail',
        })
    })
</script>
</body>
</html>

<script src="https://js.tosspayments.com/v1"></script>
- 토스 결제창을 띄우기 위해 넣어줘야 한다. 이제 requestPayment() 메서드를 이용해서 토스에서 제공하는 결제창을 띄울 수 있는 것이다.
<span>, <button>
- 해당 내용은 화면에 뜨는 내용으로 프론트 파트에서 맡게될 부분이다.
- 아래와 같이 나오게 된다.
clientKey : 토스페이먼츠에서 서비스제공자에게 정해준 클라이언트 키이다. 토스페이먼츠 입장에서는 가맹점이 클라이언트이므로 클라이언트 키라는 이름이 붙는 듯하다. 클라이언트를 구분해주는 용도로 사용되겠다.
orderId : 주문 고유 번호이다. 모든 주문마다 달라야 하겠다. 이 값은 서비스제공자 측에서 정해줘야 한다. (토스페이먼츠랑 관계 X)
<script>
- 스크립트를 통해 버튼을 클릭하면 함수가 실행되도록 하는 것이다. 이제 여기서 토스에서 제공하는 ClientKey 를TossPayments()에 넣어주고 결제 필요한 정보들 (가격, 주문 고유번호, 주문 이름, 주문자 이름, 성공 시 콜백 주소, 실패시 콜백 주소)과 함께 requestPayment() 메서드를 호출하도록 한다.
성공 시 콜백주소 : 여기서는 이제 서비스제공자가 성공 시 전달받은 값을 가지고 토스에게 최종 결제 승인 요청을 전송하게 된다. 이를 받아서 유효성이 검증되면 토스에서 최종적으로 결제 승인 요청이 되었다고 응답을 보내고, 이때 결제 관련한 정보들도 같이 전달해준다.
서비스 제공자는 이 값들을 이용해서 소비자들에게 결제 관련한 정보를 띄어줄 수 있는 것이다.
실패 시 콜백주소: 결제에 실패한 경우로 이 경우에도 서비스 제공자 측에서 소비자에게 결제가 모종의 이유로 실패했다고 알려주면 된다.

로직 테스트

1. 버튼 클릭

2. 결제 관련 동의 및 결제 수단 선택

위 사진을 보면 결제금액과 상품명이 처음에 작성한 HTML의 requestPayment()에 적은 내용과 동일한 것을 확인할 수 있다. 여기서 적은 값들을 같이 가지고 가서 진행되는 것이다.

3. 선택한 결제수단으로 결제

소비자가 결제수단을 선택하고 할부 등 내용들은 해당 결제 수단에서 처리하게 된다.

4. 결정된 결제수단이 이어서 결제 진행

이제 소비자가 결정한 결제수단에서 결제라인을 이이서 수행하게 된다. 앱결제를 선택하고 진행하였다.

5. 필자의 KB페이 앱으로 결제 진행

말그대로 자신이 선택한 결제수단에서 필요로하는 방법으로 결제를 이어서 진행하게 된다. 앱결제를 선택하면 QR코드가 뜨게 되고 이를 휴대폰에 존재하는 페이앱으로 찍어서 결제를 진행하게 된다.
일시불/할부 여부는 여기서 결정하게 된다.

위와 같이 결제창이 뜨게 되고 결제하기를 하면 소비자입장에서는 최종적으로 결제가 이뤄지게 된다. 이때 정지된 카드, 한도초과, 잔액부족 등 모종의 이유로 거부되면 실패 시 콜백 URL로 리다이렉트 될것이며 정상적으로 진행되면 성공 시 콜백 URL로 리다이렉트 될 것이다.

6. 최종 결제 승인 요청

다시 서비스 제공자 차례이다. 성공적으로 결제가 이뤄졌다면 등록해둔 성공 시 콜백 URL로 필요한 파라미터가 담겨서 리다이렉트 된다.

http://localhost:8080/success?orderId=서비스에서_정한_주문_고유번호&paymentKey=토스페이먼츠에서_정한_결제구분용_키&amount=35000

이런식으로 최초 결제 요청시 콜백주소 + 입력했던 주문 고유번호, 토스페이먼트에서 주문을 구분하는 paymentKey, 가격정보가 담겨서 온다. 이 값들을 가지고 다시 토스페이먼츠에게 최종 결제 승인 요청을 보내면 된다.
토스에서 이상이 없다면 승인을 하게 되고 상품 정보, 결제 정보 등 결제관련 모든 정보를 담아서 JSON으로 응답해준다.

토스에서 제공하는 응답 예시

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "토스페이먼츠에서_결제를_구분하는_키",
  "orderId": "서비스에서_정한_주문_고유번호",
  "orderName": "토스 티셔츠",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "status": "DONE",
  "requestedAt": "2021-01-01T10:01:30+09:00",
  "approvedAt": "2021-01-01T10:05:40+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_클라이언트_키/receipt/토스페이먼츠에서_결제를_구분하는_키"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "taxFreeAmount": 0
}

이제 어떤식으로 결제가 이뤄지는지, 필요한 부분이 무엇인지 알았으니 이를 토대로 나의 서비스에 적용해보도록 하자.

앞으로 개발할 목록 리스트

카드 결제 (토스페이먼츠)
카드 결제 취소 (토스페이먼츠)
계좌실명조회 (금융결제원)
가상계좌 결제 (토스페이먼츠)
가상계좌 결제 취소 (토스페이먼츠)

Reference

https://app.tosspayments.com

저작자표시 비영리 변경금지

'프로젝트 > 토스페이먼츠 PG 연동 시리즈' 카테고리의 다른 글

토스페이먼츠 시리즈 (6) _ 금융결제원 계좌실명조회 (8)	2022.04.20
토스페이먼츠 시리즈 (5) _ 카드 결제취소 (0)	2022.04.16
토스페이먼츠 시리즈 (4) _ 카드 결제 3 (3)	2022.04.12
토스페이먼츠 시리즈 (3) _ 카드 결제 2 (12)	2022.04.08
토스페이먼츠 시리즈 (2) _ 카드 결제 1 (24)	2022.04.04

공유하기 링크

Comments

Related Articles more

최근에 올라온 글

최근에 달린 댓글

TAG more

Total

Today

Yesterday

구름 개발일기장

티스토리 뷰