Pago

El módulo de pago proporciona funcionalidades relacionadas con la compra de artículos dentro del juego y pagos por compra definitiva. Después de leer la sección relevante para su motor de juego en la página Introducción a JOGOS_SDK, puede utilizar las funciones relacionadas de la siguiente manera:

window.JOGOS_SDK.payment;

Compras dentro de la aplicación (In-App Purchase)

Paso 1: Crear ID de producto

• Cree productos en la página Information / Purchase del Backend para Desarrolladores.
• Nota: Los ID de producto no se pueden repetir dentro del mismo juego.

Paso 2: Iniciar pedido

• Cuando un jugador necesite comprar un artículo dentro del juego, puede llamar a esta interfaz en el botón de compra para abrir la ventana de pago de Jogos.
• El desarrollador necesita pasar el ID del producto (goodsId). Tras abrir la ventana de pago con éxito, se devolverá un número de pedido. Posteriormente, el desarrollador puede utilizar este número de pedido para consultar información relacionada con este pedido.
• goodsId es el ID del producto que creó en el Backend para Desarrolladores.

// Devuelve el número de pedido en caso de éxito
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

Paso 3: Esperar a que el usuario realice el pago

Suscribirse a la notificación de finalización de pago del pedido desde el cliente

Puede haber un retraso significativo entre que un jugador realiza un pedido y el pago se completa correctamente. Los desarrolladores pueden utilizar esta interfaz para suscribirse a los mensajes de éxito de pago del jugador. Cuando un jugador pague correctamente, la plataforma notificará al callback suscrito, informando activamente al desarrollador de que el pedido ha sido pagado y devolviendo la información más actualizada del pedido.

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

Paso 4: Entregar los bienes y notificar a la plataforma

Manejar la entrega en el cliente (Juegos independientes/Standalone)

Cuando el desarrollador sepa que el jugador ha pagado correctamente, procesará automáticamente la entrega de recompensas y llamará a esta interfaz para notificar a la plataforma que la entrega se ha completado.

Recordatorio

• Si su juego (no tiene un servidor de juego), se recomienda que, al detectar el pago del usuario en el cliente, llame a esta interfaz para notificar a la plataforma Jogos que ha entregado los bienes al usuario.
• Según el resultado devuelto por la interfaz, maneje la entrega de recompensas en su juego o muestre mensajes de otras excepciones.
• Se recomienda que después de la entrega, llame a la interfaz de sincronización de guardado en el sistema de almacenamiento en la nube para guardar los datos del jugador.

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

Método mediante integración del "Servidor del Juego":

Para las API relacionadas con la integración del servidor, consulte la página Interfaz de Integración del Servidor.

Otras Interfaces

Sugerencias para mejorar los pagos

• La suscripción en el cliente a las notificaciones de éxito de pago (subscribeOrderPaid) no puede garantizar la recepción del 100% de las notificaciones debido a varios factores incontrolables como problemas de red. Le recomendamos que utilice la Interfaz de Obtención de Pedidos para comprobar el estado de pago más reciente del pedido.
• Algunos juegos independientes pueden ofrecer una función de eliminación de partidas guardadas. La decisión de si volver a otorgar recompensas de pagos anteriores recae en usted. Los desarrolladores pueden llamar a la interfaz de consulta de lista de pedidos para obtener todos los pedidos del jugador y realizar recompensas.
• Después de obtener la información del pedido, utilice el campo status para juzgar y procesar el pedido.

Información del Pedido

Consulta la información detallada de un pedido basándose en el número de pedido. La estructura del pedido es la siguiente:

// Pedido de Pago
export interface PaymentOrder {
  // ID del Juego
  gameId: number;
  // Nombre del Juego
  gameName: string;
  // ID de Usuario
  userId: number;
  // Número de Pedido
  orderNo: string;
  // ID del Producto
  productId: string;
  // Nombre del Producto
  productName: string;
  // Moneda
  currency: string;
  // País
  country: string;
  // Descuento
  discount: number;
  // Deducción de Moneda Jogos (Puntos)
  calorcoin: number;
  // Monto del Pago
  paid: number;
  // Canal de Pago
  channel: string;
  // Tipo de Pago
  paymentType: string;
  // Número de Transacción de Pago
  paymentNo: string;
  // Si los Bienes Han Sido Entregados
  deliverGoods: boolean;
  // Estado del Pedido: pending (pendiente), fail (fallido), cancel (cancelado), expire (expirado), success (éxito), refunding (en reembolso), refunded (reembolsado), refund-fail (error en reembolso)
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // Hora de Creación del Pedido
  createTime: String;
  // Número de Reembolso
  refundNo: String;
  // Descripción del Reembolso
  refundDescription: String;
  // Hora de Solicitud de Reembolso
  refundTime: String;
  // Hora de Reembolso Exitoso
  refundedTime: String;
}

Obtener Información del Pedido

// Devuelve información del pedido en caso de éxito
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

Obtener Lista de Pedidos

Los desarrolladores pueden utilizar esta interfaz para consultar pedidos de estados específicos. Devuelve una lista de pedidos en caso de éxito. La estructura de información del pedido es la misma que los detalles del pedido.

// Devuelve la lista de pedidos en caso de éxito
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // Número de página: por defecto 1
  pageSize?: number // Número de registros por página: por defecto 20
);

Juegos de Pago Único (Buy-to-Play)

1. Configure su juego como "Game Pricing" (tipo de pago único) en el Backend para Desarrolladores y establezca el precio de su juego.
2. Cree dos versiones de envío para su juego: una versión de Prueba (Trial) y una versión Completa (Full).

• Versión de Prueba: Se recomienda eliminar los recursos de niveles a los que el jugador no puede acceder, modelos, texturas, música, etc., dejando solo el contenido disponible para la prueba. Empaquete y suba esta versión por separado.
• Versión Completa: La versión donde los jugadores tienen acceso al contenido completo del juego.

3. Configure un botón de compra dentro de la versión de prueba:

• Cuando el jugador termine la prueba, por ejemplo, al llegar al último nivel del Capítulo 1 en la versión de prueba, y necesite comprar la versión completa del juego, diseñe una interfaz para "Vender la Versión Completa" con un botón de compra:
• El botón de compra puede llamar a la interfaz buyOut para abrir la ventana de pago de la plataforma Jogos, permitiendo a los jugadores comprar la versión completa del juego rápidamente.
• Una vez que el usuario compre correctamente, la plataforma Jogos cambiará automáticamente a la versión completa para que el jugador continúe jugando. El desarrollador no necesita realizar ningún proceso adicional.
• Mantenga los números de versión de la Versión de Prueba y la Versión Completa consistentes. La plataforma Jogos migrará automáticamente las partidas guardadas del usuario a la versión completa.
• Tras el pago exitoso, se devolverá un número de pedido. El desarrollador puede utilizar este número de pedido para consultar información relacionada con este pedido.

// Devuelve el número de pedido en caso de éxito
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Recordatorio Importante*

Tenga en cuenta: Tanto para la versión completa como para la versión de prueba, la inicialización debe realizarse en la primera escena de inicio del proyecto del juego. Espere a que la devolución de llamada (callback) se complete antes de ejecutar la primera línea de su código del juego. Jogos verifica durante la inicialización si el usuario ha comprado su juego; de lo contrario, el usuario no podrá continuar jugando. Este es un medio eficaz para proteger su juego de ser pirateado y jugado por usuarios no autorizados.