결제 연동
목차

결제창은 이전 버전 제품으로 사용을 권장하지 않아요. 새로운 버전의 결제위젯을 사용해주세요.


퀵계좌이체란?

계좌이체는 결제 수수료가 저렴하지만 고객이 결제를 할 때 불편하다는 단점이 있어요. 보안프로그램・계좌이체 앱도 설치해야 하고, 계좌 등록을 위해 회원가입도 해야 해요. 보안카드나 OTP처럼 평소 잘 들고 다니지 않는 인증수단으로 인증절차를 마쳐야 하는 불편함도 있고요.

토스페이먼츠 ‘퀵계좌이체'는 앱설치나 공동인증서가 없어도 간편결제처럼 한 번만 계좌등록을 해두면 비밀번호만 입력하고 쉽게 결제를 마칠 수 있는 계좌이체 서비스예요.

토스페이먼츠 SDK로 연동하기

XPAY로 연동하기

API 키 준비하기

결제창은 API 개별 연동 키로 연동하세요.

토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 연동할 수 있어요. 토스페이먼츠에 회원가입했다면, 로그인 후 다음 내 테스트 키로 결제를 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

JavaScript
// API 개별 테스트 연동 키
// 토스페이먼츠에 회원 가입하기 전이라면 아래 키는 문서 테스트 키입니다.
// 토스페이먼츠에 회원 가입하고 로그인한 상태라면 아래 키는 내 테스트 키입니다.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

1. 결제창 띄우기

아래 예제 코드를 실행하면 다음과 같은 퀵계좌이체창을 띄울 수 있습니다. 실제로 결제되지 않으니 안심하세요.

퀵계좌이체 예시 이미지

<head>
<meta charset="utf-8" />
<title>결제하기</title>
<!-- 토스페이먼츠 결제창 SDK 추가 -->
<script src="https://js.tosspayments.com/v1/payment"></script>
</head>
<body>
<script> // ------ 클라이언트 키로 객체 초기화 ------ var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' var tossPayments = TossPayments(clientKey) // ------ 결제창 띄우기 ------ tossPayments .requestPayment('계좌이체', { // 결제수단 파라미터 // 결제 정보 파라미터 // 더 많은 결제 정보 파라미터는 결제창 Javascript SDK에서 확인하세요. // https://docs.tosspayments.com/reference/js-sdk amount: 5000, // 결제 금액 orderId: '', // 주문 ID(주문 ID는 상점에서 직접 만들어주세요.) orderName: '테스트 결제', // 주문명 customerName: '김토스', // 구매자 이름 customerMobilePhone: '01012345678', // 퀵계좌이체창에서 고객의 휴대폰 번호를 자동 완성합니다. customerEmail: 'customer@email.com', successUrl: 'https://docs.tosspayments.com/guides/payment/test-success', // 결제 성공 시 이동할 페이지(이 주소는 예시입니다. 상점에서 직접 만들어주세요.) failUrl: 'https://docs.tosspayments.com/guides/payment/test-fail', // 결제 실패 시 이동할 페이지(이 주소는 예시입니다. 상점에서 직접 만들어주세요.) }) // ------결제창을 띄울 수 없는 에러 처리 ------ // 메서드 실행에 실패해서 reject 된 에러를 처리하는 블록입니다. // 결제창에서 발생할 수 있는 에러를 확인하세요. // https://docs.tosspayments.com/reference/error-codes#결제창공통-sdk-에러 .catch(function (error) { if (error.code === 'USER_CANCEL') { // 결제 고객이 결제창을 닫았을 때 에러 처리 } else if (error.code === 'INVALID_CARD_COMPANY') { // 유효하지 않은 카드 코드에 대한 에러 처리 } }) </script>
</body>

SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다. 초기화된 객체로 requestPayment()를 실행하면 결제창이 뜹니다.

requestPayment() 이해하기

결제창을 띄울 수 있는 메서드에요. 결제창을 띄우려면 파라미터에 결제수단, 결제 정보를 입력해야 해요.

1️⃣ 결제수단을 첫 번째 파라미터로 추가하세요. 퀵계좌이체는 계좌이체을 사용하세요.

2️⃣ 결제 정보는 두 번째 파라미터로 추가하세요. 모든 결제수단에서 사용하는 공통 파라미터와 결제수단에 따라 달라지는 선택 파라미터가 있습니다. 각 결제수단별 선택 파라미터는 SDK 레퍼런스를 참고하세요.

2. 결제 요청 결과 확인하기

결제 요청이 성공하면 결제창을 열 때 설정한 결제 성공 페이지(successUrl)로 이동합니다.

결제 성공 페이지의 URL에는 paymentKey, orderId, amount 세 가지 쿼리 파라미터가 들어있습니다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
  • paymentKey: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
  • orderId: 주문 ID입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
  • amount: 실제로 결제된 금액입니다.

* 결제 요청이 실패하면 결제창을 열 때 설정한 결제 실패 페이지(failUrl)로 이동합니다. 결제 실패 URL을 살펴보세요.

requestPayment() 메서드에 담아 보낸 결제 금액과 successUrl로 돌아온 amount 값이 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.

만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

3. 결제 승인하기

결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.

시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')
─────────────────┬───────────────── ┬
secretKey :
발급받은 시크릿 키 콜론

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:' | base64

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.

요청
curl --request POST \
--url https://api.tosspayments.com/v1/payments/confirm \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"{PAYMENT_KEY}","amount":5000,"orderId":"CLhz6njJufjoGs8oZTrCS"}'

성공 페이지로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출해야 합니다. 10분이 지나면 결제가 만료되어 결제 승인을 할 수 없습니다.

4. 결제 완료 후 응답 확인하기

API 호출 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 결제 완료입니다.

응답
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": {
"bankCode": "92",
"settlementStatus": "COMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": {
"type": "소득공제",
"receiptKey": "PoxJmeD4pZORzdMaqN3w96ax29XKJqr5AkYXQGwyEb21W9v7",
"issueNumber": "158251926",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/kup08l0xV6Ay21zGLXQhUcN/tvivarepublica?ref=PX",
"amount": 5000,
"taxFreeAmount": 0
},
"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//checkout"
},
"currency": "KRW",
"totalAmount": 5000,
"balanceAmount": 5000,
"suppliedAmount": 4545,
"vat": 455,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"method": "계좌이체"
}

✅ 응답 객체에 transfer 필드가 있는지 확인하세요.

✅ 응답 객체의 method계좌이체인지 확인하세요.

🙋 응답 객체에 원하는 필드가 없어요.

응답 객체의 필드는 API 버전에 따라 조금씩 달라집니다. 개발자센터에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요.

API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기