ClickTo SDK 개발 문서

ClickTo SDK는 외부 쇼핑몰 플랫폼(카페24, 제노레이 등)에 정기구독·렌탈·리스·할부 결제 버튼을 손쉽게 삽입할 수 있는 JavaScript SDK입니다.

동작 방식

1. 가맹점 페이지에서 /api/sdk.js?siteKey= 스크립트를 로드합니다. 메인 SDK + CSS + Provider SDK가 한 번에 로드됩니다.
2. bclickto.initialize(config)를 호출하면 Provider가 초기화되고 결제 버튼이 렌더링됩니다.
3. 페이지 내 #clicktoButtonBox 영역에 구독 버튼이 자동 렌더링됩니다.
4. 사용자가 버튼을 클릭하면 checkout()이 실행되어 결제 창이 열립니다.
5. 체크아웃 성공 시 oncheckout 콜백이 호출되어 GTM 등 이벤트 트래킹을 수행합니다.

빠른 시작

<!-- 1. SDK 삽입 -->
<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>

<!-- 2. 버튼 컨테이너 -->
<div id="clicktoButtonBox"></div>

<!-- 3. 초기화 -->
<script>
bclickto.initialize({
  siteKey: 'your_site_key',
  setting: {
    contract_type: 'subscription',
    button_type: 'subscribe_v2',
    subscription_plans: ['monthly-1'],
  },
  customer: {
    name: '홍길동',
    email: 'user@example.com',
    phone: '01012345678',
  },
  // 체크아웃 성공 시 GTM 등 이벤트 트래킹용 콜백
  oncheckout: async (data) => {
    window.dataLayer?.push({
      event: 'clickto_checkout',
      checkout_uuid: data.checkout_uuid,
    });
  },
});
</script>

설치

별도 npm 패키지 없이 <script> 태그 한 줄로 SDK와 플랫폼 전용 스크립트를 한 번에 로드합니다. siteKey 파라미터에 발급받은 가맹점 키를 지정하세요.

<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>

로드 후 전역 변수 window.bclickto로 SDK에 접근합니다. SDK 스크립트, CSS, 플랫폼 전용 Provider가 모두 포함되어 별도의 추가 로딩이 필요하지 않습니다.

맞춤형 SDK

ClickTo SDK는 모든 가맹점이 동일한 스크립트 URL을 사용하며, siteKey 파라미터에 따라 해당 플랫폼에 맞는 SDK가 자동으로 구성됩니다.

가맹점별 연동 방식

가맹점 관리자 페이지에서 발급받은 siteKey를 스크립트 URL에 포함합니다.

<!-- 발급받은 siteKey를 URL에 포함 -->
<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>

설치 절차

1. ClickTo 관리자 페이지에서 가맹점 등록 후 siteKey를 발급받습니다.
2. 발급된 siteKey가 포함된 SDK 스크립트 태그를 쇼핑몰 상품 상세 페이지에 삽입합니다.
3. bclickto.initialize(config)를 호출하여 초기화합니다. 서버 주소는 자동으로 설정됩니다.

전체 설치 예시

<!-- 1. 버튼이 표시될 영역 -->
<div id="clicktoButtonBox"></div>

<!-- 2. SDK 로드 -->
<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>

<!-- 3. 초기화 -->
<script>
bclickto.initialize({
  siteKey: 'your_site_key',
  setting: {
    contract_type: 'subscription',
    subscription_plans: ['monthly-1'],
  },
  customer: {
    name: '홍길동',
    phone: '01012345678',
    email: 'user@example.com',
  },
  delivery: {
    recipient_name: '홍길동',
    phone: '01012345678',
    postcode: '06234',
    address1: '서울시 강남구 테헤란로 123',
    address2: '4층',
  },
});
</script>

초기화가 완료되면 #clicktoButtonBox 영역에 결제 버튼이 자동으로 렌더링됩니다. 각 파라미터의 상세 설정은 initialize(config)를 참조하세요.

initialize(config)

SDK를 초기화합니다. 반드시 checkout() 호출 이전에 실행해야 합니다.

Setting

Customer

구매자 정보입니다. 모든 필드는 선택 사항이며, 입력하지 않은 정보는 체크아웃 화면에서 직접 입력할 수 있습니다.

Delivery

배송 정보입니다. 모든 필드는 선택 사항이며, 체크아웃 화면에서 입력할 수 있습니다. shipping_type이 digital인 경우 배송 정보는 불필요합니다.

계약 타입

setting.contract_type으로 계약 방식을 지정합니다. 각 계약 타입에 해당하는 플랜 배열을 함께 설정해야 합니다.

subscription — 정기구독

일정 주기마다 자동 결제되는 정기구독 방식입니다. 소프트웨어 월간 구독, 건강식품 정기 배송, 화장품 리필 서비스 등에 적합합니다.

setting: {
  contract_type: 'subscription',
  subscription_plans: ['monthly-1'],  // 매월 결제
}

subscription_plans 값 설명

subscription_plans는 문자열 배열로, '주기-반복수' 형식입니다.

// 여러 플랜을 제공하면 고객이 체크아웃 시 선택 가능
setting: {
  contract_type: 'subscription',
  subscription_plans: ['monthly-1', 'monthly-3', 'yearly-1'],
}

subscription-delivery — 정기배송 구독

정기구독에 실물 배송이 포함된 방식입니다. 생수·사료 정기배송, 신선식품 구독 박스, 소모품 자동 보충 등 실물 상품을 주기적으로 배송하는 서비스에 적합합니다.

subscription과 동일한 subscription_plans를 사용하며, 배송 정보(Delivery)를 함께 설정합니다.

setting: {
  contract_type: 'subscription-delivery',
  subscription_plans: ['monthly-1'],
  shipping_type: 'physical',
},
delivery: {
  recipient_name: '홍길동',
  address1: '서울시 강남구 ...',
  phone: '01012345678',
}

rental — 렌탈

계약 기간 동안 제품을 대여하는 방식입니다. 정수기 렌탈, 의료장비 대여, 사무기기 렌탈 등에 적합합니다.

rental_plans는 렌탈 기간(개월 수)의 숫자 배열입니다.

setting: {
  contract_type: 'rental',
  rental_plans: [12],       // 12개월 렌탈
}

// 여러 기간 옵션 제공
setting: {
  contract_type: 'rental',
  rental_plans: [12, 24, 36],  // 12·24·36개월 중 선택
}

lease — 리스

리스 계약 방식입니다. 고가 장비 리스, 차량 리스 등 장기 계약에 적합합니다.

lease_plans는 리스 기간(개월 수)의 숫자 배열입니다.

setting: {
  contract_type: 'lease',
  lease_plans: [24],        // 24개월 리스
}

// 여러 기간 옵션 제공
setting: {
  contract_type: 'lease',
  lease_plans: [24, 36, 48],   // 24·36·48개월 중 선택
}

installment — 할부

상품 금액을 분할납부하는 방식입니다. 고가 상품의 무이자 할부, 분할 결제 등에 적합합니다.

installment_plans는 할부 기간(개월 수)의 숫자 배열입니다.

setting: {
  contract_type: 'installment',
  installment_plans: [6],   // 6개월 할부
}

// 여러 할부 옵션 제공
setting: {
  contract_type: 'installment',
  installment_plans: [3, 6, 12],  // 3·6·12개월 중 선택
}

계약금·보증금·위약금 안내

oncheckout 콜백 (이벤트 트래킹)

체크아웃이 성공적으로 생성된 직후, 결제 창이 열리기 전에 호출되는 비동기 함수입니다. GTM(Google Tag Manager), Facebook Pixel, GA4 등 광고·분석 스크립트의 이벤트를 발생시키는 데 사용합니다.

콜백 시그니처

oncheckout: async (data) => {
  // data.checkout_uuid  — 체크아웃 고유 ID (string)
  // data.products       — 결제 대상 상품 배열
  // data.contract       — 계약 타입 정보 { type, plan }
  // data.setting        — SDK 설정 정보
}

GTM (Google Tag Manager) 연동 예시

oncheckout: async (data) => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'clickto_checkout',
    checkout_uuid: data.checkout_uuid,
    product_count: data.products.length,
    contract_type: data.contract.type,
    total_price: data.products.reduce((sum, p) => sum + (p.price * p.quantity), 0),
  });
}

Facebook Pixel 연동 예시

oncheckout: async (data) => {
  if (typeof fbq === 'function') {
    fbq('track', 'InitiateCheckout', {
      content_ids: data.products.map(p => p.code),
      content_type: 'product',
      num_items: data.products.length,
      value: data.products.reduce((sum, p) => sum + (p.price * p.quantity), 0),
      currency: 'KRW',
    });
  }
}

GA4 이벤트 연동 예시

oncheckout: async (data) => {
  if (typeof gtag === 'function') {
    gtag('event', 'begin_checkout', {
      transaction_id: data.checkout_uuid,
      items: data.products.map(p => ({
        item_id: p.code,
        item_name: p.name,
        price: p.price,
        quantity: p.quantity,
      })),
    });
  }
}

버튼 커스텀

setting.button_type으로 버튼 스타일을 선택합니다.

버튼이 렌더링될 위치에 아래 요소를 배치하세요.

<div id="clicktoButtonBox"></div>

커스텀 버튼 디자인

가맹점에서 직접 디자인한 버튼을 사용할 수 있습니다. setting.button_selector에 CSS selector를 지정하면 SDK가 해당 요소에 결제 이벤트를 자동으로 연결하며, SDK 기본 버튼은 렌더링되지 않습니다.

사용 예시

<!-- 가맹점이 직접 디자인한 버튼 -->
<button id="my-subscribe-btn" class="my-custom-class">
  지금 구독 신청하기
</button>

<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>
<script>
bclickto.initialize({
  siteKey: 'your_site_key',
  setting: {
    contract_type: 'subscription',
    button_selector: '#my-subscribe-btn',  // 커스텀 버튼 selector
    subscription_plans: ['monthly-1'],
  },
});
</script>

class selector, 속성 selector 등 표준 CSS selector를 모두 지원합니다.

// 다양한 selector 예시
button_selector: '#my-btn'           // ID
button_selector: '.checkout-button'  // class
button_selector: '[data-clickto]'    // 속성

주의 사항

플랫폼 연동 가이드

플랫폼별 Provider SDK는 siteKey에 따라 자동으로 로드됩니다. 각 SDK는 해당 플랫폼의 상품 정보를 자동으로 수집합니다.

카페24 연동

사전 요구 사항

• CAFE24 API 앱이 설치되어 있어야 합니다.
• window.CAFE24API 객체가 존재해야 합니다.
• 상품 상세 페이지에서만 동작합니다.

연동 예시

<!-- 상품 상세 페이지 내 -->
<div id="clicktoButtonBox"></div>

<script src="https://clickto.benecent.org/api/sdk.js?siteKey=your_site_key"></script>
<script>
bclickto.initialize({
  siteKey: 'your_site_key',
  setting: {
    contract_type: 'subscription',
    button_type: 'subscribe_v2',
    subscription_plans: ['monthly-1'],
  },
});
</script>

지원 상품 유형

지원 예정 플랫폼

아래 플랫폼에 대한 Provider SDK가 개발 예정입니다.

• 메이크샵 (Makeshop) — 지원 예정
• 아임웹 (Imweb) — 지원 예정
• 개인/독립몰 — 개별 지원 예정. 별도 문의가 필요합니다.

에러 처리

checkout()은 내부적으로 에러를 throw합니다. 버튼 클릭 핸들러에서 try/catch로 자동 처리되며, 에러는 브라우저 콘솔에 기록됩니다.

// SDK 내부 처리 (자동)
try {
  await bclickto.checkout();
} catch (error) {
  console.error('Checkout error:', error);
}

공통 에러

카페24 (Cafe24) 에러

제노레이 (Genoray) 에러

네트워크 / CORS 에러

브라우저 콘솔에 CORS 관련 에러가 표시되면, SDK 스크립트를 로드하는 도메인이 ClickTo 서버의 허용 목록에 등록되어 있는지 확인하세요. 가맹점 등록 시 도메인이 자동 등록됩니다.

체크아웃 플로우

SDK를 통한 결제는 다음 단계로 진행됩니다.

전체 결제 흐름

┌─────────────────────────────────────────────────────────────┐
│  1. SDK 로드 (1-step)                                       │
│     <script src=".../api/sdk.js?siteKey=your_site_key"></script>      │
│     → 메인 SDK + CSS + Provider SDK 한 번에 로드              │
│     → window.bclickto 사용 가능                              │
├─────────────────────────────────────────────────────────────┤
│  2. 초기화                                                   │
│     bclickto.initialize(config)                             │
│     → Provider 초기화 + 결제 버튼 렌더링                       │
├─────────────────────────────────────────────────────────────┤
│  3. 버튼 클릭                                                │
│     → checkout() 자동 호출                                   │
├─────────────────────────────────────────────────────────────┤
│  4. 상품 정보 수집                                            │
│     → Provider SDK가 페이지 DOM에서 상품 데이터 자동 추출        │
│     → 상품명, 가격, 수량, 옵션 등                              │
├─────────────────────────────────────────────────────────────┤
│  5. 체크아웃 생성                                             │
│     → POST /api/checkout (상품, 설정, 고객, 배송 정보 전송)     │
│     → 서버에서 체크아웃 UUID 발급                               │
├─────────────────────────────────────────────────────────────┤
│  6. oncheckout 콜백 실행                                     │
│     → GTM, Facebook Pixel 등 이벤트 트래킹                    │
│     → 콜백 에러 시에도 결제 흐름 계속 진행                       │
├─────────────────────────────────────────────────────────────┤
│  7. 결제 창 열림                                              │
│     → 새 브라우저 탭에서 체크아웃 페이지 표시                     │
│     → 고객이 결제 정보 입력 및 결제 진행                         │
└─────────────────────────────────────────────────────────────┘

정기결제 동작 원리

정기구독, 정기배송, 렌탈 등 반복 결제가 필요한 계약 타입은 다음과 같이 동작합니다.

1. 최초 체크아웃: 고객이 SDK를 통해 결제를 완료하면 계약(Contract)이 생성됩니다.
2. 결제수단 등록: 최초 결제 시 고객의 결제수단(카드 등)이 자동으로 등록됩니다.
3. 자동 결제 스케줄링: 계약 타입과 플랜에 따라 정기결제 엔진(RecurringBilling)이 후속 결제를 자동으로 스케줄링합니다.
4. 반복 결제 실행: 예약된 날짜에 등록된 결제수단으로 자동 결제가 이루어집니다.

최초 결제                   자동 결제               자동 결제
   │                          │                      │
   ▼                          ▼                      ▼
┌──────┐    1개월 후     ┌──────┐    1개월 후    ┌──────┐
│ 결제 │ ──────────────→ │ 결제 │ ────────────→ │ 결제 │ ──→ ...
└──────┘                 └──────┘               └──────┘
   │
   ├── 계약 생성
   ├── 결제수단 등록
   └── 정기결제 스케줄 등록

할부 결제 흐름

할부(installment)는 정기결제와 유사하지만, 지정된 횟수만큼 결제가 완료되면 자동으로 종료됩니다.

1회차         2회차         3회차        ...      N회차
  │             │             │                     │
  ▼             ▼             ▼                     ▼
┌──────┐    ┌──────┐    ┌──────┐              ┌──────┐
│ 결제 │ →  │ 결제 │ →  │ 결제 │  → ... →     │ 결제 │ → 계약 완료
└──────┘    └──────┘    └──────┘              └──────┘