--- title: "웹숍 설정하기" description: "Tokenz가 호스팅하는 웹숍을 만들고, 테스트 구매와 게임 서버 연동을 거쳐 라이브로 공개합니다. 이 안내에서는 스토어 화면을 개발하거나 Checkout Session API를 호출할 필요가 없습니다. 웹숍이 플레이어의 결제 화면을 엽니다." source: "https://docs.tokenz.one/ko-KR/v3/checkout/webshop" api_version: "v3" locale: "ko-KR" version_status: "current" docs_stage: "prod" --- # 웹숍 설정하기 Tokenz가 호스팅하는 웹숍을 만들고, 테스트 구매와 게임 서버 연동을 거쳐 라이브로 공개합니다. 이 안내에서는 스토어 화면을 개발하거나 Checkout Session API를 호출할 필요가 없습니다. 웹숍이 플레이어의 결제 화면을 엽니다. 예제로 **500 Gems**를 **480엔**에 판매합니다. SKU는 `gem-pack-500`, 테스트 플레이어 ID는 `player-42931`입니다. 한 팩을 구매하면 해당 테스트 계정에 보석 500개가 지급되어야 합니다. 상품과 ID는 예시이므로, 출시 전 실제 판매할 상품과 사용할 수 있는 테스트 계정으로 바꾸세요. ## 시작하기 전에 1. [Tokenz 대시보드](https://dashboard.tokenz.one/ko/home)에 로그인합니다. 접근 권한이 없으면 조직 관리자나 [Tokenz 지원팀](https://tokenz.one/ko/support)에 이용 설정을 요청하세요. 2. 조직·프로젝트 전환 메뉴에서 게임의 프로젝트를 선택합니다. 프로젝트가 없고 생성 권한이 있다면 **새 프로젝트**를 선택합니다. 프로젝트 이름, 필수 가타카나 이름(예: **Example Game**, **サンプルゲーム**), 연락처 이메일, 중복되지 않는 주소용 슬러그를 입력합니다. 법인 관련 확인 사항은 실제로 해당할 때만 확인하고, 해당하지 않으면 Tokenz에 문의하세요. 프로젝트를 만들었다고 라이브 결제가 활성화되지는 않습니다. 3. **테스트** 모드로 전환합니다. **스토어** > **상품**, **스토어** > **빌더**, 개발자 설정을 열 수 있는지 확인합니다. 페이지가 없거나 읽기 전용이라면 관리자에게 권한과 웹숍 이용 가능 여부를 확인해 달라고 요청하세요. 4. 필요하면 로고와 이미지를 준비합니다. 이후 서버 연동을 위해 플레이어 검증과 주문 이벤트를 받을 HTTPS 핸들러 두 개를 준비할 개발자를 지정합니다. 첫 구매는 핸들러 없이 Tokenz 테스트 서버로 시도할 수 있습니다. **기대 결과:** 게임 프로젝트와 테스트 모드가 선택되고, 상품과 웹숍을 편집할 수 있습니다. 실제 결제나 라이브 공개는 아직 이루어지지 않았습니다. **문제가 생기면:** 권한을 바꾸기 전에 선택한 조직과 프로젝트를 확인하세요. 프로젝트가 없거나 생성·접근할 수 없다면 관리자 또는 Tokenz 지원팀에 계정과 프로젝트 설정을 요청합니다. 상품, 웹숍 콘텐츠, 웹훅 엔드포인트는 테스트와 라이브에서 따로 관리합니다. 단, 주소는 공통입니다. 어느 모드에서 바꾸든 양쪽 주소와 결제 후 돌아갈 URL이 함께 변경됩니다. 상품이나 엔드포인트를 바꾸기 전에 모드를 확인하세요. ## 1. 상품 추가하기 첫 상품을 같은 조건으로 만들려면 다음 내용을 UTF-8 파일 `products.csv`로 저장합니다. 테스트에서 **스토어** > **상품**의 **상품 가져오기**를 선택해 업로드합니다. ```csv sku,name,description,price,currency,taxCategory,publish gem-pack-500,500 Gems,Adds 500 gems to your game account.,480,JPY,virtualCurrency,true ``` 미리보기에서 오류를 수정한 뒤 **가져오기**를 선택합니다. SKU는 상품 식별자이고 이름은 플레이어에게 표시됩니다. 가격은 엔 단위의 480, 세금 분류는 게임 내 재화이며, `publish`는 초안 대신 게시된 상태로 만들라는 뜻입니다. 이미지, 다른 통화, 대규모 카탈로그는 [상품 가져오기](https://docs.tokenz.one/ko-KR/v3/product/import)를 참고하세요. 입력 양식으로 만든다면 같은 값을 사용하세요. **새 플랜 추가**에서 **일회성** 플랜을 추가하고 기본 가격을 **480 JPY**로 설정한 뒤 상품을 저장하고 게시합니다. 가격 플랜도 판매 중이어야 합니다. 상품이 게시되어 있어도 판매 중인 플랜이 없으면 구매할 수 없습니다. **기대 결과:** 테스트 상품 목록에 SKU `gem-pack-500`인 **500 Gems**가 게시되고, 판매 중인 일회성 플랜의 가격이 **480엔**으로 표시됩니다. 라이브 카탈로그는 바뀌지 않습니다. **문제가 생기면:** 미리보기에 오류가 있으면 아무것도 가져오지 않습니다. 해당 행을 고쳐 다시 업로드하세요. 실행 결과에도 개별 실패가 없는지 확인합니다. 같은 SKU가 있으면 기존 상품을 업데이트하므로 새 SKU를 계속 만들어 재시도하지 마세요. 플랜 추가·판매 설정·게시 권한이 없다면 관리자에게 요청합니다. 첫 구매에서는 판매 기간, 재고, 구매 한도를 설정하지 마세요. 나중에 한도를 설정하면 해당 동작도 테스트하세요. 일별·주별·월별·연간 한도는 `UTC` 기준으로 초기화되며, 주는 월요일, 연도는 1월 1일에 시작합니다. 초기화 주기가 없는 플레이어별 한도는 자동으로 초기화되지 않습니다. ## 2. 숍 만들기 1. **스토어** > **빌더** > **웹숍 편집**을 엽니다. 주소가 없다면 중복되지 않는 주소를 설정합니다. 대시보드에 표시된 주소를 사용하고 직접 `test-`를 붙이지 마세요. 2. 영어 스토어·브랜드 이름과 영어 게임 이름을 확인합니다. 이 테스트에서는 **Example Game Store**, **Example Game**을 사용합니다. 영어는 항상 제공되며 번역이 비어 있을 때 대신 표시됩니다. 3. 로고, 색상, 필요한 문구를 추가합니다. 기존 설정에 **Fantasy Studio**나 번역된 샘플 회사명이 남아 있으면 실제 퍼블리셔 이름으로 바꾸거나 **회사 이름 재정의**를 끕니다. 샘플 회사명 때문에 활성화가 차단될 수 있습니다. 대표 이미지, 프로젝트 개요, 소개 문구는 선택 사항입니다. 출시 전 표시할 지원·정책 링크도 확인하세요. 4. **플레이어 ID 도움말**에 게임에서 ID를 찾는 방법을 적습니다. 예: “설정 > 계정을 열고 플레이어 ID를 복사하세요.” 실제 게임의 경로로 바꾸고 필요한 언어별 문구를 확인합니다. 5. **변경사항 저장** 후 **게시**를 선택합니다. **기대 결과:** 테스트 웹숍이 저장·게시되고 편집기 미리보기에 설정한 이름과 디자인이 표시됩니다. 테스트 게시는 라이브 웹숍을 활성화하지 않습니다. 게시 후 저장한 변경은 다시 게시할 때까지 초안입니다. **문제가 생기면:** 오류에 표시된 필드를 수정합니다. 영어 이름과 샘플 회사명부터 확인하세요. 사용 중이거나 예약된 주소라면 다른 슬러그가 필요합니다. 구매자 미리보기가 예전 내용이면 저장·게시한 뒤 다시 엽니다. 미리보기는 게시된 버전을 표시합니다. ## 3. 주문 이행 설정하기 ### 아직 서버가 없나요? **작업:** **스토어** > **빌더**에서 **주문 이행 설정**을 선택합니다. 테스트에서 **Tokenz 테스트 서버 사용**을 선택하고 테스트 검증 URL은 설정하지 않은 채 [테스트 구매하기](https://docs.tokenz.one/ko-KR/v3/checkout/webshop#make-a-test-purchase)로 이동합니다. 개발자의 핸들러가 준비되면 돌아오세요. **기대 결과:** 주문 이행 페이지에 Tokenz 테스트 서버가 표시됩니다. 테스트 주문 이벤트를 받지만 게임 아이템은 지급하지 않습니다. 테스트 검증 URL이 없으면 입력한 ID도 검증 없이 받아들입니다. **문제가 생기면:** 이 방법은 테스트 전용입니다. 테스트 검증 URL이 이미 있다면 해당 서버가 응답해야 합니다. 주문 테스트 서버가 검증을 우회하지는 않습니다. 검증 오류를 해결하거나 개발자에게 테스트 검증 설정을 제거해 달라고 요청한 뒤 다시 시도하세요. ### 게임 서버 연결하기 1. 개발자에게 주문 이벤트용 HTTPS POST 핸들러와 [서명 검증](https://docs.tokenz.one/ko-KR/v3/checkout/webhooks-get-started#3.-secure-your-webhook-endpoint)을 구현해 달라고 요청합니다. 테스트 게임에서 SKU `gem-pack-500`을 보석 500개에 연결합니다. 2. 테스트 **주문 이행** 페이지의 **주문을 보낼 곳**에 URL을 입력하고 **엔드포인트 저장**을 선택합니다. Tokenz 테스트 서버도 이 주소로 대체됩니다. 3. **설정 요약 복사**를 선택해 내용을 개발자에게 전달합니다. 한 번만 표시되는 서명 시크릿을 복사해 별도로 공유하세요. 시크릿은 서버에 안전하게 보관합니다. 4. **테스트 이벤트 보내기**로 결과를 확인합니다. 응답 제한은 5초입니다. 실제 구매가 아닌 샘플이므로 ID가 실제 주문을 가리키지 않으며 `recipientId`가 없을 수도 있습니다. 수신·서명·응답 확인용이며 아이템 지급을 증명하지 않습니다. **기대 결과:** 자체 테스트 URL이 설정되고 서명된 샘플 요청에 2xx가 반환됩니다. 개발자가 서버 로그에서 확인할 수 있습니다. 실제 지급 확인에는 5단계의 테스트 구매가 필요합니다. **문제가 생기면:** 외부에서 HTTPS로 접근 가능한지, POST를 받는지, 이 엔드포인트의 테스트 시크릿과 변경하지 않은 원본 본문으로 서명을 확인하는지 점검합니다. 테스트 결과의 HTTP 응답·시간 초과를 확인하고 [웹훅 문제 해결](https://docs.tokenz.one/ko-KR/v3/checkout/webhooks#%EB%AC%B8%EC%A0%9C-%ED%95%B4%EA%B2%B0:-%EC%9D%B4%EB%B2%A4%ED%8A%B8%EA%B0%80-%EC%88%98%EC%8B%A0%EB%90%98%EC%A7%80-%EC%95%8A%EB%8A%94-%EA%B2%BD%EC%9A%B0)을 참고하세요. 새 주문 이행 엔드포인트는 다음 이벤트를 구독합니다. - 주문: `order.succeeded`, `order.canceled`, `order.expired`, `order.failed`. - 환불: `refund.created`, `refund.failed`. - 분쟁: `dispute.created`, `dispute.closed`. `order.created`는 기본으로 포함되지 않습니다. 기존 엔드포인트는 개발자 설정에서 구독 목록을 확인하세요. 설정한 이벤트만 전송됩니다. ### 주문을 읽고 아이템 지급하기 다음은 이 예제에 필요한 필드만 발췌한 것이며 전체 웹훅이 아닙니다. 읽기 전에 전체 요청의 원본 본문으로 서명을 확인하세요. 실제 이벤트·주문 ID는 Tokenz가 생성하므로 예제 ID를 고정값으로 사용하지 마세요. ```json { "id": "2d8419f0-81fa-4e04-bb39-5cf95efa829a", "object": "order.succeeded", "test": true, "eventData": { "type": "order", "version": "v3", "data": { "order": { "id": "order_example_t", "recipientId": "player-42931", "items": [ { "detail": { "product": { "sku": "gem-pack-500", "quantity": 1 } } } ] } } } } ``` | 읽을 값 | 용도 | | --- | --- | | 최상위 `id` | 중복 전송을 걸러냅니다. 이벤트를 영구 저장한 뒤 2xx로 응답하고 비동기로 처리합니다. | | `eventData.data.order.id` | 주문을 게임 지급 처리·로그와 연결합니다. | | `eventData.data.order.recipientId` | 플레이어가 입력한 수령인 ID입니다. 테스트 플레이어 `player-42931`을 찾습니다. 이벤트 ID나 SKU로 플레이어를 추측하지 마세요. | | 각 아이템의 `detail.product.sku`와 `detail.product.quantity` | `gem-pack-500` 한 팩당 500개를 지급합니다. 수량 1은 500개, 수량 2는 1,000개입니다. | 같은 이벤트가 재전송되어도 다시 지급하지 마세요. 백그라운드 작업을 재시도해도 중복되지 않도록 게임 지급과 완료 기록의 일관성을 유지합니다. 알 수 없는 SKU나 누락된 `recipientId`는 조사하고 수신자를 추측하지 마세요. [재시도와 멱등성](https://docs.tokenz.one/ko-KR/v3/checkout/webhooks#%EC%9E%AC%EC%8B%9C%EB%8F%84%EC%99%80-%EB%A9%B1%EB%93%B1%EC%84%B1)을 참고하세요. 개발자는 이행 증거로 [배송 기록을 등록](https://docs.tokenz.one/ko-KR/v3/order)할 수도 있습니다. `refund.created`는 환불 요청이며 성공을 뜻하지 않습니다. 전액·부분 환불에서 회수할 아이템이나 권한을 정하세요. 요청 시 회수한다면 `refund.failed`로 환불 실패 시 복구해야 합니다. [환불](https://docs.tokenz.one/ko-KR/v3/refunds)을 참고하세요. ## 4. 수령인 ID 확인하기 첫 구매에 Tokenz 테스트 서버를 사용했다면 자체 게임 서버를 연결한 뒤 계속하세요. 플레이어 검증을 설정한 후 자체 서버로 5단계를 진행합니다. 검증 URL과 주문 이벤트 URL은 별도 연동이며 같은 앱에서 호스팅해도 서명 시크릿은 서로 다릅니다. 1. 테스트 게임에 `player-42931`을 만들거나 모든 예제 ID를 기존 테스트 계정으로 바꿉니다. 구매 전 보석 잔액을 기록합니다. 2. HTTPS POST 검증 핸들러를 준비합니다. 검증 시크릿으로 `Tokenz-Signature`를 확인하고 테스트 게임의 플레이어 기록에서 ID를 조회해 3초 안에 JSON 판정을 반환해야 합니다. 3. 테스트에서 **설정** > **개발자** > **사용자 검증**, 또는 주문 이행의 **사용자 검증 열기**에서 **검증 설정**을 선택하고 URL을 저장합니다. 한 번만 표시되는 시크릿을 복사합니다. 4. **테스트 검증 보내기**로 `player-42931`과 존재하지 않는 ID(예: `player-missing`)를 각각 시험합니다. 검증 요청의 예입니다. ```json { "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34", "object": "user.validation", "createdAt": "2026-07-22T09:15:00Z", "test": true, "credentials": { "type": "recipientId", "recipientId": "player-42931" } } ``` HTTP `200`과 알맞은 판정을 반환합니다. ```json { "valid": true } ``` ```json { "valid": false } ``` **기대 결과:** 존재하는 ID는 `valid: true`, 없는 ID는 `valid: false`입니다. 부정 판정도 정상 HTTP 응답이며 HTTP 오류가 아닙니다. 대시보드 테스트는 결제를 만들거나 아이템 지급을 증명하지 않습니다. **문제가 생기면:** 2xx가 아닌 응답, 잘못된 JSON, 불리언이 아닌 `valid`는 서비스 장애이며 시간 초과도 결제를 차단합니다. 검증 URL 전용 시크릿과 원본 본문으로 서명을 확인하는지 점검하세요. `test`가 true이면 테스트 기록을 사용합니다. 플레이어 상세 정보는 반환하지 마세요. Tokenz는 원본 응답을 전달하지 않지만 플레이어는 판정 결과를 알 수 있습니다. 라이브에서는 같은 판매자 프로젝트의 같은 수령인 ID에 대한 성공 결과를 기본 5분간 재사용할 수 있습니다. 선택 항목인 `validUntil`로 기한을 정할 수 있어 계정 차단이 웹숍에 즉시 반영되지 않을 수 있습니다. 부정 판정은 재사용하지 않으며 테스트에서는 매번 서버를 호출합니다. [수령인 ID 검증](https://docs.tokenz.one/ko-KR/v3/checkout/webhooks#player-id-checks)을 참고하세요. ## 5. 테스트 구매하기 1. 테스트에서 **스토어** > **빌더** > **미리보기 열기**를 선택합니다. 마지막으로 게시한 테스트 웹숍이 열립니다. 팝업이 차단되면 미리보기 링크를 복사해 엽니다. 접근 정보가 포함된 링크이므로 테스트 URL을 직접 만들지 마세요. 2. `player-42931`을 입력하고 **500 Gems** 한 팩을 구매합니다. 검증을 설정하지 않았다면 ID는 확인 없이 허용됩니다. 검증이 있다면 테스트 게임 조회에 통과해야 합니다. 3. 카드 결제를 선택하고 테스트 카드 **4242 4242 4242 4242**, 임의의 3자리 CVC, 미래 만료일을 입력합니다. 결과 선택기가 나오면 성공을 선택합니다. 테스트에 실제 카드를 쓰지 마세요. [테스트 카드 목록](https://docs.tokenz.one/ko-KR/v3/checkout/testing#test-card-numbers)에서 다른 번호를 확인할 수 있습니다. 웹숍이 결제를 열므로 해당 페이지의 API 세션 생성 단계는 건너뜁니다. 4. 결제를 마친 뒤 테스트의 **주문**에서 새 주문을 찾아 주문 ID를 기록합니다. **기대 결과:** 테스트 결제가 성공하고 테스트 주문에 표시됩니다. Tokenz 테스트 서버에서는 결제 흐름만 확인되며 게임 잔액은 변하지 않습니다. 자체 서버에서는 서명된 `order.succeeded`와 해당 주문의 지급 기록을 찾습니다. 잔액이 정확히 한 번 500개 늘어나야 합니다. **문제가 생기면:** 미리보기를 열 수 없으면 먼저 테스트를 게시합니다. 상품이 없거나 구매할 수 없다면 테스트 모드, 게시 상태, 판매 중인 가격 플랜, 기간, 재고·한도를 확인합니다. ID 검증 실패는 4단계, 결제 후 보석이 오지 않으면 주문 ID·이벤트 전송 결과·지급 로그를 비교합니다. 2xx는 수신만 증명하며 지급 성공은 증명하지 않습니다. 성공 화면이나 리디렉션만 보고 지급하지 마세요. 보류 중인 결제는 확정 성공을 기다리고 취소·실패 복귀로 지급해서는 안 됩니다. `order.succeeded` 또는 조회한 주문의 확정 상태를 사용합니다. [주문](https://docs.tokenz.one/ko-KR/v3/order)을 참고하세요. 결제가 끝나면 Checkout은 플레이어를 게임이 아닌 상점으로 돌려보냅니다. 웹숍의 복귀 URL은 상점 주소를 따릅니다. 게임에서 API로 Checkout Session을 직접 생성하는 경우 [앱으로 돌아가기](https://docs.tokenz.one/ko-KR/v3/checkout/get-started#return-to-your-app)를 참고하세요. 라이브로 공개하기 전에 자체 서버로 다음 결과를 확인하세요. - 존재하지 않는 수령인 ID에는 `{ "valid": false }`를 반환하고 구매를 차단합니다. - 검증 요청이 시간 초과되거나 HTTP `500`을 반환하면 구매를 차단하고 플레이어가 다시 시도할 수 있게 합니다. - 게시되지 않은 상품, 판매 중이 아닌 가격 플랜, 판매 기간이 시작되지 않았거나 종료된 상품, 재고가 없거나 구매 한도에 도달한 상품은 구매할 수 없습니다. - 전송에 실패한 이벤트는 재전송됩니다. 같은 이벤트가 다시 전송되어도 아이템이 중복 지급되지 않는지 주문 기록과 게임 잔액으로 확인합니다. 이 결과와 다르게 동작하는 부분을 수정하세요. Tokenz 테스트 서버로 구매에 성공했어도 자체 서버로 5단계를 진행합니다. ## 6. 라이브 시작하기 **작업:** 라이브로 전환해 **스토어** > **빌더**를 열고 **라이브 시작**의 각 항목을 완료합니다. | 항목 | 작업과 기대 결과 | 진행할 수 없다면 | | --- | --- | --- | | 계약 | 필요하면 **계정 활성화**에서 서명합니다. 프로젝트에는 조직의 계약이 적용되며 라이브 결제에는 Tokenz 승인이 필요합니다. | 검토를 기다리거나 지원팀에 문의합니다. 서명만으로 승인되지는 않습니다. | | 라이브 판매 상품 | 실제 상품을 생성·가져오기한 뒤 게시하고 판매 중인 플랜, 통화, 금액을 확인합니다. | 테스트 상품은 별도입니다. 실제로 판매할 상품인 경우에만 예제를 가져오세요. | | 숍 | **테스트에서 복사**는 게시된 테스트 웹숍으로 라이브 초안을 바꿉니다. 이름, 문구, 주소, 지원·정책 링크, 디자인을 확인합니다. | 지적된 필드를 고치고 게시 전에 예제 콘텐츠를 교체합니다. | | 주문 엔드포인트 | 자체 테스트 서버가 라이브도 처리할 때만 **라이브에도 사용**을 선택하고, 아니면 라이브 URL을 **설정**합니다. 새 라이브 시크릿을 복사합니다. | Tokenz 테스트 서버는 라이브 주문을 이행하지 못합니다. 같은 URL이어도 모드별 시크릿과 데이터 처리가 필요합니다. | | 수령인 ID 확인 | 라이브 검증 URL과 시크릿을 설정하고 이용이 허용된 라이브 플레이어로 테스트합니다. | 테스트 URL은 이어받지 않습니다. 라이브 데이터로 확인해야 합니다. | 준비되면 **웹숍 활성화**를 선택합니다. 라이브 웹숍이 게시됩니다. 대시보드의 공개 주소에서 상품·가격·언어·ID 도움말·링크를 확인하세요. 테스트 미리보기로 공개 여부를 판단하지 마세요. **기대 결과:** 이용 가능한 플레이어가 공개 웹숍에서 의도한 라이브 상품을 구매할 수 있습니다. 팀에서 라이브 확인 구매를 한다면 승인을 받고 실제 지원 결제 수단을 사용하세요. 실제 금액이 청구됩니다. 테스트 카드는 테스트 전용입니다. 테스트처럼 라이브 주문·이벤트·게임 지급까지 확인합니다. **문제가 생기면:** 공개 웹숍·상품이나 서버가 잘못되었다면 확인 구매를 중단합니다. 라이브 설정을 고쳐 다시 게시하세요. 판매를 중단하려면 빌더에서 웹숍을 비활성화합니다. 게시하지 않은 초안을 편집해도 플레이어에게 보이는 내용은 바뀌지 않습니다. ## 도움이 필요하신가요? [Tokenz 지원팀](https://tokenz.one/ko/support)에 프로젝트·웹숍 주소, 모드, 주문 ID(있는 경우), 대략적인 시간, 오류나 HTTP 상태를 알려 주세요. 서명 시크릿이나 플레이어 상세 정보는 보내지 마세요. 개발자가 결제·이벤트 전송·게임 처리 중 어디서 실패했는지 구분할 수 있도록 이벤트와 지급 로그를 보관합니다.