Checkout

Checkout으로 웹사이트에서 결제를 받는 방법을 알아봅니다.

Tokenz Checkout은 온라인 결제를 안전하게 받을 수 있는 미리 구축된 결제 폼입니다. 기본 제공 기능으로 개발 시간을 줄일 수 있습니다. 고객을 Tokenz가 호스팅하는 결제 페이지로 이동시켜 결제를 받을 수 있습니다.

Checkout Session API로 Checkout을 맞춤 설정하고 추가 기능을 사용할 수 있습니다.

금액 형식: 모든 금액 값(amount 필드 등)은 각 통화의 최소 단위로 표시합니다. 통화별 정확한 형식은 지원 통화를 참고하세요.

연동 시작하기

AI 에이전트로 연동하기

Claude Code, Cursor 또는 Codex에 Tokenz MCP를 연결하면 테스트 모드 연동을 구현해 줍니다. 코드를 검토한 후 배포하세요.

claude mcp add --transport http tokenz https://mcp.tokenz.one/mcp --header "Authorization: Bearer secret_test_YOUR_KEY_HERE"

AI로 시작하기

직접 연동하기

빠른 시작 가이드를 따라 Checkout Session을 생성하고, 결제 페이지로 이동시키고, 웹훅을 처리하세요.

빠른 시작 가이드 열기

Checkout 수명 주기

고객이 웹사이트에서 상품을 선택하고 결제 버튼을 클릭합니다.
서버가 Tokenz API로 새 Checkout Session을 생성합니다.
Tokenz API가 Checkout Session을 반환합니다.
서버가 고객을 Tokenz 호스팅 결제 페이지로 이동시킵니다.
고객이 Tokenz 호스팅 결제 페이지에서 결제를 완료합니다.
Tokenz가 고객을 웹사이트로 돌려보냅니다.
Tokenz가 서버로 웹훅 이벤트를 전송합니다.
서버가 order.succeeded 이벤트를 사용하여 주문을 이행합니다.

다이어그램

Checkout Session

API로 Checkout Session을 생성하여 고객에게 표시할 결제 폼의 내용을 설정합니다. 세션을 생성한 후 고객을 url로 이동시켜 구매를 완료하게 하세요. 고객이 구매를 완료하면 주문 이벤트 웹훅을 설정하여 주문을 이행할 수 있습니다. 다음 예제는 Checkout Session 생성 방법을 보여 줍니다.

bash

curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [
      {
        "product": {
          "price": {
            "amount": 1000,
            "currency": "JPY"
          },
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/6LaDyyNBQ5Sqd1THQYxksI/ff5bce84e3864a4f826f5aed0822bd10/treasure-chest-1.png"
          ],
          "quantity": 1,
          "label": "Treasure Chest",
          "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
        }
      }
    ],
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {}
  }'

주문 합계는 항상 itemDetails의 가격으로 계산됩니다. 일부 예제의 최상위 amount는 선택 사항이지만 지정한다면 itemDetails 합계와 같아야 합니다. 다르면 요청이 거부됩니다.

세금 카테고리

정확한 세금 계산과 규정 준수를 위해 Checkout Session의 각 상품에 taxCategory 필드를 포함해야 합니다. 다음 카테고리를 지원합니다.

VIRTUAL_CURRENCY: 게임 내 화폐, 토큰 또는 가상 코인
DIGITAL_GOODS_AND_SERVICES: 게임 아이템, 다운로드 콘텐츠, 디지털 서비스 등 디지털 상품
EBOOK: 전자책 및 전자 출판물
SAAS: 서비스형 소프트웨어 구독

세금을 정확하게 처리할 수 있도록 상품 유형에 가장 적합한 카테고리를 선택하세요.

결제 수단

Tokenz 호스팅 결제 페이지에서 고객에게 제공할 결제 수단을 설정할 수 있습니다. paymentMethodKinds 필드에 지원되는 옵션을 하나 이상 지정하세요. 이 필드를 생략하거나 빈 목록을 전송하면 지원되는 모든 결제 수단이 표시됩니다.