支付

支付模組提供遊戲內物品的購買支付和買斷支付的相關功能，閱讀JOGOS_SDK 簡介頁面與您的遊戲引擎相關的部分後，可依照以下方式使用相關功能：

window.JOGOS_SDK.payment;

應用內購買

第 1 步：建立商品 ID

• 在開發者後台的 Information / Purchase 頁面建立商品。
• 注意同一款遊戲下的商品 ID 不可重複。

第 2 步：發起訂單

• 當玩家需購買遊戲內物品時，可在商品購買按鈕上呼叫此介面開啟 Jogos 支付視窗。
• 開發者需傳入商品 Id，成功開啟支付視窗後會返回訂單編號，後續開發者可透過此訂單編號查詢該訂單的相關資訊。
• goodsId 即為您在開發者後台建立的商品 ID。

// 成功返回訂單編號
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

第 3 步：等待使用者進行付款

由用戶端訂閱訂單支付完成通知

玩家下單後至實際支付成功可能會有較長時間，開發者可透過此介面訂閱玩家支付成功的訊息；當玩家支付成功後，平台會透過訂閱時的回呼主動通知開發者訂單已支付完畢，並返回最新的訂單資訊。

window.JOGOS_SDK.payment.subscribeOrderPaid(callbackFn: (order: PaymentOrder) => void);

第 4 步：發貨，並通知平台訂單已發貨

由用戶端處理發貨(單機遊戲)

開發者獲知玩家付款成功後，自動處理獎勵發放，並呼叫此介面通知平台已完成發貨。

提醒

• 您的遊戲（若沒有遊戲伺服器）建議您在用戶端監聽到使用者付款後，透過呼叫此介面，通知Jogos平台您已向該使用者發貨。
• 根據介面返回結果，在遊戲中處理獎勵發放、或提示其他異常描述。
• 建議您在發貨後，呼叫雲端儲存系統存檔同步介面，儲存玩家的資料。

await window.JOGOS_SDK.payment.deliverGoods(orderNo: string);

由「遊戲伺服器」接入的方式：

伺服器接入相關API，請參閱：伺服器接入介面頁面。

其他介面

完善支付的建議

• 用戶端訂閱使用者付款成功的通知(subscribeOrderPaid)，因網路等各種不可控因素，無法保證用戶端100%收到通知。建議您可透過取得訂單介面獲取該筆訂單最新的支付狀況。
• 部分單機遊戲可能提供刪除存檔的功能，此時使用者先前支付所獲得的獎勵是否需重新補發，由您自行決定。開發者可呼叫查詢訂單列表的介面，取得玩家所有訂單並進行補發。
• 取得訂單資訊後，可透過status進行判斷，並處理該筆訂單。

訂單資訊

根據訂單編號查詢訂單的詳細資訊。訂單結構如下所示：

// 支付訂單
export interface PaymentOrder {
  // 遊戲 Id
  gameId: number;
  // 遊戲名稱
  gameName: string;
  // 使用者 Id
  userId: number;
  // 訂單編號
  orderNo: string;
  // 商品 Id
  productId: string;
  // 商品名稱
  productName: string;
  // 幣種
  currency: string;
  // 國家
  country: string;
  // 折扣
  discount: number;
  // Jogos幣（積分）扣減
  calorcoin: number;
  // 支付金額
  paid: number;
  // 支付管道
  channel: string;
  // 支付類型
  paymentType: string;
  // 支付單號
  paymentNo: string;
  // 是否已發貨
  deliverGoods: boolean;
  // 訂單狀態  pending: 待支付  fail: 支付失敗  cancel: 已取消  expire: 已過期  success: 支付成功  refunding: 退款中  refunded: 退款成功  refund-fail: 退款失敗
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // 訂單建立時間
  createTime: String;
  //退款單號
  refundNo: String;
  //退款說明
  refundDescription: String;
  //申請退款時間
  refundTime: String;
  //成功退款時間
  refundedTime: String;
}

取得訂單資訊

// 成功返回訂單資訊
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

取得訂單列表

開發者可透過此介面根據訂單狀態查詢所需的訂單資訊，成功後返回訂單列表，訂單資訊與訂單詳情結構一致。

// 成功返回訂單列表
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // 頁碼：預設為1
  pageSize?: number // 每頁記錄數：預設為20
);

買斷制遊戲

1. 在開發者後台將您的遊戲設定為「Game Pricing」（買斷制類型），並設定遊戲價格。
2. 為您的遊戲建立兩個提交版本：試玩版與正式版

• 試玩版：建議刪除玩家無法接觸到的關卡資產、模型、貼圖、音樂等，僅保留玩家可試玩的內容，額外打包此版本上傳。
• 正式版：玩家可使用完整遊戲內容的版本。

3. 在試玩版遊戲內設定購買按鈕：

• 當玩家試玩結束時（例如試玩版達到第一章最後一關），若需購買正式版遊戲，需設計「販售正式版」的介面與購買按鈕：
• 購買按鈕可呼叫buyOut介面開啟 Jogos 平台支付視窗，方便玩家儘快購買遊戲正式版；
• 當使用者購買成功後，Jogos 平台會自動切換至正式版遊戲供玩家繼續遊玩，開發者無需額外處理。
• 請保持試玩版與正式版的版本號一致，Jogos 平台會自動將使用者存檔遷移至正式版。
• 支付成功後會返回訂單編號，開發者可根據此訂單編號查詢該訂單的相關資訊。

// 成功返回訂單編號
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*重要提醒*

請注意，不論是正式版還是試玩版，務必在遊戲工程的第一個啟動場景進行初始化，並等待回呼完成後，再執行遊戲的第一行程式碼；Jogos 會在初始化時偵測使用者是否已購買您的遊戲，否則使用者將無法繼續遊玩。 這是保障您的遊戲不被使用者盜版遊玩的有效方式。