--- title: "设置网店" description: "本指南带你搭建由 Tokenz 托管的网店,完成测试购买,接入游戏服务器,再正式上线。你不需要开发网店前端,也不需要为本例调用 Checkout Session API:玩家购买时,托管网店会打开结账页面。" source: "https://docs.tokenz.one/zh-CN/v3/checkout/webshop" api_version: "v3" locale: "zh-CN" version_status: "current" docs_stage: "prod" --- # 设置网店 本指南带你搭建由 Tokenz 托管的网店,完成测试购买,接入游戏服务器,再正式上线。你不需要开发网店前端,也不需要为本例调用 Checkout Session API:玩家购买时,托管网店会打开结账页面。 我们以售价 **480 日元** 的 **500 Gems** 为例,商品 SKU 为 `gem-pack-500`,测试玩家为 `player-42931`。购买一份后,该玩家的测试账号应增加 500 颗宝石。商品和玩家均为示例;上线前请换成你实际销售的内容,并使用真实的测试账号完成验证。 ## 开始之前 1. 登录 [Tokenz 控制台](https://dashboard.tokenz.one/zh-CN/home)。如果还没有访问权限,请联系组织管理员或 [Tokenz 支持](https://tokenz.one/zh/support)安排开通。 2. 打开组织/项目切换菜单,选择游戏所属项目。如果项目尚不存在,且你有权限,选择 **新建项目**。填写项目名称、必填的片假名名称(例如 **Example Game** 和 **サンプルゲーム**)、联系邮箱和唯一的地址标识。只有项目确实符合页面中的法律实体声明时,才勾选确认;否则请联系 Tokenz。创建项目不代表已能正式收款。 3. 将控制台切换到 **测试**。确认可以打开 **商店** > **产品**、**商店** > **网店编辑器**以及开发者设置。页面不可见或只读时,请管理员检查相应权限和网店功能是否已开通。 4. 根据需要准备 Logo 或图片。后面的服务器接入步骤需要一位开发人员,提供两个 HTTPS 处理接口:玩家验证和订单事件。第一次购买可以先使用 Tokenz 测试服务器,无需准备这两个接口。 **预期结果:** 已选中正确的游戏项目和测试模式,可以编辑商品与网店。此时不会产生实际扣款,也没有发布正式网店。 **遇到问题:** 先核对当前组织和项目,再调整权限。如果找不到项目、无法创建项目或仍无权访问,请管理员或 Tokenz 支持协助完成账号/项目设置。 测试和正式模式分别管理商品、网店内容和 Webhook 端点。网店地址由两种模式共用:在任一模式修改地址,都会同时更新另一模式的地址和结账返回地址。每次修改商品目录或端点前,都要确认模式。 ## 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/zh-CN/v3/product/import)。 如果选择用表单创建,填写同样的内容。在 **添加新方案** 中添加 **一次性** 价格方案,将默认价格设为 **480 JPY**,保存商品后再发布。确认价格方案已上架:只有商品已发布,但没有已上架价格方案时,玩家仍无法购买。 **预期结果:** 商品列表中有一件已发布的 **500 Gems**,SKU 为 `gem-pack-500`,并有显示 **480 日元** 的已上架一次性价格方案。它属于测试目录,正式目录没有变化。 **遇到问题:** 导入预览存在错误时不会写入数据,请修正指定行后重新上传。实际导入也可能报告部分失败,要检查最终结果。同一 SKU 已存在时,导入会更新该商品;不要不断换 SKU 重试。无法添加/上架价格方案或发布商品时,请管理员补齐权限。第一次购买先不设置销售时间、库存和限购。 后续启用这些限制时,也要逐一测试。按日、周、月、年重置的购买限额均以 `UTC` 为准,每周从周一开始,每年从 1 月 1 日开始。不设置重置周期时,每位玩家的购买限额不会自动重置。 ## 2. 搭建网店 1. 打开 **商店** > **网店编辑器** > **编辑网店**。项目尚无网店地址时,设置唯一地址。使用控制台显示的地址,不要自行添加 `test-` 前缀。 2. 检查英文的店铺/品牌名称和游戏名称。本测试示例分别填写 **Example Game Store** 和 **Example Game**。英语始终可用;某种语言的翻译为空时,会回退到英文。 3. 添加 Logo、颜色和需要展示的网店文字。旧网店如果仍显示 **Fantasy Studio** 或对应语言的示例公司名称,请替换为实际发行商名称,或关闭 **覆盖公司名称**。示例公司名称可能阻止启用。主视觉图、项目简介和“关于”文字均为可选项;上线前应检查准备展示的支持与政策链接。 4. 在 **玩家 ID 帮助** 中说明玩家可在游戏的哪个位置找到 ID。例如“打开设置 > 账号,复制玩家 ID”。请换成你游戏中的实际路径。添加玩家需要的语言,并检查各语言文字。 5. 依次选择 **保存更改**、**发布**。 **预期结果:** 测试网店已有保存并发布的版本。编辑器预览显示所填名称与样式。在测试中发布不会启用公开的正式网店。发布后再保存的更改仍是草稿,需要再次发布才会展示给玩家。 **遇到问题:** 按校验提示修正对应字段,优先检查英文名称和示例公司名称。地址被占用或属于保留名称时,需要更换。如果玩家预览比编辑器内容旧,请保存、发布,再重新打开预览;玩家预览读取的是已发布版本。 ## 3. 设置发货 ### 还没有服务器? **操作:** 在 **商店** > **网店编辑器** 中选择 **设置发货**。在测试模式选择 **使用 Tokenz 测试服务器**,暂不设置测试验证 URL,然后前往[进行测试购买](https://docs.tokenz.one/zh-CN/v3/checkout/webshop#make-a-test-purchase)。开发人员准备好接口后,再回到这里接入。 **预期结果:** 发货页面显示 Tokenz 测试服务器。它接受测试订单事件,但不发放游戏物品。未设置测试验证 URL 时,测试预览接受输入的接收者 ID,不进行验证。 **遇到问题:** 这个选项仅用于测试。如果已配置测试验证 URL,该服务器仍必须正常响应;订单测试服务器不会绕过已有的验证服务。请修复验证错误,或让开发人员移除该测试配置后,再体验无需自建服务器的流程。 ### 接入游戏服务器 1. 请开发人员提供接收订单事件的 HTTPS POST 处理接口,并实现[签名验证](https://docs.tokenz.one/zh-CN/v3/checkout/webhooks-get-started#3.-%E4%BF%9D%E6%8A%A4%E4%BD%A0%E7%9A%84-webhook-%E7%AB%AF%E7%82%B9)。本例中,将 SKU `gem-pack-500` 映射为测试游戏中的 500 颗宝石。 2. 在测试模式的 **发货** 页面,将接口 URL 填入 **订单发送到哪里**,选择 **保存端点**。准备改用自己的服务器时,这一步也会替换 Tokenz 测试服务器。 3. 选择 **复制设置说明**,将说明交给开发人员。复制仅显示一次的签名密钥,并单独分享。密钥应安全保存在服务器端。 4. 选择 **发送测试事件**并检查结果。探测请求要求在 5 秒内响应。这是示例事件,不是真实购买:其中的 ID 不对应真实订单,也可能没有 `recipientId`。它用于检查接收、验签和响应,不证明游戏已发放物品。 **预期结果:** 已配置自己的测试 URL,带签名的示例请求获得 2xx 响应。开发人员可以在服务器日志中找到它。实际发货仍需通过第 5 步的真实测试购买确认。 **遇到问题:** 检查 URL 能否通过公网 HTTPS 访问、接口是否接受 POST,以及是否使用本端点的测试签名密钥对未经修改的原始请求体验签。查看探测结果中的 HTTP 响应或超时信息。参见 [Webhook 故障排查](https://docs.tokenz.one/zh-CN/v3/checkout/webhooks#%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5%EF%BC%9A%E6%88%91%E7%9A%84%E7%AB%AF%E7%82%B9%E6%B2%A1%E6%9C%89%E6%94%B6%E5%88%B0%E4%BA%8B%E4%BB%B6)。 新建的发货端点默认订阅: - 订单:`order.succeeded`、`order.canceled`、`order.expired`、`order.failed`。 - 退款:`refund.created`、`refund.failed`。 - 争议:`dispute.created`、`dispute.closed`。 默认不包含 `order.created`。使用现有端点时,请在开发者设置中检查事件订阅;实际只会投递配置中的事件。 ### 读取订单并发放物品 以下为本例需要读取的字段节选,不是完整 Webhook。读取前,应先对完整的原始请求验签。实际事件 ID 和订单 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/zh-CN/v3/checkout/webhooks#%E9%87%8D%E8%AF%95%E4%B8%8E%E5%B9%82%E7%AD%89%E6%80%A7)。开发人员还可以[登记交付记录](https://docs.tokenz.one/zh-CN/v3/order),作为已完成发货的证据。 `refund.created` 表示退款申请已创建,不代表退款已成功。请确定全额/部分退款分别应收回哪些物品或权益。如果收到申请就收回,请处理 `refund.failed`,在退款失败时恢复已收回的内容。参见[退款](https://docs.tokenz.one/zh-CN/v3/refunds)。 ## 4. 验证接收者 ID 如果第一次购买使用了 Tokenz 测试服务器,请先接入自己的游戏服务器,再继续。设置玩家验证后,使用自己的服务器完成第 5 步。玩家验证 URL 和订单事件 URL 是两项独立接入,各有自己的签名密钥;即使两个接口部署在同一个应用中,也应分别配置。 1. 在测试游戏中创建玩家 `player-42931`,或统一替换为一个已存在的测试账号。购买前记下该账号的宝石余额。 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 } ``` **预期结果:** 已存在的测试玩家返回 `valid: true`,不存在的玩家返回 `valid: false`。否定结果也应通过正常的 HTTP 响应返回,不是 HTTP 错误。控制台中的探测不会创建结账,也不证明能够发放物品。 **遇到问题:** 非 2xx 响应、JSON 格式错误或非布尔值的 `valid` 都属于服务故障;超时也会阻止结账。检查验证 URL 自己的密钥和原始请求体验签逻辑。`test` 为 true 时,应查询测试玩家记录。不要返回玩家详情:Tokenz 不透传原始响应,但玩家可以得知验证结果。 正式环境中,同一商家项目下同一接收者 ID 的成功验证结果可能被复用,默认有效期为 5 分钟,可用 `validUntil` 指定截止时间。因此,账号封禁状态不一定立即反映到网店。否定结果不复用;测试模式每次都会请求你的服务器。参见[接收者 ID 验证](https://docs.tokenz.one/zh-CN/v3/checkout/webhooks#player-id-checks)。 ## 5. 进行测试购买 1. 在测试模式打开 **商店** > **网店编辑器** > **打开预览**,查看最后发布的测试网店。浏览器拦截弹窗时,使用 **复制预览链接**,再打开复制的链接。不要自行拼接测试网址,预览链接会提供访问凭据。 2. 输入 `player-42931`,选择 **500 Gems**,购买一份。尚未配置验证时,该 ID 会被直接接受;配置了验证服务后,必须通过测试游戏的玩家查询。 3. 选择银行卡,填写测试卡 **4242 4242 4242 4242**、任意 3 位 CVC 和未来的到期日期。页面如有测试结果选项,请选择成功。测试中不要使用真实银行卡。[测试卡参考](https://docs.tokenz.one/zh-CN/v3/checkout/testing#%E6%B5%8B%E8%AF%95%E5%8D%A1%E5%8F%B7)列有更多卡号;跳过该页通过 API 创建结账的步骤,因为网店已经会打开结账页面。 4. 完成支付后,保持测试模式,在 **订单** 中找到新订单,并记下订单 ID。 **预期结果:** 测试支付成功,订单显示在测试订单列表中。使用 Tokenz 测试服务器时,只能证明结账流程已跑通,游戏余额不会变化。使用自己的服务器时,应找到带签名的 `order.succeeded` 事件和该订单的发放记录。测试玩家余额必须只增加一次,增加 500 颗宝石。 **遇到问题:** **打开预览**不可用时,先发布测试网店。找不到商品或无法购买时,检查测试模式、发布状态、已上架价格方案、销售时间及库存/限购。玩家验证失败时,检查第 4 步。支付成功却未到账时,用订单 ID 对照事件投递结果和游戏发放日志。2xx 只能证明已接收事件,不代表物品已经发放。 不能根据成功页面或跳转直接发货。支付处理中,应等待 `order.succeeded` 事件,或查询并确认订单已成功;取消/失败返回页面不能触发发放。参见[订单](https://docs.tokenz.one/zh-CN/v3/order)。 付款后,结账会将玩家带回您的商店,而不是游戏。网店的返回 URL 跟随商店地址。如果您的游戏通过 API 自行创建 Checkout Session,请参阅[返回您的应用](https://docs.tokenz.one/zh-CN/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/zh/support)时,请提供项目/网店地址、模式、订单 ID(如果已生成)、大致时间和错误或 HTTP 状态。不要提供签名密钥或玩家详情。保留服务器的事件和发放日志,方便开发人员区分支付、投递和游戏处理环节的问题。