# Pagamento

O módulo de pagamento oferece funcionalidades relacionadas à compra de itens dentro do jogo e ao pagamento de versão completa. Após ler a página de [`Introdução ao JOGOS_SDK`](./introduction.md) e a seção relacionada ao motor do seu jogo, você pode usar as funcionalidades da seguinte forma:

::: tabs key:engine

== HTML5

```javascript
window.JOGOS_SDK.payment;

== Cocos

JOGOS_SDK.payment;

== Unity

JogosSDK.Goods

:::

Compra dentro do aplicativo

Passo 1: Criar ID do produto

• Crie um produto na página Information / Purchase do painel do desenvolvedor.
• Observe que o ID do produto não pode ser repetido dentro do mesmo jogo.

Passo 2: Iniciar pedido

• Quando o jogador precisar comprar um item dentro do jogo, você pode chamar esta interface no botão de compra do produto para abrir a janela de pagamento Jogos.
• O desenvolvedor precisa passar o ID do produto. Após abrir a janela de pagamento com sucesso, o número do pedido será retornado. Você pode usar este número para consultar informações relacionadas ao pedido posteriormente.
• goodsId é o ID do produto criado no painel do desenvolvedor.

// Retorna o número do pedido em caso de sucesso
let orderNo = await window.JOGOS_SDK.payment.buyGoods(goodsId: string);

Passo 3: Aguardar o pagamento do usuário

Assinar notificação de conclusão de pagamento do pedido no cliente

Pode haver um longo período de tempo entre o pedido do jogador e o pagamento bem-sucedido. Os desenvolvedores podem usar esta interface para assinar notificações de pagamento bem-sucedido (chamada pós-inicialização). Após o pagamento bem-sucedido, a plataforma notificará o desenvolvedor via callback com as informações atualizadas do pedido

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

Passo 4: Entregar o produto e notificar a plataforma que o pedido foi entregue

Processamento de entrega pelo cliente (jogos offline)

Após confirmar que o jogador pagou com sucesso, o desenvolvedor deve processar a entrega da recompensa automaticamente e chamar esta interface para notificar a plataforma de que o produto foi entregue.

Aviso

• Seu jogo (se não houver servidor de jogo) é recomendado que, ao detectar o pagamento do usuário no cliente, você notifique a plataforma Jogos de que o produto foi entregue.
• Com base no resultado da interface, você pode processar a entrega da recompensa no jogo ou exibir mensagens de erro.
• Recomenda-se que, após a entrega, você chame a interface de sincronização de save na nuvem para salvar os dados do jogador.

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

Integração via servidor de jogo:

Para APIs relacionadas à integração do servidor, consulte a página: APIs de integração do servidor.

Outras interfaces

Sugestões para aprimorar o pagamento

• A assinatura da notificação de sucesso de pagamento no cliente (subscribeOrderPaid) não é garantida 100% devido a fatores como rede. Recomendamos que você use a interface de consulta de pedido para obter o status mais recente do pedido.
• Alguns jogos offline podem oferecer funcionalidade de exclusão de save. Nesse caso, a decisão de recompensar novamente itens previamente pagos fica a seu critério. Você pode consultar a lista de pedidos do jogador para recompensá-los.
• Após obter as informações do pedido, você pode processar o pedido com base no campo status.

Informações do pedido

Consulte os detalhes de um pedido pelo número. A estrutura do pedido é a seguinte:

// Pedido de pagamento
export interface PaymentOrder {
  // ID do jogo
  gameId: number;
  // Nome do jogo
  gameName: string;
  // ID do usuário
  userId: number;
  // Número do pedido
  orderNo: string;
  // ID do produto
  productId: string;
  // Nome do produto
  productName: string;
  // Moeda
  currency: string;
  // País
  country: string;
  // Desconto
  discount: number;
  // Dedução em Jogos coins (pontos)
  calorcoin: number;
  // Valor pago
  paid: number;
  // Canal de pagamento
  channel: string;
  // Tipo de pagamento
  paymentType: string;
  // Número do pagamento
  paymentNo: string;
  // Se foi entregue
  deliverGoods: boolean;
  // Status do pedido: pending: pendente  fail: falha  cancel: cancelado  expire: expirado  success: sucesso  refunding: em reembolso  refunded: reembolsado  refund-fail: falha no reembolso
  status: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded' | 'refund-fail';
  // Hora de criação do pedido
  createTime: String;
  // Número do reembolso
  refundNo: String;
  // Descrição do reembolso
  refundDescription: String;
  // Hora da solicitação de reembolso
  refundTime: String;
  // Hora do reembolso bem-sucedido
  refundedTime: String;
}

Obter informações do pedido

// Retorna as informações do pedido em caso de sucesso
let order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo: string);

Obter lista de pedidos

Os desenvolvedores podem usar esta interface para consultar pedidos com base no status. Em caso de sucesso, retorna uma lista de pedidos com a mesma estrutura da consulta de detalhes.

// Retorna a lista de pedidos em caso de sucesso
let orderList = await window.JOGOS_SDK.payment.getOrderList(
  status?: 'pending' | 'fail' | 'cancel' | 'expire' | 'success' | 'refunding' | 'refunded',
  pageNo?: number,  // Número da página: padrão é 1
  pageSize?: number // Registros por página: padrão é 20
);

Jogos de compra única

1. No painel do desenvolvedor, defina seu jogo como “Game Pricing” (tipo de compra única) e configure o preço.
2. Crie duas versões de envio: versão de teste e versão completa

• Versão de teste: recomenda-se remover assets, modelos, texturas e músicas inacessíveis ao jogador, mantendo apenas o conteúdo jogável. Faça o upload desta versão separadamente.
• Versão completa: versão com todo o conteúdo disponível.

3. Adicione um botão de compra na versão de teste:

• Quando o jogador terminar a demo, por exemplo, ao completar o último nível do primeiro capítulo, exiba uma tela e um botão para comprar a versão completa:
• O botão pode chamar a interface buyOut para abrir a janela de pagamento da Jogos;
• Após a compra bem-sucedida, a plataforma Jogos alternará automaticamente para a versão completa. Nenhuma ação adicional é necessária.
• Mantenha o mesmo número de versão entre demo e versão completa. A plataforma migrará automaticamente o save do jogador.
• Após o pagamento, o número do pedido será retornado. Você pode usá-lo para consultar informações do pedido.

// Retorna o número do pedido em caso de sucesso
let orderNo = await window.JOGOS_SDK.payment.buyOut();

*Aviso importante*

Independentemente da versão (demo ou completa), sempre inicialize o SDK na primeira cena do jogo e aguarde o callback antes de executar qualquer código. A Jogos detectará durante a inicialização se o usuário comprou o jogo; caso contrário, ele não poderá continuar jogando.
Isso é uma medida eficaz para evitar pirataria.

```