# Платёжный модуль

Платёжный модуль предоставляет функции для покупки предметов в игре и оплаты полной версии.  
Ознакомьтесь с разделом, соответствующим вашему игровому движку, на странице [`Введение в JOGOS_SDK`](./introduction.md), после чего используйте функции следующим образом:

::: tabs key:engine

== HTML5

```javascript
window.JOGOS_SDK.payment;

== Cocos

JOGOS_SDK.payment;

== Unity

JogosSDK.Goods

:::

Внутриигровые покупки

Шаг 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 о доставке.
• В зависимости от результата выдавайте награду или показывайте текст ошибки.
• После доставки вызовите API облачного сохранения, чтобы синхронизировать прогресс игрока.

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
);

---

Покупка полной версии (Buy-out)

1. В панели разработчика установите тип распространения игры «Game Pricing» и укажите цену.
2. Создайте две сборки: демо и полную версию

• Демо: удалите уровни, модели, текстуры, музыку, недоступные игроку, оставив только пробный контент. Загрузите эту сборку отдельно.
• Полная версия: сборка со всем контентом.

3. Добавьте кнопку покупки в демо:

• Когда игрок завершает демо (например, проходит последний уровень первой главы), покажите экран и кнопку «Купить полную версию»:
• Кнопка вызывает метод buyOut, открывая окно оплаты Jogos.
• После успешной оплаты платформа сама переключится на полную версию; дополнительных действий не требуется.
• Номер версии демо и полной сборки должен совпадать — сохранения автоматически мигрируют.
• После оплаты возвращается номер заказа, по которому можно запросить информацию.

// Возвращает номер заказа при успехе
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Важно*

Как в демо, так и в полной версии обязательно инициализируйте SDK в первой сцене и дождитесь коллбека перед запуском любого игрового кода. Jogos при инициализации проверит, купил ли пользователь игру; иначе он не сможет продолжить.
Это надёжная защита от пиратства.

```