Checkout Session 생성

Tokenz 상품 카탈로그의 가상 아이템과 번들로 Checkout Session을 생성하는 방법을 알아봅니다.

개요

Tokenz 대시보드에서 가상 아이템과 번들을 관리할 수 있습니다. 등록한 상품의 ID를 지정해 API로 Checkout Session을 생성할 수 있습니다.

사전 준비

상품 항목으로 Checkout Session을 생성하기 전에 다음을 준비하세요.

비밀 키: Tokenz 대시보드에서 연동에 사용할 비밀 키를 준비하세요.
상품 설정: Tokenz 대시보드에서 가상 아이템 또는 번들을 생성하세요.
상품 ID: 사용할 아이템 ID(virtualitem_xxx, bundle_xxx 형식)를 확인하세요. 상품 ID는 Product API로 조회할 수 있습니다.

상품 항목으로 Checkout Session 생성

가상 아이템 사용

Checkout Session 생성 시 상품 ID로 가상 아이템을 직접 참조할 수 있습니다. 가격과 상품 정보는 상품 설정에서 자동으로 가져옵니다.

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "virtualItem":{
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 2
        }
      },
      {
        "virtualItem":{
          "id": "virtualitem_3yB8CmLgwI8",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "en_US"
  }'

번들 사용

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "en_US"
  }'

아이템과 번들 혼합

하나의 Checkout Session에 가상 아이템과 번들을 함께 포함할 수 있습니다.

bash

curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      },
      {
        "virtualItem": {
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 3
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel"
  }'

구현 예제

javascript

import fetch from 'node-fetch';

async function createCheckoutSession() {
  const response = await fetch('https://api.tokenz.one/v1/checkoutsession', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TOKENZ_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      itemDetails: [
        {
          virtualItem: {
            id: "virtualitem_5xA9BnKfvH7",
            quantity: 2
          }
        }
      ],
      successUrl: "https://yourdomain.com/success",
      pendingUrl: "https://yourdomain.com/pending",
      cancelUrl: "https://yourdomain.com/cancel",
      locale: "en_US"
    })
  });

  const session = await response.json();

  // Redirect user to checkout
  return session.url;
}

응답

API는 Checkout Session 객체를 반환합니다.

json

{
  "id": "checkoutsession_12345678QsZ",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/12345678QsZ",
  "cancelUrl": "https://yourdomain.com/cancel",
  "pendingUrl": "https://yourdomain.com/pending",
  "successUrl": "https://yourdomain.com/success",
  "order": {
    "id": "order_1xdzo1aZRGB",
    "object": "order",
    "status": "requiresPayment",
    "amount": {
      "amount": 900,
      "currency": "JPY"
    },
    "items": [
      {
        "id": "item_1xdzo1ZpRcT",
        "detail": {
          "product": {
            "price": {
              "amount": 450,
              "currency": "JPY"
            },
            "quantity": 2,
            "label": "Mana Potion",
            "description": "",
            "images": [
              "https://images.ctfassets.net/z82qbo7cv7ia/2JyshO1smpYQwi0my9Rtif/f7df805472f4a1a0bf4e295afe9378a7/mana-potion.png"
            ],
            "sku": "mana-potion-450",
            "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
          }
        }
      }
    ],
    "test": true,
    "createdAt": "2025-09-22T04:32:04.696Z",
    "updatedAt": "2025-09-22T04:32:04.696Z"
  },
  "createdAt": "2025-09-22T04:32:04.374Z",
  "updatedAt": "2025-09-22T04:32:04.374Z",
  "test": true,
  "customerInfo": {},
  "locale": "en_US",
  "preferApplePay": false,
  "preferGooglePay": false
}

권장 사항

아이템 ID 검증: 세션 생성 전 상품 아이템 ID가 존재하는지 항상 확인하세요.
오류 처리: 유효하지 않거나 판매 중단된 아이템을 적절하게 처리하세요.
웹훅 사용: 결제 상태 업데이트를 실시간으로 받도록 설정하세요.
충분한 테스트: 운영 전 테스트 모드로 연동을 검증하세요.

다음 단계

결제 확인을 처리하도록 웹훅 설정
테스트 모드로 연동 테스트
대시보드에서 거래 모니터링