# Payment

The payment module provides functionality for in-app purchases and buy-to-play payments. After reading the [`JOGOS_SDK Introduction`](./introduction.md) page for the section relevant to your game engine, you can use the related features as follows:

::: tabs key:engine

== HTML5

```javascript
window.JOGOS_SDK.payment;

== Cocos

JOGOS_SDK.payment;

== Unity

JogosSDK.Goods

:::

In-App Purchase

Step 1: Create Product ID

• Create products on the Developer Backend's Information / Purchase page.
• Note: Product IDs must be unique within the same game.

Step 2: Initiate Order

• When a player needs to purchase an in-game item, call this interface on the purchase button to open the Jogos payment window.
• The developer needs to pass in the product ID. Upon successfully opening the payment window, an order number is returned. This order number can be used later by the developer to query information about this order.
• goodsId is the product ID you created in the Developer Backend.

// Returns order number on success
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

Step 3: Wait for User Payment

Subscribe to Order Payment Completion Notification on the Client

There might be a significant delay between a player placing an order and actual successful payment. Developers can use this interface to subscribe to player payment success messages. When a player successfully pays, the platform will notify the subscribed callback, proactively informing the developer that the order has been paid and returning the latest order information.

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

Step 4: Deliver Goods and Notify the Platform

Handle Delivery on the Client (Standalone Games)

Upon learning that the player has successfully paid, the developer automatically processes the reward distribution and calls this interface to notify the platform that delivery has been completed.

Reminder

• If your game (does not have a game server), it is recommended that upon listening for the user's payment on the client, you call this interface to notify the Jogos platform that you have delivered the goods to the user.
• Based on the interface return result, handle reward distribution in your game or prompt other exception descriptions.
• It is recommended that after delivery, you call the cloud storage system archive synchronization interface to save the player's data.

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

Method via "Game Server" Integration:

For server integration related APIs, please refer to the Server Integration Interface page.

Other Interfaces

Suggestions for Improving Payment

• The client-side subscription to payment success notifications (subscribeOrderPaid) cannot guarantee 100% receipt of notifications due to various uncontrollable factors like network issues. We recommend using the Get Order Interface to check the latest payment status of the order.
• Some standalone games might offer a save data deletion feature. The decision on whether to re-grant rewards from previous payments rests with you. Developers can call the order list query interface to obtain all player orders for re-granting.
• After obtaining the order information, use the status field to judge and process the order.

Order Information

Query the detailed information of an order based on the order number. The order structure is as follows:

// Payment Order
export interface PaymentOrder {
  // Game Id
  gameId: number;
  // Game Name
  gameName: string;
  // User Id
  userId: number;
  // Order Number
  orderNo: string;
  // Product Id
  productId: string;
  // Product Name
  productName: string;
  // Currency
  currency: string;
  // Country
  country: string;
  // Discount
  discount: number;
  // Jogos Coin (Points) Deduction
  calorcoin: number;
  // Payment Amount
  paid: number;
  // Payment Channel
  channel: string;
  // Payment Type
  paymentType: string;
  // Payment Number
  paymentNo: string;
  // Whether Goods Have Been Delivered
  deliverGoods: boolean;
  // Order Status: pending, fail, cancel, expire, success, refunding, refunded, refund-fail
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // Order Creation Time
  createTime: String;
  // Refund Number
  refundNo: String;
  // Refund Description
  refundDescription: String;
  // Refund Request Time
  refundTime: String;
  // Successful Refund Time
  refundedTime: String;
}

Get Order Information

// Returns order information on success
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

Get Order List

Developers can use this interface to query orders of specific statuses. Returns a list of orders upon success. The order information structure is the same as the order details.

// Returns order list on success
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // Page number: defaults to 1
  pageSize?: number // Number of records per page: defaults to 20
);

Buy-to-Play Games

1. Set your game to "Game Pricing" (buy-to-play type) in the Developer Backend and set your game's price.
2. Create two submission versions for your game: a Trial version and a Full version.

• Trial Version: It is recommended to remove assets, models, textures, music, etc., for levels the player cannot access, keeping only the content available for trial. Package and upload this version separately.
• Full Version: The version where players have access to the complete game content.

3. Set up a purchase button in the trial version:

• When the player finishes the trial, e.g., reaches the last level of Chapter 1 in the trial version, and needs to purchase the full game, design an interface for "Selling the Full Version" with a purchase button:
• The purchase button can call the buyOut interface to open the Jogos platform payment window, allowing players to purchase the full version quickly.
• Once the user purchases successfully, the Jogos platform will automatically switch to the full version for the player to continue playing. No additional handling is required by the developer.
• Keep the version numbers of the Trial and Full versions consistent. The Jogos platform will automatically migrate user save data to the full version.
• Upon successful payment, an order number is returned. The developer can use this order number to query information related to this order.

// Returns order number on success
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Important Reminder*

Please note: For both the full version and the trial version, initialization must be performed in the first startup scene of the game project. Wait for the callback to complete before executing the first line of your game code. Jogos checks during initialization whether the user has purchased your game; otherwise, the user cannot continue playing. This is an effective means to protect your game from being pirated and played by unauthorized users.