결재 API sample

쉬운 목차

📃 요약

토스 결재 API 를 이용해서 쇼핑몰 결재 부분 샘플을 진행해 보도록 하겠습니다.
주문번호를 토스 결재 API 로 전달하고 토스 결재에서 결재 진행 후에 간략한 결과를 화면에 출력해 보겟습니다.

결재 진행후에 결재 테이블에 결재정보를 저장합니다.
단, 주문정보테이블에 주문상태(주문완료->결재완료) 변경이 필요하나 결재 API 활용방법에 집중하기 위해 생략하도록 하겠습니다.

프론트는 Vue 를 사용하고, 벡엔드는 spring boot 를 사용합니다.

DB 는 오라클 도커 이미지를 사용하고 계정은 scott ( 암호 : !Ds1234567890 ) 개발자 계정을 생성하고 사용합니다.
DB 개발자 계정 및 설치하는 방법은 생략합니다.

요소 기술 :

– 프론트엔드 : Vue

– 벡엔드 : 스프링부트 & JPA

– DB : Oracle 18xe(Docker)
( Oracle 18xe 도커 이미지 주소 : https://hub.docker.com/r/kangtaegyung/oraclexe-18c )

결과 화면 :

결재 버튼 화면

토스 결재 화면 #1 : 신용카드 선택

토스 결재 화면 #2 : 앱카드 결재

토스 결재 화면 #3 : 앱카드 결재 진행

토스 결재 완료 #4

결재 완료 후 결재 테이블에 저장됨

프로젝트 탐색기 : Vue

프로젝트 탐색기 : String Boot

벡엔드 Rest API 정보 :

메소드	URL	설명
POST	/api/shop/simple-approval	결재 저장

📃 기술 구현

스펙 :

- Vue 3.x
- toss 결재 API ( 참조 : https://github.com/tosspayments/payment-widget-sample )
- jdk 17
- spring boot 3.x
- intellij IDEA & gradle
- logging tool : logback

테이블 설계

-- Table , 시퀀스 등 구조 정의
DROP SEQUENCE SQ_SIMPLE_APPROVAL;
CREATE SEQUENCE SQ_SIMPLE_APPROVAL START WITH 1 INCREMENT BY 1;

DROP TABLE TB_SIMPLE_APPROVAL CASCADE CONSTRAINT;

-- 결재 정보 테이블
CREATE TABLE TB_SIMPLE_APPROVAL
(
    SANO            NUMBER NOT NULL PRIMARY KEY,       -- 결재번호(PK), 시퀀스
    APPROVAL_DATE   VARCHAR2(1000) ,                   -- 결재일자 : YYYY-MM-DD HH24:MI:SS
    APPROVAL_AMOUNT NUMBER NOT NULL
);

결재 API 구현을 위한 테이블 설계입니다.

데이터베이스를 오라클(Docker)을 사용하여 구현해 보겠습니다.

Spring build.gradle : dependencies 블럭 내 추가

dependencies {
    //    오라클 라이브러리( 19c )
    implementation 'com.oracle.database.jdbc:ucp:19.14.0.0'
    implementation 'com.oracle.database.security:oraclepki:19.14.0.0'
    implementation 'com.oracle.database.security:osdt_cert:19.14.0.0'
    implementation 'com.oracle.database.security:osdt_core:19.14.0.0'

    //    logback , log4jdbc 설정
    implementation 'org.bgee.log4jdbc-log4j2:log4jdbc-log4j2-jdbc4.1:1.16'
        ... 생략
}

결재 엔티티

– SimpleApproval.java

package com.example.simpledms.model.entity.shop;

import jakarta.persistence.*;
import lombok.*;
import org.hibernate.annotations.DynamicInsert;
import org.hibernate.annotations.DynamicUpdate;


/**
 * @fileName : SimpleApproval
 * @author : kangtaegyung
 * @since : 11/22/23
 * description : 결재
 */
@Entity
@Table(name = "TB_SIMPLE_APPROVAL")
@SequenceGenerator(
        name = "SQ_SIMPLE_APPROVAL_GENERATOR"
        , sequenceName = "SQ_SIMPLE_APPROVAL"
        , initialValue = 1
        , allocationSize = 1
)
@Getter
@Setter
@ToString
@Builder
@NoArgsConstructor
@AllArgsConstructor
@DynamicInsert
@DynamicUpdate
public class SimpleApproval {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE
            , generator = "SQ_SIMPLE_APPROVAL_GENERATOR"
    )
    private Integer sano;             // 결재번호, 기본키, 시퀀스
    private String  approvalDate;     // 결재일
    private Integer approvalAmount;   // 결재금액

}

결재 레포지토리

– SimpleApproval.java

package com.example.simpledms.repository.shop;

import com.example.simpledms.model.entity.shop.SimpleApproval;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

/**
 * @fileName : SimpleApprovalRepository
 * @author : kangtaegyung
 * @since : 11/22/23
 * description :  주문 레포지토리
 */
@Repository
public interface SimpleApprovalRepository extends JpaRepository<SimpleApproval, Integer> {
}

결재 서비스

– SimpleApprovalService.java

package com.example.simpledms.service.shop;

import com.example.simpledms.model.entity.shop.SimpleApproval;
import com.example.simpledms.repository.shop.SimpleApprovalRepository;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

/**
 * @fileName : SimpleApprovalService
 * @author : kangtaegyung
 * @since : 11/22/23
 * description :  결재 서비스
 */
@Service
@RequiredArgsConstructor
public class SimpleApprovalService {

    private final SimpleApprovalRepository simpleApprovalRepository;

    public void save(SimpleApproval simpleApproval) {
        simpleApprovalRepository.save(simpleApproval);
    }
}

결재 컨트롤러

– SimpleApprovalController.java

package com.example.simpledms.controller.shop;

import com.example.simpledms.model.entity.shop.SimpleApproval;
import com.example.simpledms.service.shop.SimpleApprovalService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
/**
 * @fileName : SimpleApprovalController
 * @author : kangtaegyung
 * @since : 11/22/23
 * description : 결재 컨트롤러
 */
@Slf4j
@RestController
@RequestMapping("/api/shop")
@RequiredArgsConstructor
public class SimpleApprovalController {

    private final SimpleApprovalService simpleApprovalService;

    @PostMapping("/simple-approval")
    public ResponseEntity<Object> create(@RequestBody SimpleApproval simpleApproval) {

            simpleApprovalService.save(simpleApproval);

            return new ResponseEntity<>(HttpStatus.OK);
    }
}

공통 Exception 클래스

– CommonExceptionAdvice.java

컨트롤러에서 어떤 에러가 발생하더라도 이 클래스의 internalServerErrorException 함수가 실행됨

package com.example.simpledms.exceptions;

import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * @author : kangtaegyung
 * @fileName : ExControllerAdvice
 * @since : 24. 5. 27.
 * description : 공통된 예외 처리 함수
 *  @ResponseStatus(HttpStatus.상태코드) : 상태코드가 발생하면
 *  @ExceptionHandler(Exception.class) : Exception 예외 클래스에 대해 처리한다.
 */
@Slf4j
@RestControllerAdvice
public class CommonExceptionAdvice {

//  컨트롤러에서 어떤 에러가 발생하더라도 이 함수가 실행됨
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> internalServerErrorException(Exception e) {
        log.debug("벡엔드 에러: " + e.getMessage());

        return new ResponseEntity<>("벡엔드 에러: " + e.getMessage()
                , HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

Vue 페이지

– Vue 패키지 추가 :

npm i @tosspayments/payment-widget-sdk
npm i axios

1) 공통 js

– utils/axiosDefaultConfig.js : axios 기본 설정 파일

import axios from "axios";

// axios 기본 설정
export default axios.create({
  baseURL: "http://localhost:8000/api",
  headers: {
    "Content-Type": "application/json"
  }
});

– services/shop/SimpleApprovalService.js

import axiosDefault from "@/utils/axiosDefaultConfig";

class SimpleApprovalService {

  create(data) {
    return axiosDefault.post("/shop/simple-approval", data);
  }
}

export default new SimpleApprovalService();

– router/index.js

import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  {
    path: "/",
    name: "home",
    component: () => import("../views/HomeView.vue"),
  },
  // 결재 버튼 메뉴
  {
    path: "/simple-order",
    name: "simple-order",
    component: () => import("@/views/shop/simple-product/SimpleOrderList.vue"),
  },
  // 토스 결재
  {
    path: '/toss-check/:sono',
    component: () => import('@/views/shop/toss/CheckoutView.vue')
  },
  {
    path: '/success',
    component: () => import('@/views/shop/toss/SuccessView.vue')
  },
  {
    path: '/fail',
    component: () => import('@/views/shop/toss/FailView.vue')
  }
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

export default router

토스 결재 API 함수 : 토스 결제 사이트에서 제공

– utils/confirmPayment.js

export async function confirmPayment(requestData) {
    // TODO: 개발자센터에 로그인해서 내 결제위젯 연동 키 > 시크릿 키를 입력하세요. 시크릿 키는 외부에 공개되면 안돼요.
    // @docs https://docs.tosspayments.com/reference/using-api/api-keys
    const secretKey = "test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6";

    // 토스페이먼츠 API는 시크릿 키를 사용자 ID로 사용하고, 비밀번호는 사용하지 않습니다.
    // 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.
    // @docs https://docs.tosspayments.com/reference/using-api/authorization#%EC%9D%B8%EC%A6%9D
    const encryptedSecretKey = btoa(secretKey+":")

    // ------ 결제 승인 API 호출 ------
    // @docs https://docs.tosspayments.com/guides/payment-widget/integration#3-결제-승인하기
    const response = await fetch("https://api.tosspayments.com/v1/payments/confirm", {
      method: "POST",
      headers: {
        "Authorization": `Basic ${encryptedSecretKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(requestData),
    });
    
    const json = await response.json();

    return { response, json };
}

Vue 페이지

결재 버튼 결과 화면 :

– views/shop/SimpleOrderList.vue

<template>
  <div>
    <!-- 결재 버튼 -->
    <div class="row d-flex justify-content-end">
      <button type="button" @click="goApproval" class="btn btn-warning w-25">
        Go Approval
      </button>
    </div>
  </div>
</template>
<script>
export default {
  data() {
    return {
      // 주문번호 샘플(6자리이상 : 토스 결재 API 필수자리수) : 주문번호는 고유한 값으로 테스트 할것
      sono: 222235
    }
  },
  methods: {
    // 토스 결재페이지로 이동
    goApproval() {
      this.$router.push("/toss-check/" + this.sono);
    },
  },
};
</script>
<style></style>

주문번호 : 고유한 값으로 테스트해야 정상 실행됨
결재 버튼을 클릭하면 토스 API 결재 페이지로 이동됨,
이동 시 주문번호가 웹브라우저 주소창으로 전달됨 : /toss-check/주문번호

토스 결재 화면 #1 :

– views/toss/CheckoutView.vue : 토스 API 사이트에서 제공

<template>
  <div class="wrapper">
    <div class="box_section">
      <!-- 결제 UI -->
      <div id="payment-method"></div>
      <!-- 이용약관 UI -->
      <div id="agreement"></div>
      <!-- 결제하기 버튼 -->
      <button
        :disabled="!inputEnabled"
        @click="requestPayment"
        class="button"
        id="payment-button"
        style="margin-top: 30px"
      >
        결제하기
      </button>
    </div>
  </div>
</template>

<script>
import { loadPaymentWidget, ANONYMOUS } from "@tosspayments/payment-widget-sdk";

export default {
  data() {
    return {
      paymentWidget: null,
      paymentMethodWidget: null,
      // TODO: clientKey는 개발자센터의 결제위젯 연동 키 > 클라이언트 키로 바꾸세요.
      // TODO: customerKey는 구매자와 1:1 관계로 무작위한 고유값을 생성하세요.
      clientKey: "test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm",
      customerKey: this.$route.params.sono,       // 주문번호(고유값, 개발자코딩)
      amount: 0,
      inputEnabled: false,
    };
  },
  methods: {
    // TODO: 토스 API 결재 
    async requestPayment() {
      try {
        if (this.paymentWidget) {
          // TODO: 결재 요청 임시 정보
          let data = {
            orderId: this.$route.params.sono,                // 주문번호(개발자코딩), 필수
            orderName: "테스트 이름",                           // 주문명(개발자코딩) 필수
            successUrl: `${window.location.origin}/success`, // 성공 url, 필수
            failUrl: `${window.location.origin}/fail`,       // 실패 url, 필수
          };
          console.log(data);
          // ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
          // 결제를 요청하기 전에 orderId, amount를 서버에 저장하세요.
          // 결제 과정에서 악의적으로 결제 금액이 바뀌는 것을 확인하는 용도입니다.
          // @docs https://docs.tosspayments.com/reference/widget-sdk#requestpayment결제-정보
          await this.paymentWidget.requestPayment(data);
        }
      } catch (error) {
        // 에러 처리하기
        console.error(error);
      }
    },
  },
  async mounted() {

    // TODO: 토스 API ------  결제위젯 초기화 ------
    // @docs https://docs.tosspayments.com/reference/widget-sdk#sdk-설치-및-초기화
    this.paymentWidget = await loadPaymentWidget(this.clientKey, ANONYMOUS);

    // TODO: 토스 API ------  결제 UI 렌더링 ------
    // @docs https://docs.tosspayments.com/reference/widget-sdk#renderpaymentmethods선택자-결제-금액-옵션
    this.paymentMethodWidget = this.paymentWidget.renderPaymentMethods(
      "#payment-method",
      { value: 13000 },                // 결재금액(개발자코딩)
      { variantKey: "DEFAULT" }
    );

    // TODO: 토스 API ------  이용약관 UI 렌더링 ------
    // @docs https://docs.tosspayments.com/reference/widget-sdk#renderagreement선택자-옵션
    this.paymentWidget.renderAgreement("#agreement", {
      variantKey: "AGREEMENT",
    });

    // TODO: 토스 API  
    this.paymentMethodWidget.on("ready", () => {
      this.inputEnabled = true;
    });
  },
};
</script>

<style>
@import "@/assets/css/style.css";
</style>

토스 API 사이트에서 제공하는 소스
개발자코딩 : 이 부분이 직접 개발자가 작성해서 응용하는 부분임
위에서는 주문번호, 주문명을 직접 개발자가 코딩했음

토스 결재 화면 #4

– views/toss/SuccessView.vue : 토스 API 사이트에서 제공

<template>
  <section v-if="confirmed">
    <div class="box_section" style="width: 600px">
      <img
        style="width: 100px"
        src="https://static.toss.im/illusts/check-blue-spot-ending-frame.png"
      />
      <h2>결제를 완료했어요</h2>

      <div class="p-grid typography--p" style="margin-top: 50px">
        <div class="p-grid-col text--left"><b>결제금액</b></div>
        <div class="p-grid-col text--right" id="amount">
          {{ jsonData.totalAmount }}원
        </div>
      </div>
      <div class="p-grid typography--p" style="margin-top: 10px">
        <div class="p-grid-col text--left"><b>주문번호</b></div>
        <div class="p-grid-col text--right" id="orderId">
          {{ jsonData.orderId }}
        </div>
      </div>
    </div>
  </section>
</template>

<script>
import { confirmPayment } from "@/utils/confirmPayment";
import SimpleApprovalService from '@/services/shop/SimpleApprovalService';

export default {
  data() {
    return {
      requestData: {
        orderId: this.$route.query.orderId, 
        amount: this.$route.query.amount, 
        paymentKey: this.$route.query.paymentKey, 
      },
      confirmed: false,
      jsonData: null,
    };
  },
  methods: {
    // TODO: 토스 결재 함수
    async confirm() {
      try {
        const { response, json } = await confirmPayment(this.requestData);
        console.log(json);
        if (!response.ok) {
          this.$router.push(`/fail?message=${json.message}&code=${json.code}`);
        } else {
          this.confirmed = true;
          this.jsonData = json;

          // 결재 저장 함수 실행(개발자코딩)
          this.confirmApproval()
        }
      } catch (e) {
        console.log(e);
      }
    },
    // 결재 저장 함수 정의(개발자코딩)
    async confirmApproval() {
      let now              = new Date();
      let yearMonthDay     = `${now.getFullYear()}-${now.getMonth()}-${now.getDate()}`;
      let hourMinuteSecond = `${now.getHours()}:${now.getMinutes()}:${now.getSeconds()}`;
      let dateFormat       = `${yearMonthDay} ${hourMinuteSecond}`;

      try {
        let approval = {
          sono: this.$route.query.orderId,          // 주문번호
          approvalDate: dateFormat,                 // 결재일
          approvalAmount: this.$route.query.amount, // 주문금액
        };
        let response = await SimpleApprovalService.create(approval);
        this.simpleApproval = response.data;
        
        console.log(response.data);
      } catch (e) {
        console.log(e);
      }
    },
  },
  mounted() {
    this.confirm();
  },
};
</script>

<style>
@import "@/assets/css/style.css";
</style>

개발자 코딩 : 이 부분이 직접 개발자가 작성해서 응용하는 부분임
위에서는 결재 저장 함수 정의했고(confirmApproval()), 결재 저장 함수를 실행했음

📃 결론

토스 결재 API 를 이용해서 Vue & Spring boot 로 연동하는 예제를 살펴보았습니다.
토스 결재 페이지가 로딩될때 주문번호를 웹브라우저 주소창으로 전달했으며,
토스 결재가 완료되면 결재 테이블에 Create 하는 기능도 구현했습니다..

Spring Boot 는 @RestController 어노테이션을 이용해 구현했으며, 결과는 JSON 데이터로 리턴됩니다.
Vue 는 axios 라이브러리를 사용해 벡엔드와 통신합니다.

DB 프레임워크는 JPA 를 이용해서 sql 문을 직접 제작하지 않고 자동화기능을 이용해 구현했습니다.
Mybatis 의 직접 sql 문 제작 기능에 대응해 자주 반복되고 쉬운 기능은 JPA 의 sql 자동생성 기능을 이용하고,
복잡한 sql 문은 @Query 를 이용해 직접 작성할 수 있어 요즘 서비스 업체 기준으로 많이 사용되고 있습니다.

결재 API 에 관심 있으시다면 Source 는 아래에서 찾을 수 있습니다.

Github 주소 : https://github.com/KangTaeGyung/simple-toss-api

감사합니다.