IAP游戏

1. IAP 是什么

IAP 是 In-App Purchase，也就是游戏内购买。

在 TapTap 小游戏场景下，IAP 现已支持「TapTap 点券」和「直购」两种支付方式。开发者在后台配置商品价格时，仍然按人民币金额录入；涉及点券展示时，当前换算比例为 1 元人民币 = 10 TapTap 点券。客户端在游戏内发起支付，TapTap 收银台完成支付流程，游戏服务端再负责验签、发货和查单。

请注意，本文档中的 IAP 说明仅适用于普通 TapTap 小游戏，不适用于创意工坊和 TapTap 制造游戏。

2. 你会获得哪些能力

• 后台商品管理：在开发者后台配置和管理商品信息。
• 客户端支付拉起：在小游戏中调用支付 API 发起购买。
• 服务端签名与发货：实现服务端签名和发货回调处理。
• 订单状态查询：查询订单状态，用于排查异常订单。
• 沙箱环境测试：在正式上线前完成沙箱环境下的支付流程测试。

3. 接入前需要先准备什么

上传游戏资质

接入 IAP 的 TapTap 小游戏必须具备《网络游戏出版物号核发单》，并已经在 开发者中心 >> 商店 >> 资质与审核 >> 游戏资质 上传对应资质证明。

申请白名单权限

请通过工单系统联系 TapTap 运营团队，申请开通小游戏 IAP 权限。运营团队将对游戏资质进行审核，评估通过后将为游戏开通 IAP 功能权限。

完善财务信息

权限开通后，内购功能暂不对外生效，需先完成财务认证。

• 进入 开发者中心 >> 厂商 >> 财务与管理。
• 按照要求填写企业财务信息并提交审核。
• 审核通过后，内购功能方可正式对用户启用。

4. 一条完整的 IAP 接入链路

后台开通与基础配置

• 进入路径：开发者后台 >> 商店 >> 游戏包体管理 >> 小游戏管理 >> 开放能力 >> 小游戏内购。
• 获得权限后，请先在开发者中心完成 IAP 基础配置。
• URL：接收支付结果回调通知的服务器地址，必须符合 https:// 协议格式。
• Token：开发者自定义的验证票据，用于生成签名，需符合系统规定的字符要求。
• EncodingAESKey：消息加密密钥，用于回调数据的加密与解密。
• 消息加密方式：根据开发需求选择明文或加密模式。
• 配置完成后，建议立即使用后台的“模拟推送”能力验证服务端连通性、签名逻辑和回调处理流程，避免把联调问题留到支付实测阶段。

商品创建与上架管理

• 商品配置路径与基础配置一致，也是在 开发者后台 >> 商店 >> 游戏包体管理 >> 小游戏管理 >> 开放能力 >> 小游戏内购 中完成。
• 点击“新建商品”后，商品类型固定为“游戏内购道具”，发货方式固定为“自动发货”。
• 商品定价直接填写人民币金额，无需手动换算为点券数量。
• 新建商品默认是“草稿”状态，需要提交审核；审核通过后，才能执行上架或下架操作。
• 商品上架后，如果只修改价格，通常无需重新提审；如果修改名称或素材，则需要重新审核。
• 游戏内展示的商品名称、商品 ID、价格和后台配置需要保持一致，避免支付后对不上商品信息。

客户端发起支付

• 玩家在游戏内点击购买后，客户端通常需要先向游戏服务端请求支付参数。
• 由服务端生成 signData、paySig、signature。
• 客户端再调用支付接口发起购买。
• 支付接口调用时需要传入后台配置好的商品 ID（productId）。
• API 调用成功后，系统会拉起统一收银台，展示商品名称、对应的点券价格及确认按钮。
• 客户端接收到支付成功结果后，建议结合服务端发货状态刷新游戏界面，不要直接把“客户端支付成功”视为最终到账。
• 除成功场景外，也要处理用户取消支付、支付超时和接口调用失败等异常路径。

服务端处理发货

• 支付完成后，TapTap 会向开发者配置的服务端地址发送异步通知。
• 服务端需要使用配置好的 Token 和 EncodingAESKey 对通知请求进行验签和解密。
• 服务端需要根据订单信息完成道具发放。
• 服务端需要对重复通知做幂等处理，避免网络波动或重试导致重复发货。
• 处理完成后，需要返回正确的响应状态码，确保平台能正确识别处理结果。

测试、查单与正式上线

• 正式上线前，必须在沙箱环境完成全流程测试。
• 在 开发者后台 >> 商店 >> 游戏包体管理 >> 小游戏管理 >> 开放能力 >> 小游戏内购 中添加测试账号，填写参与测试的 TapTap 用户 ID。
• 测试账号在小游戏“开发版”或“体验版”中发起支付时，系统会自动进入沙箱模式。
• 沙箱环境下可以直接测试“草稿”状态的商品，无需等待审核通过。
• 非白名单用户发起支付时，应出现账号异常或无权限提示。
• 白名单测试用户发起支付时，应拉起带有测试标识的收银台。
• 支付完成后，游戏内道具应正确到账，且服务端能成功接收并解析回调数据。

• 如果支付链路中出现异常订单，也建议结合订单查询接口完成补单、排障和对账。

5. 常见问题

后台配置价格时需要考虑点券汇率吗？

不需要。后台直接填写人民币金额即可。当前涉及点券展示时，换算比例为 1 元人民币 = 10 TapTap 点券。

这两种支付方式对客户端版本有要求吗？

有。Android 和 iOS 都需要使用最新 TapTap 客户端，才能支持「TapTap 点券」和「直购」两种支付方式。建议开发者在测试和正式接入时，将 TapTap 客户端升级至最新版本。

为什么配置了 URL 却收不到回调？

建议优先检查三件事：URL 是否为公网可访问的 HTTPS 地址、服务器是否拦截了请求、是否已经先通过后台“模拟推送”验证连通性。

商品审核周期大概多久？

根据当前产品侧文档，商品提交后通常会在 1-3 个工作日内完成审核。

必须完成财务信息补充吗？

是的。财务信息是结算的基础，未完成财务认证时，正式环境无法开启 IAP 能力。

6. 详细技术文档索引

如果你已经理解了 IAP 的产品流程，下面这些文档是进一步接入时需要查看的详细技术文档索引，分别对应能力说明、客户端支付、服务端发货和订单查询等具体实现内容。

• 虚拟支付能力概览 (opens new window)：先理解 IAP 的整体能力边界、接入条件和流程。
• 道具直购 (opens new window)：理解当前主要支付形态、商品字段和客户端接入思路。
• tap.requestPaymentGameItem (opens new window)：查看客户端支付接口、签名参数和错误码。
• 商品发货消息协议 (opens new window)：查看服务端如何接收发货通知、验签和返回处理结果。
• 订单查询 (opens new window)：查看服务端如何查单、补单和排查异常订单。