결제창을 여는 모든 방법

by 토스페이먼츠

결제창은 고객이 결제 경험에서 처음 맞이하는 과정이죠. 결제를 구현하는 개발자가 길고 험난한 결제 연동 과정에서 처음 마주하는 난관이기도 해요.

토스페이먼츠 결제창은 고객에게도, 개발자에게도 최고의 경험을 주고 있어요. 이번 포스트에는 결제 연동을 처음하는 개발자에게 토스페이먼츠 결제창을 여는 모든 방법을 소개해요. 🤗

결제창이란?

온라인 쇼핑을 마치고 결제하기를 눌러요. 결제 수단을 선택하고, 결제 정보를 입력하는 창이 나와요. 이게 바로 결제창이에요.

위 이미지는 토스페이먼츠 결제창이에요. 고객이 직접 원하는 결제 수단을 선택할 수 있는 창이죠. 예를 들어 현대카드를 선택하면 할부, 이메일을 설정하는 화면이 나와요. 설정을 마치고 다음을 누르면 현대카드 결제창이 열려요. 현대카드 결제창에서 고객의 결제 여정이 이어지죠.

그럼 토스페이먼츠 SDK, API로 결제창을 여는 세 가지 방법을 알아볼게요.

방법 1. SDK 사용하기

토스페이먼츠 결제창은 일반 결제 SDK로 열 수 있어요. SDK로 결제창을 여는 방법은 3 단계로 나뉘어요.

  1. SDK를 설치해요.<script> 태그를 이용하거나 npm 패키지를 이용해서 일반 결제 SDK를 설치해요.
  2. SDK를 초기화해요. 초기화는 SDK를 사용하기 위한 설정 작업이에요. SDK 메서드를 사용할 수 있는 객체를 만들고, 클라이언트 키로 상점을 구분해요. 클라이언트 키는 아래 예시 코드에 있는 테스트 키를 사용해도 되고, 개발자센터에 가입해서 내 계정의 테스트 키를 이용할 수 있어요.
  3. requestPayment() 메서드를 호출해서 결제창을 열어요. 결제 수단, 결제 정보를 파라미터로 설정해요. 결제 수단을 카드로 설정하면 위 이미지와 같은 결제창이 열려요. 결제 정보는 결제 금액, 주문명 등 주문의 상세 정보가 있는 객체에요.

아래 예시 코드를 실행해 보세요.

<head>
  <title>결제하기</title>
  <script src="<https://js.tosspayments.com/v1/payment>"></script>
</head>
<script>
  var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 상점을 구분하는 키
  var tossPayments = TossPayments(clientKey) // SDK 초기화
	tossPayments.requestPayment('카드', {  // 결제 수단
	  amount: 15000, // 결제 정보
	  orderId: 'qkasYgYukbzCHRgwakVYZ',
	  orderName: '토스 티셔츠 외 2건',
	  customerName: '박토스',
	  successUrl: '<http://localhost:8080/success>',
	  failUrl: '<http://localhost:8080/fail>',
	})
</script>

결제창을 여는데 성공하셨나요? 그럼 이제 결제 수단 파라미터를 바꿔가면서 계좌이체, 휴대폰 결제창도 열어보세요. 각 결제 수단의 결제 정보 파라미터가 조금씩 달라요. 결제 수단에 맞는 가이드를 꼭 참고하세요.

✅ 카드 결제의 자세한 파라미터와 사용 방법은 결제창 연동하기를 참고하세요.

방법 2. API 사용하기

똑같은 토스페이먼츠 결제창을 결제 생성 API로도 열 수 있어요. API는 한 단계로 끝나요!

  1. 결제 생성 API를 호출해요. 인증 헤더를 설정해요. 아래 예시 코드에 있는 인증 헤더를 사용해도 되고, 개발자센터 계정의 시크릿 키를 인코딩해 사용할 수 있어요. 마지막으로 필수 파라미터를 데이터로 넣어요.

API가 성공적으로 호출됐다면 응답으로 결제 정보가 담긴 Payment 객체가 돌아와요. 이 객체의 checkout.url을 브라우저로 열면 토스페이먼츠 결제창이 나타나요.

아래 요청을 복사해서 실행해 보세요.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"method":"카드","amount":15000,"orderId":"qkasYgYukbzCHRgwakVYZ","orderName":"토스 티셔츠 외 2건", "successUrl":"http://localhost:8080/success", "failUrl": "http://localhost:8080/fail"}'

돌아온 응답에서 checkout.url 필드의 값을 브라우저로 열어봐요.

  {
    "mId": "tosspayments",
    "version": "2022-11-16",
    "checkout": {
        "url": "<https://api.tosspayments.com/v1/payments/0jPR7DvYpNk6bJXmgo28e1QkmPjlE8LAnGKWx4qMl91aEwB5/checkout>"
    }
		//...
}

API로 결제창을 여는 것도 성공하셨나요? SDK와 마찬가지로 결제 수단을 바꿔가면서 실험을 해보세요.

✅ 요청 파라미터는 결제 생성 API에서 확인할 수 있어요.

방법 3. 카드사, 간편결제사 결제창 바로 열기

앞에 나온 두 가지 방법은 토스페이먼츠 결제창을 열어요. 근데 내 상점의 주문서 페이지에서 직접 토스페이, 현대카드 결제창을 부르고 싶다면? 토스페이먼츠 결제창 대신 위 이미지에 있는 토스페이 결제창, 현대카드 결제창을 바로 열어야겠죠. 이것도 앞서 사용한 일반 결제 SDK, 결제 생성 API로 가능해요!

일반 결제 SDK requestPayment()의 결제 정보 객체에서, 결제 생성 API에서 아래 선택 파라미터를 사용하면 돼요.

  • flowMode · string 값을 넣지 않으면 토스페이먼츠 결제창이 열리지만, 값을 DIRECT로 설정하면 카드사, 간편결제사의 결제창이 바로 열려요. cardCompany, easyPay 파라미터 중 하나와 함께 사용해야 돼요.
  • cardCompany · string 카드사 결제창을 열려면 cardCompany에 원하는 카드사의 코드를 설정하세요.
  • easyPay · string 간편결제사 결제창을 열려면 easyPay에 원하는 간편결제사의 코드를 설정하세요.

조금 복잡한데요, 코드로 보면 더 쉬울 거예요.

현대카드 결제창을 바로 열 수 있는 일반 결제 SDK 코드에요.

<head>
  <title>결제하기</title>
  <script src="<https://js.tosspayments.com/v1/payment>"></script>
</head>
<script>
  var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 상점을 구분하는 키
  var tossPayments = TossPayments(clientKey) // SDK 초기화
	tossPayments.requestPayment('카드', {  // 결제 수단
	  amount: 15000, // 결제 정보
	  orderId: 'qkasYgYukbzCHRgwakVYZ',
	  orderName: '토스 티셔츠 외 2건',
	  customerName: '박토스',
	  successUrl: '<http://localhost:8080/success>',
	  failUrl: '<http://localhost:8080/fail>',
      flowMode: 'DIRECT',
      cardCompany: '현대'
	})
</script>

토스페이 결제창을 바로 열 수 있는 결제 생성 API 코드에요.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"flowMode":"DIRECT", "easyPay":"토스페이", "method":"카드","amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건", "successUrl":"http://localhost:8080/success", "failUrl": "http://localhost:8080/fail"}'

✅ 카드사, 간편결제사 파라미터에 숫자, 한글, 영문 기관 코드를 사용할 수 있어요.

이게 끝은 아니죠

축하드려요! 🎉 결제창을 세 가지 방법으로 열어봤어요. 근데 결제창은 시작일 뿐이에요. 결제를 끝까지 마무리하고 싶다면 결제창 연동하기 가이드를 따라 해보세요. 어려움이 있다면 디스코드로 1:1 문의를 해보세요.

📍 함께 읽으면 좋을 콘텐츠

Writer 박수연 Graphic 이은호, 이나눔

ⓒ토스페이먼츠, 무단 전재 및 배포 금지

의견 남기기
토스페이먼츠

고객사의 성장이 곧 우리의 성장이라는 확신을 가지고 더 나은 결제 경험을 만듭니다. 결제가 불편한 순간을 기록하고 바꿔갈게요.