💳 토스페이먼츠 연동하기 (1) _결제 흐름

프로젝트를 진행하면서 결제 시스템을 도입해야 했는데,

우리는 좀 더 쉽고 편하게 도입할 수 있는 토스페이먼츠를 선택하였다.

토스페이먼츠는 결제 시스템 연동을 위해 필요한 자료들을 <요기>에 자세하게 안내해주고 있다.

이 문서들을 참고하여 연동해주면 되고,
이번 게시물에서는 적용 전 결제 흐름부터 살펴보려고 한다.

---

✏️ 토스페이먼츠 결제 흐름 ( 고객 입장 )

1. 결제 버튼 클릭

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

3. 선택한 결제 수단으로 결제
( 나의 경우 토스페이로 하였다. )

4. 선택된 결제 수단에서 이어서 결제 진행

➜ 휴대폰 번호와 생년월일 6자리를 입력하면 해당 휴대폰으로 아래와 같은 알림이 가게 된다.

5. 휴대폰의 토스 앱으로 결제 진행

➜ 위와 같이 결제창이 뜨고 동의하고 결제하기를 누르면 최종적으로 결제가 이루어지게 된다.
이 때, 여러 이유로 결제가 거부되면 실패 시 콜백 URL로 리다이렉트 되고,
결제가 정상적으로 진행되면 성공 시 콜백 URL로 필요한 파라미터가 담겨서 리다이렉트 된다.

6. 최종 결제 승인 요청

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}

• paymentKey = 토스페이먼츠에서 정한 결제 구분용 키
• orderId = 서비스에서 정한 주문 고유번호
• amount = 가격 정보

➜ 위와 같은 식으로, 최초 결제 요청 시 콜백 주소 + 위 세가지 정보가 담겨서 오고
이 값들을 가지고 다시 토스페이먼츠에게 최종 결제 승인 요청을 보내면 된다.
⠀
➜ 이 후, 토스페이먼츠에서 이상이 없다면 승인하고 상품 정보 / 결제 정보 등 결제 관련 정보들을 담아서 JSON으로 응답해준다.
( 아래는 토스에서 제공하는 응답 예시입니다. )

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "8uc3GNBacphSFe-EpgbvV", // 토스페이먼츠에서 결제를 구분하는 키
  "status": "DONE",
  "lastTransactionKey": "yEYX-9U5AAP7l0qbIFOF_",
  "orderId": "qJYf2biY9yBqKcr-21Y2G", // 서비스에서 정한 주문 고유 번호
  "orderName": "토스 티셔츠 외 2건",
  "requestedAt": "2022-06-08T15:40:09+09:00",
  "approvedAt": "2022-06-08T15:40:49+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12345678****789*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "amount": 15000
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/8uc3GNBacphSFe-EpgbvV/checkout"
  },
  "currency": "KRW",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0,
  "method": "카드"
}

7. 결제 완료

---

✏️ 토스페이먼츠 결제 흐름 ( 역할별 정리 )

결제 시에 위와 같은 흐름으로 요청/응답이 이루어지는데,
토스페이먼츠에서 발급해준 {클라이언트_키}를 가지고 TossPayments 객체를 초기화해주어야 한다.
이렇게 초기화된 객체로 requestPayment()를 실행하면 결제창 호출을 하게 된다.
⠀
( 🌼 자세한 내용은 다음 포스팅에서 다루고 있습니다! )

( 아래는 프론트 / 백엔드 / 토스페이먼츠 간의 역할별 결제 과정입니다. )

1. 프론트가 사용자가 입력한 정보를 가지고 [결제하기] 버튼을 통해 백엔드의 결제 요청 API를 호출

2. 백엔드가 해당 [요청 객체]를 가지고 검증 후 필요한 값들을 채워주고 DB에 결제 정보 저장 후 반환

3. 프론트가 반환받은 값을 가지고 이어서 tossPayments.requestPayment('카드',{결제 정보 파라미터})를 통해 토스페이먼츠에 [결제창 호출]을 하게 함

4. 결제창에서 구매자는 일련의 절차 후 최종적으로 결제 완료.
   이 후, 토스페이먼츠는 결제의 성공 여부 및 관련 파라미터를 콜백 주소로 리다이렉트

5. 백엔드는 성공/실패에 따라 적절한 Controller로 응답을 받음.
   성공적으로 결제가 이루어졌다면 백엔드에서 토스페이먼츠에게 [최종 결제 승인 요청]을 보냄.
   ( 이 때, 실패면 프론트에게 실패 정보를 함께 담아 반환하고 끝 )

6. 토스페이먼츠는 해당 요청을 검증하고 정상적이라면 백엔드에 반환.
   백엔드도 해당 데이터 확인 후 잘 포장해서 프론트에 반환

7. 프론트가 응답 데이터를 가지고 구매자에게 결제 결과 / 정보를 보여줌

---

여기까지 결제 흐름을 살펴보았으니, 이 후 포스팅에서는 이를 토대로 서비스에 적용해볼 예정이다 !

📌 다음 포스팅은 결제 요청에 대한 내용입니다.
⠀
👉 💳 토스페이먼츠 연동하기 (2) _결제 요청