Integration Guide Hướng dẫn tích hợp集成指南

Explains Portal endpoints. Most are called by SDK JOY — mini-game usually only implements the game IPN in §5. Giải thích endpoint Portal. Hầu hết do SDK JOY gọi — mini game thường chỉ cần implement IPN game ở §5.说明 Portal 接口。多数由 SDK JOY 调用 — 小游戏通常只需实现 §5 的游戏 IPN。

Base: https://devsdkapi.joyplay.vn. Authed endpoints need header Authorization: <accessToken> (raw JWT).

Base: https://devsdkapi.joyplay.vn. API cần auth: header Authorization: <accessToken> (JWT thô).

Base：https://devsdkapi.joyplay.vn。 鉴权接口需要 header Authorization: <accessToken>（原始 JWT）。

POST /tiktok/orders/create

Purpose: create a Portal order and a TikTok Beans trade. Returns tradeOrderId for TTMinis.game.pay. Auth required. See request/response tables in §3 Native.

Mục đích: tạo đơn Portal + giao dịch TikTok Beans. Trả tradeOrderId để gọi TTMinis.game.pay. Cần auth. Xem bảng body/response ở §3 Native.

用途：创建 Portal 订单与 TikTok Beans 交易。 返回供 TTMinis.game.pay 使用的 tradeOrderId。 需要鉴权。请求/响应表见 §3 原生。

GET /tiktok/orders/:id

Purpose: after pay (or webhook), SDK polls this until status is paid (and checks addGoldStatus). :id = orderId from create. Auth required.

Mục đích: sau pay (hoặc webhook), SDK poll API này đến khi status = paid (và kiểm tra addGoldStatus). :id = orderId từ create. Cần auth.

用途：支付（或 webhook）后，SDK 轮询此接口直到 status 为 paid（并检查 addGoldStatus）。 :id = create 返回的 orderId。需要鉴权。

{
  "status": 0,
  "data": {
    "orderId": "a1b2c3d4-...",
    "status": "paid",
    "addGoldStatus": "success",
    "addGoldError": null,
    "addGoldCallbackUrl": "https://game-server/.../ipn",
    "tiktokTradeOrderId": "TOID_...",
    "amount": 29000,
    "tokenAmount": 20
  }
}

POST /tiktok/orders/:id/sandbox-complete

Internal / JoyGames demo only — not part of partner production. Partner games wait for TikTok’s real POST /tiktok/payment/webhook after Beans pay.

Chỉ demo nội bộ JoyGames — không nằm trong tích hợp partner production. Game partner chờ webhook thật POST /tiktok/payment/webhook sau khi trả Beans.

仅 JoyGames 内部 demo — 不属于合作方正式集成。 合作方游戏在 Beans 支付后等待 TikTok 真实的 POST /tiktok/payment/webhook。

POST /tiktok/orders/a1b2c3d4-.../sandbox-complete
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
// no body required — demo tools only

POST /tiktok/payment/webhook

Purpose: TikTok server → Portal callback after a real Beans payment. Portal verifies the event (live Product requires Webhook Secret on Admin), marks the order paid, then runs addGold (game IPN). Your game never calls this — only TikTok servers after a real Beans payment.

Mục đích: TikTok server → Portal sau khi trả Beans thật. Portal xác minh event (Product bắt buộc Webhook Secret trên Admin), đánh dấu order paid, rồi chạy addGold (IPN game). Game không gọi API này — chỉ server TikTok sau thanh toán thật.

用途：真实 Beans 支付后，TikTok 服务器 → Portal 回调。 Portal 校验事件（正式 Product 在 Admin 必须配置 Webhook Secret）， 将订单标记为 paid，然后执行 addGold（游戏 IPN）。 游戏不要调用此接口 — 仅 TikTok 服务器在真实支付后调用。

GET /tiktok/me

Purpose: return the current Portal user from the JWT (e.g. refresh balance after payment). Auth required. Prefer this over looking up users by id.

Mục đích: trả user Portal hiện tại từ JWT (ví dụ refresh số dư sau thanh toán). Cần auth. Dùng API này thay vì tra cứu user theo id.

用途：根据 JWT 返回当前 Portal 用户 （例如支付后刷新余额）。需要鉴权。 优先使用本接口，而不是按 id 查询用户。

Full flow from buy → paid → gold. Red = Dev Game setup; cyan = SDK JOY; other nodes = Portal / TikTok / game IPN. Sơ đồ toàn bộ luồng từ mua → paid → cộng vàng. Đỏ = Dev Game phải setup; cyan = SDK JOY; các bước khác = Portal / TikTok / IPN game.完整流程示意：购买 → 已支付 → 发币。红色 = Dev Game 需配置；青色 = SDK JOY；其余步骤 = Portal / TikTok / 游戏 IPN。

Header Sandbox / Live only switches Portal hosts (dev vs production). TikTok Beans always use the live TikTok path: Open API create trade → TTMinis.game.pay → TikTok webhook → Portal paid → game addGold. Game only calls joySdk.pay(); SDK talks to Portal; Portal talks to TikTok.

Header Sandbox / Live chỉ đổi host Portal (dev vs production). Beans TikTok luôn đi luồng TikTok live: Open API create trade → TTMinis.game.pay → webhook TikTok → Portal paid → addGold game. Game chỉ gọi joySdk.pay(); SDK nói với Portal; Portal nói với TikTok.

页头 Sandbox / Live 仅切换 Portal 域名 （开发 / 生产）。TikTok Beans 始终走正式 TikTok 路径： Open API 创建交易 → TTMinis.game.pay → TikTok webhook → Portal paid → 游戏 addGold。 游戏只调用 joySdk.pay()；SDK 与 Portal 通信；Portal 与 TikTok 通信。

Product should be active with TikTok Client Key / Secret / Webhook secret configured on Admin so Portal can call TikTok Open API and verify the webhook.

Product nên active và đã cấu hình TikTok Client Key / Secret / Webhook secret trên Admin để Portal gọi TikTok Open API và verify webhook.

Product 应为 active，并在 Admin 配置 TikTok Client Key / Secret / Webhook secret， 以便 Portal 调用 TikTok Open API 并校验 webhook。

Flowchart Sơ đồ流程图

Step by step Từng bước分步说明

1. Dev Game Login first. joySdk.login() → JWT stored. Đăng nhập trước. joySdk.login() → lưu JWT.先登录。 joySdk.login() → 保存 JWT。
2. Dev Game Game calls pay. Pass package + character fields. Game gọi pay. Truyền gói + thông tin nhân vật.游戏调用 pay。 传入套餐与角色字段。
3. SDK JOY SDK JOY → Portal create on the host from the header (dev or prod). SDK JOY → Portal create trên host theo header (dev hoặc prod).SDK → Portal 创建订单，域名随页头（开发或生产）。
4. System Portal → TikTok live create trade. Real trade_order_id. Portal → TikTok live create trade. Nhận trade_order_id thật.Portal → TikTok 正式创建交易。 真实 trade_order_id。
5. SDK JOY SDK JOY opens TTMinis.game.pay. Native Beans UI. SDK JOY mở TTMinis.game.pay. UI Beans native.SDK JOY 打开 TTMinis.game.pay。 原生 Beans 界面。
6. System Player pays. TikTok deducts Beans. User trả. TikTok trừ Beans.玩家支付。 TikTok 扣减 Beans。
7. System TikTok webhook → Portal. Event minis.trade_order.redeem.success. TikTok webhook → Portal. Event minis.trade_order.redeem.success.TikTok webhook → Portal。 事件 minis.trade_order.redeem.success。
8. System Portal setPaid + addGold. Calls game callback URL. Portal setPaid + addGold. Gọi callback URL game.Portal setPaid + addGold。 调用游戏回调 URL。
9. Dev Game Game IPN sends items. Verify signature (amount), then match googleProductId + amountBean + amount with Dev Game server catalog — only send when all 3 match. IPN game send vật phẩm. Verify signature (theo amount), rồi đối chiếu googleProductId + amountBean + amount với server Dev Game — chỉ send khi đúng cả 3 trường.游戏 IPN 发送道具。校验签名（按 amount），再对照 Dev Game 服务器目录核对 googleProductId + amountBean + amount — 仅当 3 个字段一致时发送。
10. SDK JOY SDK JOY poll sees paid. pay() returns success. SDK JOY poll thấy paid. pay() trả success.SDK JOY 轮询到 paid。 pay() 返回成功。

addGold IPN — body the Portal sends to your game server addGold IPN — body Portal gửi về game server của bạnaddGold IPN — Portal 发送到你游戏服务器的 body

{
  "action": "addGold",
  "type": "tiktok",
  "platform": "tiktok",
  "userId": 1002752299,
  "amount": 29000,
  "amountBean": 20,
  "serverId": "34",
  "charId": "34000001234",
  "time": 1784438520042,
  "transactionId": "332c9bee-...",
  "orderId": "32ec6b03-...",
  "productId": "com.joyplay.tiennghich.29",
  "googleProductId": "com.joyplay.tiennghich.29",
  "productName": "Tiên Nghịch Mobile",
  "clientID": "b18tiennghich",
  "extraInfo": { "amount": 29000, "goodids": null },
  "signature": "52dfa596..."
}

Header Sandbox vs Live (Portal hosts only) Header Sandbox vs Live (chỉ host Portal)页头 Sandbox 与 Live（仅 Portal 域名）