결제 연동 준비하기

결제 연동 방식에는 UI와 API를 사용하는 결제창 연동과 UI 없이 API만 연동하는 두 가지 방식이 있습니다.

결제창을 연동한다면 결제의 최종 단계에 API 호출 과정이 포함되어 있기 때문에 결제창 연동 준비, API 연동 준비 두 가지 모두 진행해야 합니다. API만으로 연동한다면 서버 호출과 응답만으로 결제가 완료되기 때문에 API 연동 준비만 하면 됩니다.

결제창 연동 준비

일반 결제 JavaScript SDK는 브라우저에서 결제창을 여는 기능을 제공합니다. SDK를 추가하고 초기화하는 과정을 알아보세요.

SDK 추가하기

스크립트로 추가하기

결제창을 연동할 HTML 페이지에 일반 결제 JavaScript 파일을 추가합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>
HTML

TossPayments 함수로 SDK 초기화를 진행해봅니다. 클라이언트 키를 TossPayments 함수에 넣고 실행하면 초기화 된 객체가 생성됩니다.

  • 클라이언트 키는 브라우저에서 결제창을 연동할 때 사용되는 키입니다.
// * 테스트용 클라이언트 키로 시작하세요
var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
var tossPayments = TossPayments(clientKey)
JavaScript

npm으로 추가하기(ES6+)

ES6+ 환경에서 개발하는 경우 npm 패키지로 SDK를 추가할 수 있습니다.

npm install @tosspayments/payment-sdk --save
yarn add @tosspayments/payment-sdk # yarn을 사용하는 경우

설치가 완료되면 package.json 파일에서 아래와 같이 SDK가 추가된 걸 확인할 수 있습니다.

{
"name": "payments-test",
"version": "1.0.0",
"description": "토스페이먼츠 테스트 프로젝트",
"main": "app.js",
"author": "김토페",
"dependencies": {
"@tosspayments/payment-sdk": "^1.0.0"
}
}
JSON

npm으로 설치했다면 먼저 SDK에서 loadTossPayments를 불러와야 합니다.

아래와 같이 loadTossPayments에 클라이언트 키를 넣고 실행하면 초기화된 객체가 생성됩니다.

import { loadTossPayments } from '@tosspayments/payment-sdk'
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
// async/await을 사용하는 경우
async function main() {
const tossPayments = await loadTossPayments(clientKey)
}
// Promise를 사용하는 경우
loadTossPayments(clientKey).then(tossPayments => {
// ...
})

초기화 단계를 마쳤다면 tossPayments 객체로 메서드를 실행할 수 있습니다. SDK에서 제공하는 메서드를 다음과 같이 호출해보세요. 브라우저에 결제창이 띄워지면 성공입니다.

// * 계좌이체 결제창 열기
tossPayments.requestPayment("계좌이체", { ... });
// * 카드 자동 결제 등록창 열기
tossPayments.requestBillingAuth("카드", { ... });

더 알아보기

결제 연동을 이어서 진행해 보세요

SDK를 자세히 알아보세요


API 연동 준비

API 키, 인증, 요청 프로토콜, 방화벽 설정을 준비합니다.

API 키

토스페이먼츠 API에 요청을 보내기 위해서는 API 키가 필요합니다. API 키를 통해 상점을 식별하고, 올바른 요청인지 판단할 수 있습니다.

가입된 계정이 없어도 아래 테스트용 API 키를 사용해서 요청을 보낼 수 있습니다.

test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R

API 요청에는 시크릿 키를 사용합니다. 토스페이먼츠 서버는 API 요청에 시크릿 키가 포함되어 있는지, 포함되어 있다면 올바른 시크릿 키인지 확인합니다. 시크릿 키는 브라우저에 노출되면 안 됩니다.

기본적으로 제공되는 테스트 키가 아닌 가맹점용 키를 사용해서 API 요청을 보내고 싶다면 토스페이먼츠에 가입해야 합니다.

자세한 내용은 내 상점의 API 키 발급받기에서 알아보세요.

인증(Authentication)

HTTP 요청 헤더에 Authorization 필드를 추가하고, 시크릿 키를 base64로 인코딩해서 값으로 넣습니다. 인코딩 된 시크릿키 앞에 'Basic'을 추가합니다.

Authorization:

Basic Authorization은 HTTP의 기본 인증 방식 중 하나로, username:password을 Base64로 인코딩해서 사용합니다. 토스페이먼츠 API는 username에 시크릿 키를 넣어 사용하고 password는 사용하지 않습니다.

요청 프로토콜 설정

토스페이먼츠 API 엔드포인트에 대한 모든 요청은 HTTPS 프로토콜을 따라야 합니다. Base64로 인코딩한 정보는 쉽게 디코딩이 가능하기 때문입니다. TLS(Transport Layer Security, 전송 계층 보안) 1.2 미만의 SSL/TLS 버전은 보안이 취약하기 때문에 TLS 버전 1.2 이상만 지원합니다.

방화벽 설정

방화벽은 외부의 신뢰할 수 없는 네트워크가 내부 네트워크에 접근하지 못하도록 하는 보안 시스템입니다. 토스페이먼츠 API에 요청을 보내려면 HTTPS로 접근할 수 있는 443 포트 허용이 필요합니다. 그 외에 가상계좌 웹훅 URL의 포트번호 허용, 접근 제어 목록에 토스페이먼츠 NAT IP 주소 허용 또한 필요합니다.

더 알아보기

더 자세한 내용은 API 사용하기 페이지에서 살펴볼 수 있습니다.

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기