웹숍 설정하기

Tokenz 웹숍은 Tokenz가 호스팅하는 게임 스토어입니다. 플레이어는 그곳에서 아이템을 구매하고, Tokenz가 결제를 처리하며, 게임 서버가 아이템을 지급합니다. 스토어프론트를 직접 만들 필요 없이 대시보드에서 숍을 만듭니다.

먼저 테스트 모드에서 모든 것을 설정하고 테스트 구매를 해 보세요. 그런 다음 하나의 체크리스트로 라이브를 시작합니다. 숍과 주문 엔드포인트는 테스트에서 복사하고, 상품과 플레이어 ID 확인은 라이브에서 다시 설정합니다.

시작하기 전에

대시보드 오른쪽 위의 스위치로 테스트와 라이브를 전환합니다. 테스트와 라이브는 상품, 숍, 웹훅 엔드포인트를 따로 관리하므로, 테스트에서 설정해도 라이브 숍은 바뀌지 않습니다. 테스트 구매에는 테스트 카드를 사용하며 실제로 청구되지 않습니다.

게임 서버는 웹숍을 위해 두 가지 일을 합니다.

주문 전달. Tokenz는 결제된 주문을 서버의 엔드포인트로 보내고, 서버가 아이템을 지급합니다.
플레이어 ID 확인. 플레이어가 결제하기 전에 Tokenz는 입력된 플레이어 ID가 존재하는지 서버에 묻습니다. 그래서 아이템이 실제 계정에 전달됩니다.

서버가 이 두 가지를 준비하기 전에도 숍을 시험해 볼 수 있습니다. 아직 서버가 없나요?를 참고하세요.

1. 상품 추가하기

테스트 모드로 전환하고 스토어 > 상품을 엽니다. 아이템을 하나씩 만들거나 파일에서 카탈로그를 가져옵니다. 상품 가져오기를 참고하세요.

게시한 상품이 숍에서 판매됩니다. 초안은 숍에 표시되지 않습니다.

2. 숍 만들기

스토어 > 빌더를 열고 웹숍 편집을 선택합니다. 숍 주소를 정한 다음, 판매하는 각 언어로 로고, 색상, 텍스트를 추가합니다. 편집기 옆의 미리보기에 플레이어가 보게 될 숍이 표시됩니다.

플레이어는 결제하기 전에 플레이어 ID를 입력합니다. 플레이어 ID 도움말에 게임에서 ID가 표시되는 위치를 한두 문장으로 적어 주세요. 스크린샷이 있으면 더 좋습니다. 플레이어는 플레이어 ID 입력란의 도움말 아이콘에서 이 내용을 엽니다.

숍이 준비되면 게시를 선택합니다. 테스트에서 게시해도 숍이 공개되지는 않으며, 테스트 구매를 할 수 있는 상태가 됩니다.

3. 주문 이행 설정하기

스토어 > 빌더에서 주문 이행 설정을 선택합니다. 주문 이행 페이지에서 주문이 게임 서버에 도착하는 방법을 설정합니다.

주문을 보낼 곳에 주문을 받을 서버의 HTTPS 주소를 입력하고 엔드포인트 저장을 선택합니다.
서명 시크릿을 복사합니다. Tokenz는 엔드포인트를 저장할 때 한 번만 보여 줍니다. 서버는 이 시크릿으로 각 주문이 Tokenz에서 왔는지 확인합니다. 웹훅 엔드포인트 보호하기를 참고하세요.
테스트 이벤트 보내기를 선택합니다. Tokenz가 결제된 샘플 주문을 보내며, 서버는 5초 안에 응답해야 합니다.

엔드포인트는 모든 주문, 환불, 분쟁 이벤트를 받습니다. 결제된 주문은 order.succeeded 이벤트로 도착하며, playerId에 플레이어가, 아이템 목록에 SKU가 담깁니다. 해당 플레이어에게 아이템을 지급하고, refund.created를 받으면 회수하세요. 이벤트 설명은 웹훅에 있습니다.

다른 사람이 엔드포인트를 만든다면 개발자에게 전달에서 설정 요약 복사를 선택하세요. 요약에는 엔드포인트, 받는 이벤트, 상품과 샘플 주문이 들어 있습니다. 서명 시크릿은 빠져 있으니 따로 보내 주세요.

아직 서버가 없나요?

테스트 모드에서는 주문 이행 페이지에 Tokenz 테스트 서버 사용이 표시됩니다. 테스트 서버는 모든 테스트 주문을 받아들이고 게임에는 아무것도 전달하지 않습니다. 테스트 검증 URL을 설정하기 전까지는 테스트 미리보기도 입력한 플레이어 ID를 검증하지 않고 받아들입니다. 그래서 서버 코드를 작성하기 전에 테스트 구매를 할 수 있습니다. 서버가 준비되면 그 주소를 대신 입력하세요.

4. 플레이어 ID 확인하기

Tokenz는 주문을 받는 엔드포인트와 별도로, 서버의 검증 URL에서 플레이어 ID를 확인합니다. 설정 > 개발자 > 사용자 검증을 열거나, 주문 이행 페이지에서 사용자 검증 열기를 선택하세요. 테스트와 라이브는 각각 자체 URL과 서명 시크릿이 있으므로 먼저 테스트 모드에서 설정합니다.

검증 설정을 선택하고 서버의 HTTPS 주소를 입력한 뒤 저장합니다.
서명 시크릿을 복사합니다. 서명 시크릿은 생성될 때 한 번만 표시됩니다.
실제 플레이어 ID를 입력하고 테스트 검증 보내기를 선택해 서버가 응답하는지 확인합니다.

그러면 플레이어가 ID를 입력할 때 결제 전에 Tokenz가 그 ID를 담은 user.validation 요청을 이 URL로 보냅니다. 라이브 URL이 true로 응답한 뒤에는 Tokenz가 몇 분 동안 그 응답을 재사용하고 서버를 호출하지 않을 수 있으므로, 계정을 즉시 차단하는 수단으로 이 검증에 의존하지 마세요. 응답 재사용을 참조하세요. 테스트 URL을 설정하기 전까지는 테스트 미리보기가 모든 플레이어 ID를 받아들이므로, 서버가 응답할 수 있을 때 설정하세요.

json

{
  "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34",
  "object": "user.validation",
  "createdAt": "2026-07-22T09:15:00Z",
  "test": true,
  "credentials": { "type": "playerId", "playerId": "player-42931" }
}

HTTP 200과 플레이어 존재 여부로 응답합니다.

json

{ "valid": true }

플레이어가 있든 없든 200을 반환하세요. Tokenz는 다른 상태 코드를 장애로 보며, 플레이어는 구매할 수 없습니다.
3초 안에 응답하세요. 응답이 없으면 플레이어는 결제할 수 없고 다시 시도하라는 안내를 받습니다.
valid만 반환하세요. ID를 입력한 사람은 누구나 응답을 읽을 수 있으니 플레이어에 관한 다른 정보는 보내지 마세요.
test가 true이면 테스트 플레이어와 대조하세요.
주문과 마찬가지로 Tokenz-Signature 헤더를 검증하되, 검증 URL의 서명 시크릿을 사용하세요.

요청과 응답의 자세한 내용은 플레이어 ID 검증을 참조하세요.

5. 테스트 구매하기

스토어 > 빌더에서 미리보기 열기를 선택합니다. 테스트에서 마지막으로 게시한 숍이 열립니다. 테스트 카드로 아이템을 구매하고 서버가 아이템을 지급했는지 확인하세요. 대시보드가 테스트 모드일 때 주문은 주문에도 표시됩니다.

6. 라이브 시작하기

대시보드를 라이브로 전환하고 스토어 > 빌더를 엽니다. 라이브 시작 목록에 라이브에 아직 필요한 항목이 각각의 버튼과 함께 표시됩니다.

필요하면 좌우로 스크롤하세요

항목	할 일
계약	페이지 위쪽의 계정 활성화에서 서명합니다. 라이브 결제가 시작되기 전에 Tokenz가 계약을 확인합니다. 프로젝트는 조직의 계약으로 처리됩니다.
라이브 판매 상품	라이브에는 별도의 상품이 있습니다. 상품 추가를 선택해 라이브에서 다시 만들거나 가져옵니다.
숍	테스트에서 복사를 선택하면 라이브 초안이 테스트에서 게시한 숍으로 바뀝니다.
주문 엔드포인트	테스트 주문을 자체 서버로 보내고 있다면 라이브에도 사용을 선택해 라이브 주문도 그 서버로 보냅니다. 라이브에는 별도의 서명 시크릿이 있으며 한 번만 표시됩니다. 그렇지 않으면 설정을 선택하고 서버 주소를 입력합니다.
플레이어 ID 확인	라이브에는 자체 검증 URL이 있습니다. 설정을 선택해 라이브의 사용자 검증을 열고, 서버 주소를 입력한 뒤 라이브 서명 시크릿을 복사합니다.

모든 항목이 준비되면 웹숍 활성화를 사용할 수 있습니다. 활성화하면 라이브 숍이 게시되고, 플레이어는 숍 주소로 접속할 수 있습니다.

도움이 필요하신가요?

Tokenz 지원팀에 문의하고 숍 주소를 알려 주세요.