正在加载搜索…

正在加载搜索…

跳至内容
结账集成设置网店

设置网店

本指南带你搭建由 Tokenz 托管的网店,完成测试购买,接入游戏服务器,再正式上线。你不需要开发网店前端,也不需要为本例调用 Checkout Session API:玩家购买时,托管网店会打开结账页面。

我们以售价 480 日元 的 500 Gems 为例,商品 SKU 为 gem-pack-500,测试玩家为 player-42931。购买一份后,该玩家的测试账号应增加 500 颗宝石。商品和玩家均为示例;上线前请换成你实际销售的内容,并使用真实的测试账号完成验证。

开始之前

  1. 登录 Tokenz 控制台。如果还没有访问权限,请联系组织管理员或 Tokenz 支持安排开通。
  2. 打开组织/项目切换菜单,选择游戏所属项目。如果项目尚不存在,且你有权限,选择 新建项目。填写项目名称、必填的片假名名称(例如 Example Game 和 サンプルゲーム)、联系邮箱和唯一的地址标识。只有项目确实符合页面中的法律实体声明时,才勾选确认;否则请联系 Tokenz。创建项目不代表已能正式收款。
  3. 将控制台切换到 测试。确认可以打开 商店 > 产品、商店 > 网店编辑器以及开发者设置。页面不可见或只读时,请管理员检查相应权限和网店功能是否已开通。
  4. 根据需要准备 Logo 或图片。后面的服务器接入步骤需要一位开发人员,提供两个 HTTPS 处理接口:玩家验证和订单事件。第一次购买可以先使用 Tokenz 测试服务器,无需准备这两个接口。

预期结果: 已选中正确的游戏项目和测试模式,可以编辑商品与网店。此时不会产生实际扣款,也没有发布正式网店。

遇到问题: 先核对当前组织和项目,再调整权限。如果找不到项目、无法创建项目或仍无权访问,请管理员或 Tokenz 支持协助完成账号/项目设置。

测试和正式模式分别管理商品、网店内容和 Webhook 端点。网店地址由两种模式共用:在任一模式修改地址,都会同时更新另一模式的地址和结账返回地址。每次修改商品目录或端点前,都要确认模式。

1. 添加产品

为了方便复现第一个商品,将下面的内容保存为 UTF-8 编码的 products.csv。在测试模式打开 商店 > 产品,选择 导入产品并上传文件:

products.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 表示发布商品而非保存为草稿。图片、其他币种和批量商品的处理见导入产品。

如果选择用表单创建,填写同样的内容。在 添加新方案 中添加 一次性 价格方案,将默认价格设为 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,然后前往进行测试购买。开发人员准备好接口后,再回到这里接入。

预期结果: 发货页面显示 Tokenz 测试服务器。它接受测试订单事件,但不发放游戏物品。未设置测试验证 URL 时,测试预览接受输入的接收者 ID,不进行验证。

遇到问题: 这个选项仅用于测试。如果已配置测试验证 URL,该服务器仍必须正常响应;订单测试服务器不会绕过已有的验证服务。请修复验证错误,或让开发人员移除该测试配置后,再体验无需自建服务器的流程。

接入游戏服务器

  1. 请开发人员提供接收订单事件的 HTTPS POST 处理接口,并实现签名验证。本例中,将 SKU gem-pack-500 映射为测试游戏中的 500 颗宝石。
  2. 在测试模式的 发货 页面,将接口 URL 填入 订单发送到哪里,选择 保存端点。准备改用自己的服务器时,这一步也会替换 Tokenz 测试服务器。
  3. 选择 复制设置说明,将说明交给开发人员。复制仅显示一次的签名密钥,并单独分享。密钥应安全保存在服务器端。
  4. 选择 发送测试事件并检查结果。探测请求要求在 5 秒内响应。这是示例事件,不是真实购买:其中的 ID 不对应真实订单,也可能没有 recipientId。它用于检查接收、验签和响应,不证明游戏已发放物品。

预期结果: 已配置自己的测试 URL,带签名的示例请求获得 2xx 响应。开发人员可以在服务器日志中找到它。实际发货仍需通过第 5 步的真实测试购买确认。

遇到问题: 检查 URL 能否通过公网 HTTPS 访问、接口是否接受 POST,以及是否使用本端点的测试签名密钥对未经修改的原始请求体验签。查看探测结果中的 HTTP 响应或超时信息。参见 Webhook 故障排查。

新建的发货端点默认订阅:

  • 订单: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 时应排查,不能猜测接收账号。参见重试与幂等性。开发人员还可以登记交付记录,作为已完成发货的证据。

refund.created 表示退款申请已创建,不代表退款已成功。请确定全额/部分退款分别应收回哪些物品或权益。如果收到申请就收回,请处理 refund.failed,在退款失败时恢复已收回的内容。参见退款。

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 验证。

5. 进行测试购买

  1. 在测试模式打开 商店 > 网店编辑器 > 打开预览,查看最后发布的测试网店。浏览器拦截弹窗时,使用 复制预览链接,再打开复制的链接。不要自行拼接测试网址,预览链接会提供访问凭据。
  2. 输入 player-42931,选择 500 Gems,购买一份。尚未配置验证时,该 ID 会被直接接受;配置了验证服务后,必须通过测试游戏的玩家查询。
  3. 选择银行卡,填写测试卡 4242 4242 4242 4242、任意 3 位 CVC 和未来的到期日期。页面如有测试结果选项,请选择成功。测试中不要使用真实银行卡。测试卡参考列有更多卡号;跳过该页通过 API 创建结账的步骤,因为网店已经会打开结账页面。
  4. 完成支付后,保持测试模式,在 订单 中找到新订单,并记下订单 ID。

预期结果: 测试支付成功,订单显示在测试订单列表中。使用 Tokenz 测试服务器时,只能证明结账流程已跑通,游戏余额不会变化。使用自己的服务器时,应找到带签名的 order.succeeded 事件和该订单的发放记录。测试玩家余额必须只增加一次,增加 500 颗宝石。

遇到问题: 打开预览不可用时,先发布测试网店。找不到商品或无法购买时,检查测试模式、发布状态、已上架价格方案、销售时间及库存/限购。玩家验证失败时,检查第 4 步。支付成功却未到账时,用订单 ID 对照事件投递结果和游戏发放日志。2xx 只能证明已接收事件,不代表物品已经发放。

不能根据成功页面或跳转直接发货。支付处理中,应等待 order.succeeded 事件,或查询并确认订单已成功;取消/失败返回页面不能触发发放。参见订单。

付款后,结账会将玩家带回您的商店,而不是游戏。网店的返回 URL 跟随商店地址。如果您的游戏通过 API 自行创建 Checkout Session,请参阅返回您的应用。

上线前,使用自己的服务器确认以下结果:

  • 不存在的接收者 ID 返回 { "valid": false },并阻止购买。
  • 验证请求超时或返回 HTTP 500 时,购买被阻止,玩家可以重试。
  • 未发布的商品、未上架的价格方案、销售时间以外的商品,以及库存耗尽或已达购买限额的商品均无法购买。
  • 投递失败的事件会重试。重复投递同一事件不会重复发放物品;请同时核对订单记录与游戏余额。

修正与上述预期不符的行为。即使之前已通过 Tokenz 测试服务器完成购买,也要使用自己的服务器完成第 5 步。

6. 上线

操作: 将控制台切换到正式模式,打开 商店 > 网店编辑器,完成 上线 清单中的各项:

可按需左右滚动
项目操作与预期结果受阻时检查
协议必要时通过 激活账户 签署。项目适用所属组织的协议。正式收款需要 Tokenz 批准。等待审核或联系支持;签署完成不等于审核通过。
正式环境在售商品创建/导入实际销售的正式目录,发布商品并确认价格方案已上架,核对币种和金额。测试商品与正式商品分开。只有示例确实对应你计划销售的真实商品时,才将其导入正式环境。
商店从测试复制会用已发布的测试网店替换正式草稿。检查名称、文字、地址、支持/政策链接和样式。修正提示的字段,上线前替换所有示例内容。
订单端点只有自己的测试服务器也能处理正式订单时,才选择 用于正式环境;否则 设置正式 URL。复制新的正式签名密钥。Tokenz 测试服务器不能交付正式订单。共用 URL 也必须按模式使用不同密钥和数据。
接收者 ID 验证设置正式验证 URL,复制正式密钥,并用获授权的正式玩家测试。测试验证 URL 不会自动沿用;正式服务器必须查询正式玩家记录。

各项准备好后,选择 启用网店,发布正式网店。打开控制台显示的公开地址,核对正式商品、价格、语言、玩家 ID 帮助和链接。不能用测试预览来证明公开网店已经可用。

预期结果: 获授权的玩家能打开公开网店,购买预期的正式商品。如果团队要做正式验证购买,应先获得授权,使用受支持的真实支付方式,并预期产生实际扣款。测试卡只用于测试模式。像测试时一样,核对正式订单、正式事件和游戏内发放结果。

遇到问题: 公开网店、商品目录或服务器不正确时,先停止上线验证,修正正式设置并重新发布。需要停止销售时,在网店编辑器中停用网店;修改尚未发布的草稿不会改变玩家正在看到的内容。

需要帮助?

联系 Tokenz 支持时,请提供项目/网店地址、模式、订单 ID(如果已生成)、大致时间和错误或 HTTP 状态。不要提供签名密钥或玩家详情。保留服务器的事件和发放日志,方便开发人员区分支付、投递和游戏处理环节的问题。