Version 1

가상계좌 결제창 연동하기

결제창 SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.

✅ 토스페이먼츠 가상계좌 결제창에서 가상계좌를 발급받고, 입금 결과를 웹훅으로 받을 수 있어요.

샘플 프로젝트결제창 연동 샘플 프로젝트입니다.

결제창 SDK 레퍼런스JavaScript SDK 스펙을 더 자세히 알아보세요.

더욱 매끄럽고 쉬운 결제 경험을 제공하고 싶다면 결제위젯을 추천드려요.

어떤 은행에서 가상계좌를 발급받을 수 있나요?

경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, iM뱅크(대구), 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 하나은행에서 가상계좌를 발급받을 수 있습니다.

구매자 이름과 입금명이 같아야 되나요?

아니요. 결제 금액만 정확히 입금된다면 구매자와 입금명이 달라도 결제는 정상적으로 처리됩니다.

현금영수증은 언제 발급되나요?

현금영수증은 구매자가 가상계좌에 입금한 뒤에 발급됩니다. 입금 전에는 현금영수증을 확인할 수 없습니다.

API 키 준비하기

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

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

// 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/sdk/payment-js
        amount: 15000,
        orderId: '', // 주문번호(주문번호는 상점에서 직접 만들어주세요.)
        orderName: "토스 티셔츠 외 2건",
        customerName: "박토스",
        successUrl: "http://localhost:8080/success", // 결제 성공 시 이동할 페이지(이 주소는 예시입니다. 상점에서 직접 만들어주세요.)
        failUrl: "http://localhost:8080/fail", // 결제 실패 시 이동할 페이지(이 주소는 예시입니다. 상점에서 직접 만들어주세요.)
        validHours: 24, // 입금 기한
        cashReceipt: {
          // 현금영수증 발행
          type: "소득공제",
        },
      })
      // ------ 결제창을 띄울 수 없는 에러 처리 ------
      // 메서드 실행에 실패해서 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>

더 많은 가상계좌 결제 정보 파라미터는 결제창 Javascript SDK에서 확인하세요.

가상계좌 입금 기한 설정하기

가상계좌 입금 기한의 기본 값은 발급 시점으로부터 7일입니다. 입금 기한을 바꾸려면 validHours, dueDate 선택 파라미터를 사용하세요. 설정할 수 있는 최대 기한은 발급 시점으로부터 30일입니다. 입금 기한을 넘기면 발급된 가상계좌는 더 이상 사용할 수 없습니다.

두 파라미터 중 하나만 선택해서 사용해야 합니다. 두 파라미터는 사용 기한을 발급 시점으로부터 상대적으로 설정할 지, 특정 시점으로 설정할 지에 차이가 있습니다. 예를 들어 가상계좌 입금 기한을 발급시점부터 하루로 설정하고 싶다면, 위와 같이 validHours 파라미터를 24로 설정하세요.

입금 기한 설정 파라미터

validHours number
가상계좌가 유효한 시점을 시간 단위로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, validHours를 120으로 설정하면 발급 후 120시간 뒤인 2022년 1월 5일 오전 1시 전까지 입금되어야 합니다.
dueDate number
입금 기한을 특정 시점으로 설정할 때 사용합니다. 예를 들어 가상계좌 발급 시점이 2022년 1월 1일 오전 1시(2022-01-01T01:00:00+09:00)이고, dueDate를 2022-01-10T01:00:00로 설정하면 2022년 1월 10일 오전 1시 전까지 입금되어야 합니다.

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

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

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

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

paymentKey: 결제의 키값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
orderId: 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.
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":15000,"orderId":"z8LXgPqX9r6y5Yn6g3mwi"}'

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

4. 가상계좌 정보 확인하기

API 호출 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 가상계좌 발급 완료입니다. 응답에서 virtualAccount 필드를 확인하세요. 가상계좌의 계좌번호, 은행, 입금기한 등 정보를 구매자에게 안내해주세요.

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "",
  "status": "WAITING_FOR_DEPOSIT",
  "lastTransactionKey": "12FC03A573C88BC945E0B5F2D0D2A2A3",
  "orderId": "",
  "orderName": "토스 티셔츠 외 2건",
  "requestedAt": "2022-06-08T15:40:09+09:00",
  "approvedAt": null,
  "useEscrow": false,
  "cultureExpense": false,
  "card": null,
  "virtualAccount": {
    "accountNumber": "X6505636518308",
    "accountType": "일반",
    "bankCode": "20",
    "customerName": "박토스",
    "dueDate": "2022-06-09T15:40:09+09:00",
    "expired": false,
    "settlementStatus": "INCOMPLETED",
    "refundStatus": "NONE",
    "refundReceiveAccount": null
  },
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": {
    "type": "소득공제",
    "receiptKey": "kWzn16mywdYPBal2vxj81P72xv2m2r5RQgOAND7pJe9KE0qL",
    "issueNumber": "",
    "receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/ewsXcAG7jJztpS7pi59ZJ/tosspayments?ref=PX",
    "amount": 15000,
    "taxFreeAmount": 0
  },
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": "",
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments//checkout"
  },
  "currency": "KRW",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "metadata": null,
  "taxExemptionAmount": 0,
  "method": "가상계좌"
}

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

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

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

5. 입금하고 결제 완료하기 🛎

가상계좌 결제는 발급된 계좌에 구매자가 입금한 시점에 결제가 됩니다. 직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 등록된 웹훅 URL로 알림이 발송됩니다.

테스트 입금하기

테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 칼럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.

입금 확인하기

개발자센터의 웹훅 페이지에서 DEPOSIT_CALLBACK 웹훅을 등록하세요.
입금이 완료되면 결제 상태가 DONE으로 바뀌고 아래와 같은 이벤트 본문이 등록한 웹훅 URL로 전송됩니다.
이벤트 본문의 secret 값이 결제 승인 응답으로 돌아온 Payment 객체의 secret 값과 같은지 확인하세요. 값이 같다면 토스페이먼츠 서버에서 돌아온 올바른 요청입니다.

{
  "createdAt": "2022-06-09T15:40:09+09:00",
  "secret": "",
  "status": "DONE",
  "transactionKey": "13CD6AE82C268B57F4E7FB976DC45475",
  "orderId": ""
}

가상계좌 발급 요청이 정상적으로 승인된 응답에만 secret 값이 있고, 이후에 결제 조회를 할 때는 보안 이유로 secret 값이 null로 돌아옵니다.