가이드
목차

카드사 및 자체창을 바로 호출하기 위해서는 결제 UI를 직접 만들어야 합니다. 새로운 버전의 결제위젯을 사용하면 따로 결제 UI를 만들 필요가 없어 편리합니다.

카드사 및 간편결제 자체창 바로 열기

토스페이먼츠 결제창 화면 대신 미리 선택한 카드사와 간편결제사의 자체창을 바로 호출하는 방법을 알려드려요.

카드사 자체창은 앱카드, 일반결제 등 카드사에서 제공하는 모든 결제 방법을 제공합니다. 간편결제사 자체창은 고객이 간편결제에 미리 등록한 카드나 계좌로 결제할 수 있는 서비스를 제공합니다. 해외카드 자체창은 지원하지 않습니다.

결제창-결제흐름

샘플 프로젝트자체창 샘플 프로젝트입니다.
결제창 SDK 레퍼런스JavaScript SDK 스펙을 더 자세히 알아보세요.

는 토스페이, 네이버페이, 삼성페이, 엘페이, 카카오페이, 페이코, SSG페이를 지원합니다. 간편결제 서비스를 연동하려면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

API 키 준비하기

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

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

JavaScript
// API 개별 테스트 연동 키

// 토스페이먼츠에 회원 가입하기 전이라면 아래 키는 문서 테스트 키입니다.

// 토스페이먼츠에 회원 가입하고 로그인한 상태라면 아래 키는 내 테스트 키입니다.

const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'

const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

1. 먼저, SDK를 준비하세요

SDK를 스크립트 태그에 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다.

<head>

  <meta charset="utf-8" />

  <title>결제하기</title>

  <script src="https://js.tosspayments.com/v1/payment"></script>

</head>

<body>

  <script>
    var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
    var tossPayments = TossPayments(clientKey) // 클라이언트 키로 초기화하기
  </script>

</body>

더 자세한 SDK 설명은 결제창 SDK 페이지에서 확인할 수 있습니다.

2. 결제창을 띄워보세요 🚀

초기화된 객체로 SDK 메서드를 사용할 수 있습니다. requestPayment(결제수단, 결제 정보)메서드로 결제창을 호출합니다.

첫 번째 파라미터는 결제수단입니다. 카드사 결제창 및 간편결제창은 결제수단으로 카드를 추가하세요.

두 번째 파라미터는 결제 정보입니다. 결제 금액 등 필수 파라미터를 먼저 설정하고 flowMode 파라미터를 DIRECT로 고정하세요. 자체창으로 열 카드사를 cardCompany에 카드사 코드로 설정하세요. 간편결제는 easyPay에 간편결제사 코드로 설정하세요.

JavaScript
tossPayments

  .requestPayment('카드', {

    // 결제수단

    // 결제 정보

    amount: 15000,

    orderId: '',

    orderName: '토스 티셔츠 외 2건',

    customerName: '박토스',

    successUrl: 'http://localhost:8080/success',

    failUrl: 'http://localhost:8080/fail',

    flowMode: 'DIRECT',

    easyPay: '토스페이',

  })

  .catch(function (error) {

    if (error.code === 'USER_CANCEL') {

      // 결제 고객이 결제창을 닫았을 때 에러 처리

    } else if (error.code === 'INVALID_CARD_COMPANY') {

      // 유효하지 않은 카드 코드에 대한 에러 처리

    }

  })

카드사 간편결제 결제창 예시 이미지

메서드 실행에 성공하면 위와 같이 선택한 카드사 또는 간편결제사 자체창이 열립니다. 결제를 완료하려면 결제 승인을 요청하세요.

메서드 실행에 실패하면 reject 된 에러는 Promise의 catch 블록에서 처리할 수 있습니다. 발생할 수 있는 에러 코드를 살펴보세요.

카드사 결제창 또는 간편결제창을 띄우기 전에 고객에게 아래 토스페이먼츠 이용약관 동의를 받으세요.

- 전자금융거래 이용약관: https://pages.tosspayments.com/terms/user

- 개인(신용)정보 수집이용 동의: https://pages.tosspayments.com/terms/privacy/consent1

- 개인(신용)정보 제3자 제공 동의: https://pages.tosspayments.com/terms/privacy/consent2

결제 정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    주문번호입니다. 주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • successUrl 필수 · string

    결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.

  • flowMode string

    결제창 유형입니다. DEFAULT, DIRECT 중 하나입니다.

    카드사 결제창 또는 간편결제창을 연동하려면 값을 DIRECT로 지정하고 cardCompany 또는 easyPay 파라미터를 설정하세요.

  • easyPay string

    연동하려는 간편결제 서비스 코드입니다. 예를 들어, 토스페이 값을 주면 바로 토스페이 결제창이 실행됩니다. 간편결제사 코드를 참고하세요.

    * 테스트 환경에서는 페이코의 결제 및 취소가 제대로 진행되지 않을 수 있습니다.

  • cardCompany string

    카드사 코드입니다. 카드사 코드를 참고하세요. 예를 들어, 현대 값을 주면 현대카드 결제창이 실행됩니다.

    * 카드사 결제창은 국내 카드사만 지원합니다. 해외 카드사 코드는 사용할 수 없습니다.

  • useAppCardOnly boolean

    카드사 앱카드로만 결제할지 결정합니다. 이 값을 true로 주면 카드사 결제창에서 일반결제 등 다른 결제 방식을 선택할 수 있는 단계를 건너뛰고 바로 카드사의 앱카드 결제창이 열립니다.

    국민, 농협, 롯데, 삼성, 신한, 우리, 현대 카드에만 true 값을 사용할 수 있습니다.

  • appScheme string

    페이북/ISP 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. testapp://같은 형태입니다.

카드사 결제창 및 간편결제창에서 사용할 수 있는 더 많은 파라미터는 결제창 Javascript SDK에서 확인하세요.

3. 결제 승인을 요청하세요

결제 요청이 성공하면 successUrl로 이동합니다. URL에 포함된 를 확인하고 결제 승인을 요청하세요.

결제 요청이 실패하면 failUrl로 이동합니다. 결제 실패 URL 리다이렉트를 살펴보세요.

리다이렉트 URL 확인하기

결제 성공 리다이렉트 URL에는 paymentKey, orderId, amount 세 가지 가 들어있습니다.

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

리다이렉트 URL 쿼리 파라미터를 이용해 결제 승인 API를 호출할 수 있습니다.

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

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

결제 승인 API 호출하기

결제 승인 API를 호출합니다. 요청 본문에는 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣습니다. Basic 인증 헤더에는 시크릿 키와 콜론을 base64로 인코딩해서 넣습니다.

successUrl로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출해야 합니다.

4. 결제를 성공적으로 완료하셨네요! 🎉

API 호출 결과로 HTTP 200 OK를 받으면 결제 승인 성공입니다. 상태 코드와 함께 Payment 객체가 응답으로 돌아옵니다. 응답 객체에 선택한 결제수단의 필드가 있는지 확인하세요.

간편결제 서비스를 사용하면 선택한 결제수단에 따라 돌아오는 응답 객체가 달라집니다. 간편결제 응답 확인 가이드를 참고해서 간편결제 응답 객체 처리까지 진행해주세요.

응답
JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  "status": "DONE",

  "requestedAt": "2022-08-17T15:38:47+09:00",

  "approvedAt": "2022-08-17T15:39:14+09:00",

  "useEscrow": false,

  "cultureExpense": false,

  "card": null,

  "virtualAccount": null,

  "transfer": null,

  "mobilePhone": null,

  "giftCertificate": null,

  "cashReceipt": null,

  "cashReceipts": null,

  "discount": null,

  "cancels": null,

  "secret": null,

  "type": "NORMAL",

  "easyPay": {

    "provider": "토스페이",

    "amount": 15000,

    "discountAmount": 0

  },

  "country": "KR",

  "failure": null,

  "isPartialCancelable": true,

  "receipt": {

    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=cno3Idq53AKHoXP%2BJnAWt70lTLYJHVytjcCu%2FhEIUd56LAMEmBlJ9FWaQinp0uZ1&ref=PX"

  },

  "checkout": {

    "url": "https://api.tosspayments.com/v1/payments//checkout"

  },

  "currency": "KRW",

  "totalAmount": 15000,

  "balanceAmount": 15000,

  "suppliedAmount": 13636,

  "vat": 1364,

  "taxFreeAmount": 0,

  "taxExemptionAmount": 0,

  "method": "간편결제"

}

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

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

5. 간편결제 응답 확인하기

에서 결제수단을 조합해서 사용하면 결제 응답 객체가 조금씩 달라집니다. 아래 토스페이 사용 예시를 확인해보세요.

간편결제 결제수단 타입

결제수단설명응답 객체 금액 필드예시
신용·체크 카드고객이 간편결제 서비스에 등록한 카드card.amount토스페이에 등록된 카드
충전식 결제수단고객이 금액을 충전해서 사용하는 결제수단으로 간편결제 서비스에 등록한 계좌 혹은 현금성 포인트easyPay.amount토스페이에 연결된 계좌, 카카오페이머니
적립식 결제수단*고객이 간편결제사에서 제공하는 결제 서비스를 이용해서 적립된 포인트, 쿠폰, 즉시할인 금액으로 카드나 충전식 결제수단과 조합해서 사용easyPay.discountAmount토스포인트, 카카오페이포인트

* 적립식 결제수단은 카드 혹은 충전식 결제수단과 조합해서 사용할 수 있습니다.

Case 1. 간편결제에 등록된 카드로 결제하기

토스페이에 등록된 카드로 15,000원을 결제하면 전체 결제 금액 totalAmount는 카드로 결제한 금액인 card.amount와 동일합니다.

JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "status": "DONE",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  //...

  "card": {

    "issuerCode": "61",

    "acquirerCode": "31",

    "number": "123456******7890",

    "installmentPlanMonths": 0,

    "isInterestFree": false,

    "interestPayer": null,

    "approveNo": "21974757",

    "useCardPoint": false,

    "cardType": "신용",

    "ownerType": "개인",

    "acquireStatus": "READY",

    "amount": 15000

  },

  "easyPay": {

    "provider": "토스페이",

    "amount": 0,

    "discountAmount": 0

  },

  //...

  "totalAmount": 15000

}

Case 2. 간편결제에 등록된 카드 + 적립식 결제수단으로 결제하기

토스페이에 등록된 카드로 10,000원을 결제하고 토스포인트에서 5,000원을 사용해 총 15,000원을 결제합니다.

전체 결제 금액 totalAmount은 card.amount와 easyPay.discountAmount의 합계입니다.

JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "status": "DONE",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  //...

  "card": {

    "issuerCode": "61",

    "acquirerCode": "31",

    "number": "123456******7890",

    "installmentPlanMonths": 0,

    "isInterestFree": false,

    "interestPayer": null,

    "approveNo": "21706400",

    "useCardPoint": false,

    "cardType": "체크",

    "ownerType": "개인",

    "acquireStatus": "READY",

    "amount": 10000

  },

  "easyPay": {

    "provider": "토스페이",

    "amount": 0,

    "discountAmount": 5000

  },

  //...

  "totalAmount": 15000

}

Case 3. 충전식 결제수단으로 결제하기

토스페이에 연결된 계좌로 결제하면 전체 결제 금액 totalAmount는 계좌로 결제한 금액인 easyPay.amount와 동일합니다. 즉 easyPay 객체만 확인하면 됩니다.

JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "status": "DONE",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  //...

  "card": null,

  "easyPay": {

    "provider": "토스페이",

    "amount": 15000,

    "discountAmount": 0

  },

  //...

  "totalAmount": 15000

}

Case 4. 충전식 결제수단 + 적립식 결제수단으로 결제하기

토스페이에 연결된 계좌로 15,000원을 결제하고 토스포인트에서 5,000원을 사용해 총 15,000원을 결제합니다.

전체 결제 금액 totalAmount는 easyPay.amount와 easyPay.discountAmount의 합계입니다.

JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "status": "DONE",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  //...

  "card": null,

  "easyPay": {

    "provider": "토스페이",

    "amount": 10000,

    "discountAmount": 5000

  },

  //...

  "totalAmount": 15000

}

Case 5. 적립식 결제수단으로 결제하기

토스포인트로 15,000원을 결제하면 전체 결제 금액 totalAmount는 easyPay.discountAmount와 동일합니다. 즉 easyPay 객체만 확인하면 됩니다.

JSON
{

  "mId": "tosspayments",

  "version": "2022-11-16",

  "paymentKey": "",

  "status": "DONE",

  "lastTransactionKey": "",

  "orderId": "",

  "orderName": "토스 티셔츠 외 2건",

  //...

  "card": null,

  "easyPay": {

    "provider": "토스페이",

    "amount": 0,

    "discountAmount": 15000

  },

  //...

  "totalAmount": 15000

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