커넥트페이 JavaScript SDK

커넥트페이 JavaScript SDK는 브라우저 환경에서 사용할 수 있는 SDK(Software Development Kit)로, 커넥트페이 결제와 관련한 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.

SDK 추가

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

스크립트 로드가 완료되면 전역 객체(window)에 ConnectPay가 생성됩니다. 이 함수를 이용해서 초기화를 진행할 수 있습니다.

index.html
<head>
<title>커넥트페이로 결제하기</title>
<!-- 1. 스크립트 추가 -->
<script src="https://js.tosspayments.com/v1/connectpay"></script>
</head>
<script> var clientKey = 'test_ck_YZ1aOwX7K8mzAJ1WnwP3yQxzvNPG' // 테스트 키 값 var customerKey = 'customer123' // 2. 초기화 var connectpay = ConnectPay(clientKey, customerKey, { redirectUrl: 'http://example.com', ui: { buttonStyle: 'full', highlightColor: '#26C2E3', labels: { oneTouchPay: '바로페이', }, }, }) </script>
HTML

초기화는 SDK를 사용하기 위한 설정 작업입니다. 설치된 SDK에 포함된 메서드를 사용할 수 있도록 객체를 만들고, 클라이언트 키 값을 통해 가맹점을 구분할 수 있습니다.

클라이언트 키와 customerKey, 리다이렉트 URL을 SDK에서 제공하는 ConnectPay 함수에 넣고 실행하면 초기화된 객체가 생성됩니다. 토스페이먼츠에서 제공하는 테스트용 클라이언트 키는 개발 설정 페이지에서 확인할 수 있습니다. 가맹점에서 고객을 특정하기 위해 사용하는 값을 customerKey로 사용할 수 있도록 준비해주세요.

패키지 매니저로 설치하기

커넥트페이 JavaScript SDK는 npm 패키지로도 제공됩니다. 사용하는 패키지 매니저에 따라 아래 명령어로 SDK를 설치해보세요.

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

커넥트페이 SDK의 npm 패키지는 패키지 내부에 커넥트페이 JavaScript SDK 소스코드를 포함하지 않습니다. 동적으로 HTML에 https://js.tosspayments.com/v1/connectpay 코드를 삽입하는 역할을 합니다. 따라서 사용하는 번들러의 번들링 대상에 포함되지 않습니다.

UI 옵션 설정하기

ConnectPay 함수의 세번째 파라미터는 인증을 위해 필수적인 리다이렉트 URL, 선택적으로 적용할 수 있는 UI 옵션으로 이루어져 있습니다.

var connectPay = ConnectPay(clientKey, customerKey, {
redirectUrl: 'http://example.com',
ui: {
highlightColor: '#26C2E3',
buttonStyle: 'full',
labels: {
oneTouchPay: '바로페이',
},
},
})
JavaScript

초기화 파라미터

  • redirectUrl 필수 · string

    리다이렉트 URL은 권한을 증명하는 인증코드를 받기 위해 반드시 필요합니다.

    개발 설정 페이지에 값이 추가되어 있어야 합니다.

  • ui string

    UI 커스터마이징 옵션을 담은 객체입니다. 각 파라미터 옵션에 따라 달라지는 결제창 UI는 아래 이미지를 참고하세요.

    • buttonStyle string

      버튼 스타일입니다. 값이 없으면 default가 기본값으로 지정됩니다.

      default로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, full로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다.

      • default
      • full
    • highlightColor string

      UI의 메인 강조 컬러입니다. 값이 없으면 기본 색상인 #3182f6로 설정됩니다.

      웹에서 사용할 수 있는 색상 코드 형식을 모두 사용할 수 있습니다.

    • showNavigationBar string

      커넥트페이에서 제공하는 상단 내비게이션 UI를 사용할지 여부입니다. 값이 없으면 기본값으로 true가 설정됩니다.

      상단 내비게이션을 사용하지 않으려면 false로 설정해야 합니다.

    • labels object

      UI에 사용되는 커스텀 텍스트들을 모아둔 객체입니다.

      • oneTouchPay string

        UI에 표시되는 원터치결제를 대신해 사용할 텍스트입니다. 값이 없으면 원터치결제가 보여집니다.

UI 파라미터 옵션에 따라 달라지는 결제창 화면 예시

UI 옵션 이미지 1

UI 옵션 이미지 2

응답

커넥트페이 JavaScript SDK 메서드를 실행하면 Promise 객체가 응답으로 돌아옵니다. 사용자가 창을 닫은 경우 codeUSER_CANCEL인 에러가 돌아옵니다.

모든 메서드 응답에 대해 성공 및 에러 처리를 동일한 방식으로 할 수 있습니다.

응답처리
connectPay
.getPaymentMethod() // 다른 메서드들도 동일한 방식으로 처리됨
.then(function () {
// 성공 처리
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript

휴대폰 본인 인증이 먼저 진행된 후에 메서드를 사용할 수 있습니다. 만약 휴대폰 본인 인증이 완료되지 않은 상태에서 메서드를 실행하면 휴대폰 본인 인증 과정을 먼저 거치게 됩니다.

getPaymentMethods()

등록되어 있는 결제수단을 조회하는 메서드입니다.

connectPay
.getPaymentMethods()
.then(function (methods) {
// 성공 처리
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript

메서드를 실행하면 응답으로 Promise가 돌아옵니다. then 에서 등록된 결제수단 정보를 확인할 수 있습니다. 이 데이터를 이용해서 결제수단을 UI에 표시하는 작업을 할 수 있습니다.

각 결제수단에 할당된 id 값은 결제수단을 특정하는 값입니다. selectedMethodId 필드는 가장 최근에 등록했거나 사용한 결제수단의 id 값을 보여줍니다. 전체 결제수단의 등록날짜와 최근 1달 이내에 사용한 결제수단의 사용일을 비교해 가장 최근에 등록했거나 사용한 결제수단의 id가 내려갑니다. 등록한 결제수단이 없다면 null이 내려갑니다.

응답
{
"isIdentified": false,
"selectedMethodId": "c_L4MrjxdRvjjG130z", // 가장 최근에 등록했거나 사용한 결제수단의 ID
"accounts": [
{
"accountName": "우리은행 계좌",
"accountNumber": "100******1234",
"alias": "",
"bank": "우리",
"bankCode": "20",
"iconUrl": "https://static.toss.im/icons/png/4x/icn-bank-woori.png",
"id": "b_pdA8d1B6n61LP3o1",
"methodKey": "c6MKlA4XDvdYoEjb0gm23PvK5B7ZvNrpGwBJn5eya1RPQkx9q",
"registeredAt": "2021-11-26T16:28:45+09:00",
"status": "DISABLED"
}
],
"cards": [
{
"alias": "",
"cardCompany": "현대",
"cardImgUrl": null,
"cardName": "현대백화점카드",
"cardNumber": "176237******7777",
"cardType": "신용",
"companyCode": "61",
"iconUrl": "https://static.toss.im/icons/png/4x/icn-bank-square-hyundaicard.png",
"id": "c_L4MrjxdRvjjG130z",
"installmentMinimumAmount": 0,
"issueCompany": "우리",
"methodKey": "cyvKaNpekDYjZ61JOxRQVEKaaKvzDg8W0X9bAqwdmgPznL42o",
"ownerType": "개인",
"registeredAt": "2021-11-29T12:48:47+09:00",
"status": "ENABLED"
}
]
}
JSON

addPaymentMethod('카드'|'계좌')

결제수단을 등록할 수 있는 메서드입니다.

카드, 계좌 중 등록할 결제수단을 파라미터로 추가하면 바로 해당 결제수단 등록 창으로 연결됩니다. 파라미터 없이 실행하면 결제수단을 선택하는 창으로 연결됩니다.

connectPay
.addPaymentMethod('카드')
.then(function (methods) {
// 성공 처리
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript

결제수단 등록창이 닫히면 Promise가 돌아옵니다. then 에서 등록된 결제수단 정보를 확인할 수 있습니다.

selectedMethodId 값을 통해 가장 최근에 등록했거나 사용한 결제수단 정보도 확인할 수 있습니다.

응답
{
"selectedMethodId": "c_Eba3Gmdj4j1yQrpW",
"cards": [
{
"id": "c_Eba3Gmdj4j1yQrpW",
"cardCompany": "현대",
"cardNumber": "4330********1234",
"cardName": "현대비자플래티늄",
"ownerType": "개인",
"cardType": "신용",
"registeredAt": "2021-02-02T17:26:36+09:00",
"status": "ENABLED"
}
],
"accounts": [
{
"id": "b_pdA8d1B6n61LP3o1",
"bank": "우리",
"accountNumber": "100******2333",
"registeredAt": "2021-02-26T14:32:07+09:00",
"status": "ENABLED"
}
]
}
JSON

requestPayment(결제정보)

커넥트페이 결제창을 띄우는 메서드입니다. 결제정보 객체를 파라미터로 추가해서 실행합니다.

connectPay.requestPayment({
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
customerEmail: 'customer@example.com',
shippingAddress: '서울특별시 강남구 역삼동 647-9 15층',
}).catch(function (error)) {
if (error.code) {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript

결제정보

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    가맹점에서 사용하는 해당 주문에 대한 ID입니다. 각 주문마다 유니크해야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • methodId string

    결제수단 ID 입니다. 등록되어 있는 결제수단 중 하나를 지정해서 바로 결제하고 싶을 때 사용합니다.

  • customerEmail string

    고객의 이메일주소입니다.

  • shippingAddress string

    고객의 배송지 주소입니다. 부정거래탐지시스템(FDS, Fraud Detection System, 거래 정보와 고객 정보, 평소 거래 패턴 등을 분석해서 의심되는 전자금융거래를 탐지하고 차단하는 기술)에 사용할 수 있습니다.

  • taxFreeAmount string

    면세금액입니다.

  • cardInstallmentPlan string

    카드로 결제한 경우 설정하는 할부 개월 수입니다. 값이 있으면 할부 개월 수가 고정된 상태로 결제창이 열립니다.

    값은 2부터 12까지 사용할 수 있습니다. 0이 들어가는 경우 할부가 아닌 일시불로 결제됩니다.

    값을 따로 넣지 않으면 결제창에서 전체 할부 개월 수를 선택할 수 있습니다.

  • useCardPoint string

    카드로 결제한 경우 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않으면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다.

    이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다. 이 값을 false로 주면 사용자는 카드사 포인트를 사용할 수 없습니다.

  • discountCode string

    카드로 결제한 경우 설정하는 카드사의 할인 코드입니다.

    카드혜택 조회 API를 통해 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.

  • cashReceipt string

    카드로 결제한 경우 설정하는 카드사의 할인 코드입니다.

    • type string

      현금영수증의 종류입니다. 미발급소득공제지출증빙 중 하나입니다. 값이 있으면 결제창에 현금영수증이 입력된 채 열립니다.

    • registrationNumber string

      현금영수증 발급을 위한 개인 식별 번호입니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

openSettings()

커넥트페이에서 사용하는 결제수단, 비밀번호, 원터치결제 사용을 관리하는 결제 관리창을 열 수 있습니다.

connectPay.openSettings().catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript

setupOneTouchPay()

원터치페이 설정 창을 열 수 있습니다. 원터치페이는 결제할 때 비밀번호 입력없이 바로 결제할 수 있는 커넥트페이 기능입니다.

메서드를 실행하면 Promise가 돌아오고, 원터치페이 설정이 완료되어 창이 닫히면 Promisefulfilled 상태로 변경됩니다.

connectPay.setupOneTouchPay().catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 창을 닫아 취소한 경우에 대한 처리
}
})
JavaScript

requestAgreement('빌링')

선택약관 동의 창을 띄우는 메서드입니다.

파라미터로 동의받을 선택약관 이름을 추가하면 해당 약관을 볼 수 있습니다. 현재 자동결제를 위한 '빌링'파라미터만 지원합니다.

connectPay.requestAgreement('빌링')
JavaScript

'빌링' 을 설정하면 자동결제 동의 약관 창을 열 수 있습니다. 동의가 완료되면 자동결제에 대한 결제 실행 API를 사용할 수 있습니다.

메서드를 실행하면 Promise가 돌아오고, 약관동의가 완료되면 Promisefulfilled 상태로 변경됩니다.

응답
connectpay
.requestAgreement('빌링') // 자동결제 선택 약관 동의 호출
.then(function () {
// 성공 처리
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 사용자가 결제창을 닫은 경우 에러 처리
}
})
JavaScript
내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기