Preços locais

Você pode definir preços regionais para todos os itens do seu catálogo para aumentar as vendas em países com baixo poder de compra. Por padrão, os preços são definidos em USD. Além disso, você pode configurar restrições regionais.

Você pode adicionar, editar e excluir preços regionais das seguintes maneiras:

• usando Métodos API

Como funciona

O preço do item é determinado quando o catálogo é solicitado, dependendo do país do usuário. Durante a compra via Pay Station, o preço de um item é convertido para a moeda do país do usuário e inclui impostos, se aplicável.

Determinação de país

O país do usuário é determinado em diferentes etapas do trabalho com o catálogo e o pagamento, da seguinte forma:

• Ao solicitar o catálogo de itens, o país do usuário é passado no parâmetro country dos métodos nos grupos Virtual items and currency ou Game keys.

  Se o país não for especificado, ele é determinado com base no Endereço IP do usuário. Os preços do catálogo de itens são selecionados com base no país do usuário.

• Ao comprar um item:

  • Se você usar os métodos do lado do cliente para obter um token de pagamento, use-os no lado do cliente, não no servidor. O país e a moeda nos métodos do lado do cliente são determinados pelo Endereço IP do usuário. Usar métodos do lado do cliente no servidor pode causar determinação incorreta da moeda e afetar os Métodos de Pagamento na interface de pagamento.

  • Se você usar o método de servidor Create payment token for purchase, passe o país no parâmetro user.country.value no Corpo da Solicitação ou o endereço IPv4 do usuário no cabeçalho X-User-Ip. Se ambos os valores forem passados, user.country.value tem prioridade. Endereços IPv6 não são compatíveis: enviar um pode resultar em detecção incorreta de país e moeda.

  Observação

  Você pode passar a moeda no parâmetro settings.currency. Esse valor tem precedência sobre o valor do país e afeta como a moeda de pagamento é exibida. Os Métodos de Pagamento na interface de pagamento ainda são determinados pelo valor do país no parâmetro user.country.value.

Princípios de exibição de preços no catálogo de itens

Use a mesma lista de moedas para todos os itens do catálogo. Os preços são processados conforme a seguinte lógica:

• Se pelo menos um item não tiver preço definido para o país selecionado, os preços de todo o catálogo de itens naquele país mudam para a moeda padrão.
• Se os itens tiverem moedas padrões diferentes, os preços são exibidos na moeda padrão do primeiro item no catálogo. Se um dos itens não tiver um preço nessa moeda, o valor de preço null será retornado para ele na resposta da solicitação do catálogo. Isso resulta em exibição incorreta do preço do item e pode afetar a exibição do catálogo como um todo.

Exemplos:

• 1 item, 1 moeda, sem preços regionais
• 1 item, existem preços regionais
• Múltiplos itens, existem preços regionais, uma moeda padrão
• Múltiplos itens, existem preços regionais, moedas padrões diferentes

A moeda padrão para o item é USD e o preço é 5 USD. Não há configurações para países. Nesse caso, todos os usuários de todos os países verão esse preço.

O projeto possui preços nas seguintes moedas:

• preço padrão — 7 USD
• preço em euro — 6 EUR
• preços regionais:
  • Alemanha — 8 EUR
  • Itália — 5 EUR
  • Malásia — 20 MYR
  • África do Sul — 90 ZAR

Dependendo do país do usuário, a exibição de preços no catálogo será como a seguir:

País do usuário	Preço no catálogo	Comentário
EUA	7 USD	Os EUA são um país onde se usa USD. Um preço especial para os EUA não está especificado.
Japão	7 USD	A moeda do Japão não está especificada, então o preço é exibido na moeda padrão.
França	6 EUR	A França é um país onde se usa EUR. Um preço especial para a França não está especificado.
Alemanha	8 EUR	Um preço regional está especificado para a Alemanha.
Itália	5 EUR	Um preço regional está especificado para a Itália.
Malásia	20 MYR	Um preço regional está especificado para a Malásia.
África do Sul	90 ZAR	Um preço regional está especificado para a África do Sul.

O projeto tem preços nas seguintes moedas:

• o preço padrão para todos os itens é em dólares americanos (USD)
• na Malásia, os preços de todos os itens estão em ringgit malaio (MYR)
• na África do Sul, os preços de todos os itens, exceto um, estão em rand sul-africano (ZAR)

Nesse caso, o catálogo é exibido em MYR para os usuários da Malásia, mas em USD para a África do Sul. Para os usuários da África do Sul, o preço é exibido em USD, pois o preço em ZAR não foi especificado a um dos itens.

O projeto tem preços nas seguintes moedas:

• o preço padrão do 1_test_item é em dólares americanos (USD)
• o preço padrão do 2_test_item é em euro (EUR)
• na África do Sul, o preço do 1_test_item é dado em rand sul-africano (ZAR); para o 2_test_item não está especificado

Nesse caso, para usuários da África do Sul, o preço deve ser exibido na moeda padrão do primeiro item do catálogo — 1_test_item.

A moeda padrão do 1_test_item é USD. Ela não corresponde à moeda padrão do 2_test_item — EUR. Além disso, não há preço em USD na lista de preços dele.

Portanto, para o 2_test_item o valor de preço retornado será null.

Para criar um item virtual com um preço regional:

2. Clique em Create manually e selecione Virtual item na lista suspensa.

3. Na seção General settings, informe:
   • SKU
   • um ou mais grupos aos quais o item deve pertencer (opcional)
   • Nome
   • Descrição breve
   • Descrição estendida — para adicioná-la, ative a Opção correspondente (opcional)

4. Na seção Media, faça upload de uma ou mais imagens ou vídeos (opcional) — do seu dispositivo ou via link. Na loja criada com o editor de sites da Xsolla, todos os cartões do item exibem o arquivo marcado como Main, enquanto os demais arquivos ficam disponíveis apenas em cartões com galeria de mídia. O arquivo marcado como Main também é retornado nas respostas das Chamadas de API de obtenção do catálogo.

5. Na seção Price settings, selecione Paid item.

6. Ative a Opção Real currency prices e clique em Set up prices.

7. Na janela que abrir, especifique a moeda e o preço padrão. Você pode substituir USD por outra moeda padrão.

8. Configure os preços regionais. Você pode fazer isso de duas formas, manualmente ou automaticamente:

• Para definir preços manualmente:

1. Selecione Add local price e adicione preços linha por linha.

2. Selecione Apply.

• Para definir preços automaticamente:

1. Selecione Calculate using default price. Uma lista de países será gerada em ordem alfabética, e o preço na moeda regional será calculado para cada país com base nas taxas de conversão e impostos.

2. Para remover países para os quais você não precisa definir preços regionais, clique no ícone de menos à direita do preço.

3. Para modificar um preço calculado automaticamente, altere o valor na fileira correspondente.

4. Clique em Apply.

9. Se quiser adicionar um preço em moeda virtual, ative a Opção Virtual currency prices e especifique os valores.

10. Para limitar a quantidade de itens disponíveis para compra:

    1. Ative a Opção na seção Limits e especifique a quantidade.
    2. Configure a frequência de redefinição do limite. Para isso, selecione um período na Lista Suspensa:
       • Daily.
       • Weekly.
       • Monthly.
       • Custom interval. O intervalo é calculado a partir da data de início de exibição do item na loja.
       • No regular refresh.
    3. Defina a programação de redefinição especificando os parâmetros que correspondem ao período selecionado.

11. Para configurar um limite de tempo de exibição para o item (opcional):

    1. Ative a Opção na seção Add specific display period.
    2. Especifique o Fuso Horário e o início e o fim do período.

    Para deixar o fim do período de exibição do item sem especificação, ative a Opção No end date.

12. Configure os Atributos usando uma das opções a seguir (opcional):
    1. Adicione atributos e seus valores no Formato JSON.
    2. Crie manualmente atributos e seus valores e vincule-os aos itens.

13. Se o item pago for usado em alguma mecânica com recompensa aleatória (por exemplo, loot boxes ou gacha), ative a Opção Mark as paid randomized reward.

14. Clique em Create.

15. Na janela que abrir, selecione o Status do item e clique em Continue.

O item criado aparecerá na seção All items.

Para editar preços:

2. Clique em ⋮ ao lado do item desejado e selecione Edit na lista suspensa.

3. Na seção Price settings, clique no ícone de edição abaixo do preço padrão.

Você pode importar preços regionais de um arquivo para itens pré-criados.

Recursos:

• Fazer upload ou atualizar preços regionais para vários itens de uma só vez.
• Suporte para itens de todos os tipos:
  • itens virtuais
  • moedas virtuais
  • pacotes de moeda virtual
  • conjuntos
  • pacotes de chaves do jogo em uma plataforma específica
• Validação dos dados enviados. Se a estrutura do arquivo ou o formato dos dados não atenderem aos requisitos, você verá uma lista de erros durante a importação.

Estrutura do arquivo

Colunas obrigatórias do arquivo:

• SKU — o SKU do item para o qual é necessário definir preços regionais.
• Country — o código do país no formato ISO 3166-1 alpha-2. Verifique a lista de países com suporte pela Xsolla antes de fazer Upload do Arquivo CSV. Preencher as células nesta coluna é opcional. Você pode ver exemplos de exibição de preço se o país não for especificado.
• Currency — o código da moeda no formato ISO 4217.
• Amount — o preço do item. Use ponto para casas decimais.
• IsDefault — indica se este é o preço padrão. Especifique:
  • 1 — para a linha com o preço padrão. Ele é exibido em todos os países sem preços regionais.
  • 0 — para todas as outras linhas. Você também pode deixar a célula na coluna IsDefault vazia.

Observação

O preço na moeda padrão não deve ser regional — deixe a célula na coluna Country vazia.

EXEMPLO

Arquivo corretamente preenchido (vários itens, 3 moedas, preços regionais disponíveis).

Arquivo preenchido incorretamente (vários itens, 3 moedas, preços regionais disponíveis).
Erro: em virtual-item-1 e bundle-1 as células dos grupos na coluna Country não estão vazias.

Ao adicionar cada novo item, você deve definir o preço na moeda padrão. Se não for especificado, um erro será exibido ao importar o arquivo.

EXEMPLO

Arquivo corretamente preenchido (vários itens, 3 moedas, preços regionais disponíveis).

Arquivo preenchido incorretamente (vários itens, 3 moedas, preços regionais disponíveis).
Erro: não há moeda padrão para os grupos virtual-item-1 e bundle-1.

• Platform — o SKU da plataforma. É usado ao definir preços regionais para chaves do jogo, mas não é usado para outros itens.

  Plataformas disponíveis.

  SKU da plataforma	Nome da plataforma
  steam	Steam
  playstation	PlayStation
  xbox	Xbox
  uplay	Uplay
  origin	Origin
  drmfree	DRM Free
  gog	GOG
  epicgames	Epic Games Store
  nintendo_eshop	Nintendo Switch eShop
  discord_game_store	Discord Game Store
  oculus	Oculus
  viveport	Viveport
  stadia	Google Stadia

Observação

Chaves do jogo com o mesmo SKU, mas plataformas diferentes, são consideradas entidades diferentes. Cada entidade deve ter um preço especificado na moeda padrão.

EXEMPLO

Arquivo corretamente preenchido (várias chaves do jogo, 3 moedas, preços regionais disponíveis, 2 plataformas).

Arquivo preenchido incorretamente (várias chaves do jogo, 3 moedas, preços regionais disponíveis, 2 plataformas).
Erro 1: Agrupamento incorreto de chaves do jogo por SKU e Platform, resultando em nove entidades encontradas em vez de três.
Erro 2: Os grupos 3, 4, 5 e 6 não têm preço padrão devido ao agrupamento incorreto.
Erro 3: O grupo 9 substituirá os dados do grupo 7 porque eles têm um conjunto completo de preços para a mesma entidade. Como resultado, a game-key-2 para a plataforma playstation terá apenas um preço em MYR após a importação.

Exemplos de preenchimento do arquivo e possíveis erros

Exemplos de preenchimento correto do arquivo CSV para importação:

• Diversos itens, 3 moedas, nenhum preço regional
• Itens diversos, 1 moeda, nenhum preço regional
• Diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 1 plataforma
• Diversas chaves de jogo, 3 moedas, nenhum preço regional, 2 plataformas

Copy

Full screen

Small screen

• csv

 1SKU,Currency,Amount,Country,IsDefault
 2virtual-item-1,EUR,9.09,,0
 3virtual-item-1,USD,10.1,,1
 4virtual-item-1,MYR,47,,0
 5virtual-currency-1-pack-100,EUR,2.09,,0
 6virtual-currency-1-pack-100,USD,2.3,,1
 7virtual-currency-1-pack-100,MYR,24,,0
 8bundle-1,EUR,15,,0
 9bundle-1,USD,17,,1
10bundle-1,MYR,82,,0

Copy

Full screen

Small screen

• csv

1SKU,Currency,Amount,Country,IsDefault
2virtual-item-1,USD,10.1,,1
3virtual-currency-1-pack-100,USD,2.3,,1
4bundle-1,USD,17,,1

Copy

Full screen

Small screen

• csv

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

Copy

Full screen

Small screen

• csv

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,USD,10.1,,1,steam
 3game-key-1,EUR,9.09,,0,steam
 4game-key-1,MYR,47,,0,steam
 5game-key-1,USD,17,,1,playstation
 6game-key-1,EUR,15,,0,playstation
 7game-key-1,MYR,82,,0,playstation
 8game-key-2,USD,2.3,,1,steam
 9game-key-2,EUR,2.09,,0,steam
10game-key-2,MYR,24,,0,steam

Exemplos de preenchimento incorreto do arquivo CSV para importação:

• Diversas chaves de jogo, 3 moedas, nenhum preço regional, 2 plataformas
• Diversas chaves de jogo, 3 moedas, preços regionais disponíveis, 2 plataformas
• Diversos itens, 3 moedas, preços regionais disponíveis
• Diversos itens, 3 moedas, preços regionais disponíveis
• Diversos itens, 3 moedas, nenhum preço regional

Erro: Os grupos game-key-1 + steam e game-key-2 + steam não têm moedas padrão.

Erro: Os grupos game-key-1 + steam e game-key-2 + steam têm US mencionado como o país para os preços padrão.

Erro: Os grupos virtual-item-1 e bundle-1 não têm preços padrão.

Erro: Os grupos virtual-item-1 e bundle-1 têm US mencionado como o país para os preços padrão.

Erro 1: Agrupamento incorreto de itens por SKU, resultando em cinco entidades encontradas em vez de três.
Erro 2: O grupo 3 não tem preço padrão devido ao agrupamento incorreto.
Erro 3: O grupo 4 substituirá os dados do grupo 2 porque eles têm um conjunto completo de preços para o mesmo item. Como resultado, o SKU de virtual-currency-1-pack-100 terá apenas um preço em MYR após a importação.

Importação de arquivo

Para importar preços de um arquivo:

3. Clique em Import/Export e, na lista suspensa no bloco Import, selecione Prices from CSV.

4. Faça Upload do arquivo no campo correspondente da janela de importação.

Após um envio bem-sucedido, os preços regionais dos itens com os SKUs especificados será atualizado de acordo com os preços no arquivo. Os preços especificados anteriormente serão excluídos.

Exemplo:

Além disso, você pode definir preços regionais ao importar itens usando a Chamada de API Import items via JSON file.

Configurar usando Métodos API

Para configurar preços regionais através de métodos de API, informe uma matriz de objetos com configurações de preço para países:

• nos métodos para criar e atualizar Itens Virtuais
• nos métodos para criar e atualizar Moedas Virtuais
• nos métodos para criar e atualizar Pacotes de Moeda Virtual
• nos métodos para criar e atualizar Conjuntos
• nos métodos para criar e atualizar Pacotes de Chaves do Jogo

Exemplo de matriz:

 1"prices": [
 2  {
 3    "amount": 100,
 4    "currency": "USD",
 5    "is_enabled": true,
 6    "is_default": true
 7  },
 8  {
 9    "amount": 200,
10    "currency": "CZK",
11    "country_iso": "CZ",
12    "is_enabled": false,
13    "is_default": false
14  }
15]