Vista geral

O objetivo do sistema de pagamento em jogos do Steam é disponibilizar uma forma fácil de vender bens arbitrários a utilizadores sem precisarem de sair do jogo. Cabe ao vendedor decidir o que pretende vender. Podem ser itens do jogo (por exemplo, armas ou munições), dinheiro virtual (por exemplo, moedas ou ouro) ou até roupa para a personagem no jogo. Pode ter tantos itens quanto desejar no seu jogo e pode vendê-los individualmente ou em pacotes. O Steam não limita o que pode vender e como o deve vender, nem impede o uso de quaisquer outros mecanismos do seu jogo para a venda de itens. A finalidade deste sistema é implementar no seu jogo uma experiência comum de pagamento já familiar para os utilizadores da plataforma Steam, permitindo-lhes usar facilmente o saldo da Carteira Steam para comprar os seus produtos. Ao usar este tipo de integração, o seu jogo terá acesso imediato a novos utilizadores do Steam e a métodos de pagamento assim que estiverem disponíveis.

Com este sistema, o processo de compra fica completamente sob o seu controlo. Uma resposta bem-sucedida a um pedido de compra fará com que o utilizador seja devidamente cobrado e que você receba uma notificação imediata acerca desse evento. Assim que uma compra for aprovada, cabe-lhe a si conceder e gerir os itens. Se, por exemplo, um item tiver um prazo de validade, é o seu sistema que dita até quando estará disponível.

Para além de compras no jogo, o sistema disponibiliza funcionalidades adicionais que o seu sistema de contabilidade e apoio técnico poderão usar:

1. Pode receber notificações em caso de falhas no pagamento.
   
2. Pode processar reembolsos e consultar o estado de transações através do serviço web.
   
3. Terá acesso a relatórios detalhados na página de estatísticas do site de parceiros Steamworks, incluindo dados em tempo real de vendas de itens e jogos.

Boas práticas para compras em jogos

Se pretender disponibilizar compras dentro do seu jogo no Steam, temos algumas sugestões, boas práticas e recursos que poderão ser úteis para começar. Quer tenha um jogo grátis para jogar ou pago, há elementos comuns a todos os jogos com microtransações que devem ser levados em consideração quando estiver a preparar o lançamento do seu produto no Steam.

Consulte Microtransações (compras em jogos) para sugestões sobre economias de jogos e boas práticas.

Como funciona o sistema de pagamento

O sistema de pagamento é uma combinação do processo de compra que existir no seu jogo, o serviço web de cobrança do Steam e um processo de aprovação do utilizador.

O processo de compra segue a ordem abaixo. O utilizador inicia e conclui sempre a compra no seu jogo:

1. Quando um utilizador pretende comprar algo no jogo, o seu jogo envia um pedido de compra para o seu servidor de compras. O servidor de compras poderá ser qualquer entidade de serviço que o sistema do seu jogo possui para gerir os pedidos de compra, como um servidor web ou um sistema de autenticação. O servidor terá de comunicar com os servidores de cobrança do Steam por protocolo HTTP. O seu servidor de compras poderá também solicitar dos servidores de cobrança do Steam o país, o idioma e a moeda do utilizador. Pode usar estes dados para ajustar os seus preços conforme precisar.
   
2. O seu servidor de compras inicia então uma transação de pagamento em nome do cliente ao serviço web do Steam. O pedido HTTP é seguro e usa o método POST. Os conteúdos deste pedido incluem os metadados do utilizador, uma descrição e o preço de cada item que o utilizador deseja comprar.
   
3. Depois de receber este pedido, o Steam irá ativar automaticamente o Painel Steam e apresentar uma janela de diálogo onde estão listados todos os itens, o preço e um botão para confirmar ou autorizar a transação. Se o utilizador não tiver saldo suficiente na Carteira Steam, o Painel Steam irá encaminhar o utilizador pelo processo de depósito de saldo. O Painel Steam gere a recolha de toda a informação de cobrança do utilizador. Uma vez concluído este processo, o utilizador irá receber uma notificação a indicar que a compra foi autorizada ou negada. O seu jogo deve estar registado para receber um callback desta notificação e encaminhar o resultado para o seu servidor de compras.
   
4. O seu servidor de compras recebe a notificação e faz uma chamada a FinalizeTxn para concluir a operação. Uma resposta de pagamento bem-sucedido irá resultar na cobrança ao utilizador e poderá assim conceder-lhe o item.

Em alternativa, no caso de jogos cujas opções de compra costumam estar disponíveis através de uma página web ou se desejar disponibilizar o Steam como um método de pagamento diretamente no seu site, pode realizar uma integração do browser. Para esta solução, o processo de compra segue a seguinte ordem:

1. O utilizador deseja comprar algo dentro do jogo ou através do seu site. Se for uma compra dentro do jogo, a sua página web será aberta num browser.
   
2. O seu servidor de compras inicia uma transação web em nome do utilizador através de um pedido HTTP seguro com o método POST. Se for bem-sucedido, o pedido irá retornar um URL único do Steam para o qual a sessão do browser pode ser redirecionada, permitindo ao utilizador autorizar a transação. Ao redirecionar o link, também terá de especificar um URL para o qual encaminhar o utilizador após a conclusão da transação.
   
3. Quando o utilizador é redirecionado para o seu site, o seu servidor de compras solicita o estado da transação e, se foi autorizada com sucesso, pode capturar os fundos ao chamar FinalizeTxn.

Configuração de uma ligação

Pré-condições

Comece por criar uma chave da Web API de editora. As instruções estão disponíveis na página de documentação sobre Autenticação com chaves da Web API. A chave está incluída em todos os pedidos ao servidor web e é usada para os autenticar. Deve ser enviada com cada pedido no parâmetro key=<chave aqui>.

Armazenamento das compras

Armazene cada compra para referência futura no seu sistema. Utilize um ID único de 64 bits (OrderID) para referenciar as transações no Steam.

Envio de pedidos

Todos os pedidos devem ser enviados através de métodos GET ou POST do protocolo HTTP 1.1, utilizando uma ligação TLS segura. O "Content-Type" deve ser "application/x-www-form-urlencoded" e os parâmetros POST devem estar no corpo do pedido no formato padrão de codificação de URL para formulários. O texto deve ser transmitido no formato UTF-8.

Os pedidos serão enviados para o URI base:
https://partner.steam-api.com/ISteamMicroTxn/*

Alguns comandos retornam um resultado positivo ou negativo. Nos casos em que é recebido um resultado negativo, será acrescentado também um código de erro e uma descrição. Estas chaves de parâmetros não estarão presentes se a resposta for positiva.

As respostas serão retornadas no formato JSON, por predefinição. Pode especificar que o formato XML seja usado ao adicionar o parâmetro "format=xml" ao pedido.
Atenção: deve implementar uma solução JSON ou XML flexível que permita o envio e retorno de chaves de parâmetro em qualquer ordem.

Testes

O Steam disponibiliza uma sandbox para que teste a sua integração. A sandbox permite todos os pedidos disponíveis através da API comum, mas o saldo da Carteira Steam não será utilizado durante testes.

A sandbox é acedida a partir de um URI base diferente:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Passos para integração

Compras dentro do jogo

Estes passos são para jogos com uma loja integrada, onde os jogadores não precisam de sair do jogo para realizar uma compra.

• Passo 1
  O seu jogo precisa de conter a API do Steamworks, o que significa que deverá incluir um ficheiro de cabeçalho (header), estar associado a um ficheiro de biblioteca (lib) e ser lançado com um dll. Para mais detalhes, consulte Steamworks API Overview. A API do Steamworks tem de ser inicializada com sucesso antes de continuar!
  
• Passo 2
  O utilizador decide comprar um ou mais itens no seu jogo. Assim que os itens tiverem sido identificados, o seu jogo precisa de recolher alguns metadados sobre o utilizador:
  
  • SteamID – Este número de 64 bits identifica de forma única o utilizador no sistema do Steam.
    
  • Código do país – O código ISO 3166 do país do utilizador indica de onde a compra está a ser realizada. Utilize este código para determinar qual o preço a aplicar à compra.
    
  • Código da moeda — O código ISO 4217 da moeda na qual o utilizador será cobrado.
    
  • Código do idioma do jogo — O código ISO 639-1 do idioma usado pelo jogo na aplicação Steam.
    
  
  O SteamID e o idioma podem ser obtidos através das chamadas à API do Steamworks:
  
  • ISteamUser::GetSteamID
    
  • ISteamApps::GetCurrentGameLanguage
    
  
  Para obter o país e moeda do utilizador, faça um pedido à Web API ISteamMicroTxn/GetUserInfo com o SteamID do utilizador como parâmetro.
  
  Estes metadados do utilizador devem ser agrupados e enviados para o servidor de compras com os seus dados de compra comuns.
  
• Passo 3
  O seu servidor de compras inicia um pedido de compra através do serviço web do Steam em nome da aplicação Steam. Utilize o método ISteamMicroTxn/InitTxn descrito mais à frente neste documento. Precisa de enviar os seguintes dados com o seu pedido:
  
  • OrderID – Um número único de 64 bits que atribui a esta compra. Este número é a sua chave para a transação. É usado para referenciar a transação no sistema do Steam.
    
  • SteamID – O ID do utilizador recebido através da aplicação Steam no passo 3.
    
  • AppID – O identificador único do seu jogo no Steam.
    
  • Idioma – O código ISO 639-1 do idioma no qual o seu item ou itens aparecem listados.
    
  • Moeda – O código ISO 4217 da moeda em que o seu preço é apresentado. Se não for igual ao código da moeda do utilizador como consta no passo 2, será aplicada uma conversão automática de acordo com a taxa de câmbio atual. O Steam irá apresentar o preço convertido ao utilizador para sua aprovação, na sua moeda local. Para oferecer uma melhor experiência, é recomendado que defina preços específicos em cada uma das moedas que espera que sejam usadas pelos utilizadores.
    
  • Uma lista de um ou mais itens que o utilizador deseja comprar. Deve especificar os seguintes dados para cada item:
    
    • ItemID – O identificador de 32 bits definido por si para o item.
      
    • Quantidade – Número de itens deste tipo na transação.
      
    • Montante – O montante em centésimas que pretende cobrar ao utilizador por este item. Algumas moedas devem apresentar o custo em valores inteiros (consulte Moedas disponíveis para mais informações). Se o valor de quantidade deste item for superior a um, este valor é o total que será cobrado (Montante = quantidade x item_cost).
      
    • Descrição do item – Uma descrição em texto do item. Isto será apresentado ao utilizador quando lhe for solicitada a autorização da transação. Esta descrição pode ser traduzida de acordo com o código de idioma indicado pela aplicação Steam.
      
    • Categoria de item – Uma descrição opcional em texto sobre a categoria à qual este item deve pertencer. Este valor é usado para agrupar dados de vendas nos relatórios do Steam e nunca aparece para utilizadores.
      
  
  Se a transação for aceite pelo Steam, a aplicação Steam será notificada automaticamente para autorizar a compra. Se um erro for retornado, será necessário corrigir o problema e enviar uma nova transação de compra.
  
• Passo 4
  Uma tentativa bem-sucedida do método ISteamMicroTxn/InitTxn irá resultar numa notificação no Painel Steam a informar que a transação precisa de ser autorizada. Os detalhes da transação são apresentados com base nas descrições dos itens fornecidas pelo seu pedido de compra. O utilizador poderá então autorizar a transação. Se o utilizador não tiver saldo suficiente na conta, o Steam irá encaminhá-lo automaticamente pelo processo de depósito de saldo. No final, o seu jogo receberá uma notificação que a transação foi autorizada ou negada.
  
  O seu jogo precisará de registar um handler para o callback ISteamUser::MicroTxnAuthorizationResponse_t para receber uma notificação do evento de aprovação (ou negação). O resultado do callback contém o AppID, o OrderID e o estado de autorização da transação. O seu jogo pode enviar este resultado para o seu servidor de compras para que possa finalizar a transação. Consulte a documentação sobre callbacks para mais detalhes.
  
• Passo 5
  O seu servidor de compras usa o comando ISteamMicroTxn/FinalizeTxn da Web API para concluir a transação com os seguintes parâmetros:
  
  • OrderID – O ID da compra criado por si para iniciar a transação.
    
  • AppID – O identificador único do seu jogo no Steam.
    
  
  Uma resposta bem-sucedida significa que a compra foi aceite e que os itens devem ser concedidos. Uma resposta de erro indica que a compra não foi concluída corretamente e uma mensagem de erro apropriada é enviada.
  
• Passo 6
  O seu servidor de compras terá de chamar regularmente a API ISteamMicroTxn/GetReport para receber notificações sobre alterações do estado de liquidação das transações. No mínimo, deve chamar esta API diariamente para reconciliar alterações do estado de liquidação, mas não é uma má ideia chamar esta API a cada minuto para garantir que os seus servidores estejam a par de todas as alterações relativamente a transações.
  
  Conforme as suas necessidades, pode usar a API ISteamMicroTxn/RefundTxn para reembolsar transações de clientes. Contudo, existem outras formas de reverter transações que deve ter em mente. Se uma transação entrar num estado revertido (por exemplo, "Refunded", "PartialRefund", "Chargedback", "RefundedSuspectedFraud" ou "RefundedFriendlyFraud", consulte: Anexo A: Valores referentes ao estado), o seu backend deve tentar recuperar os itens associados à transação revertida, se possível. Consulte a secção "Prevenção de fraudes" deste artigo e certifique-se de que tomou as medidas necessárias para prevenir os tipos de fraude mais comuns.

Compras na web

Se a loja do seu jogo for uma página web ou se pretende apenas adicionar o Steam como método de pagamento na sua loja existente, use os seguintes passos para a integração:

• Passo 1
  Obtenha o SteamID do utilizador.
  
  • Se o utilizador estiver no jogo, utilize a API do Steamworks para obter o SteamID: ISteamUser::GetSteamID.
    
  • Se o utilizador estiver no seu site, pode usar a API OpenID do Steamworks para obter de forma segura o SteamID do utilizador. Os detalhes sobre o OpenID estão disponíveis na documentação do Steamworks sobre Web Browser based authentication with OpenID.
    
  
  Atenção: recomendamos que associe a conta do jogo do utilizador ao respetivo SteamID para que o utilizador só precise de realizar este início de sessão secundário uma vez.
  
• Passo 2
  Obtenha o país e a moeda do utilizador ao fazer um pedido à Web API ISteamMicroTxn/GetUserInfo com o SteamID do utilizador como parâmetro. Estes dados podem ser usados para apresentar a sua loja ao utilizador com o preço e os valores de moeda corretos.
  
  Atenção: o método GetUserInfo tem um parâmetro de endereço IP opcional que pode ser usado para indicar ao Steam de onde o utilizador é. Envie o endereço IP público do utilizador para todas as compras efetuadas através da web ou sempre que o utilizador não estiver com sessão iniciada pela aplicação Steam e a jogar o seu jogo.
  
• Passo 3
  O seu servidor de compras inicia um pedido de compra através do serviço web do Steam usando ISteamMicroTxn/InitTxn. É necessário facultar as seguintes informações para além do que é normalmente necessário para compras no jogo:
  
  • usersession – Deve conter o valor "web", o que indica que o utilizador estará a autenticar a transação através de um browser.
    
  • ipaddress – O endereço IP público do utilizador.
    
  
  Quando o valor de "usersession" é "web", o pedido de InitTxn irá retornar um parâmetro "steamurl" adicional. Este é um URL único para o qual pode redirecionar a sessão web do utilizador e que identifica a transação criada por esta chamada à API.
  
  
• Passo 4
  O seu servidor de compras redireciona a sessão web do utilizador para o URL do Steam retornado na chamada à API InitTxn. Com o redirecionamento, inclua o seu próprio URL para onde o utilizador será encaminhado após a autorização ou negação da transação. Use um URL específico completo (por exemplo, http://www.steamgames.com) no formato:
  returnurl=URL_aqui
  Quando um utilizador é redirecionado para o URL do Steam, o utilizador terá de iniciar sessão no Steam antes do processo de autenticação. Este seria o comportamento esperado pelo utilizador caso este tenha selecionado o Steam como método de pagamento no seu site. Porém, se o utilizador estiver já com sessão iniciada no Steam e a jogar o seu jogo, é desejável que esse segundo início de sessão não seja necessário. Para tal, use o browser da web integrado no Painel Steam. Quando o browser do Painel Steam é utilizado para autorização, a sessão do utilizador será iniciada automaticamente. Para iniciar o browser, chame a seguinte função da API do Steamworks:
  ISteamFriends::ActivateGameOverlayToWebPage
  
  Detalhes completos sobre o uso do Painel Steam estão disponíveis aqui.
  
• Passo 5
  Quando o utilizador regressar ao seu site, chame o método ISteamMicroTxn/QueryTxn da Web API para obter os resultados. Se o estado da compra for "Approved", capture os fundos com uma chamada ao método ISteamMicroTxn/FinalizeTxn da Web API. Abandone a transação se receber qualquer outro estado.
  
  Atenção: se o utilizador fechar o browser ou se algo ocorrer que o impeça de regressar ao seu site, abandone a transação e não chame FinalizeTxn. Mesmo que o utilizador tenha aprovado a transação e por algum motivo não tenha sido redirecionado de volta, abandone-a e comece de novo.
  
• Passo 6
  O seu servidor de compras terá de chamar regularmente a API ISteamMicroTxn/GetReport para receber notificações sobre alterações do estado de liquidação das transações. No mínimo, deve chamar esta API diariamente para reconciliar alterações do estado de liquidação, mas não é uma má ideia chamar esta API a cada minuto para garantir que os seus servidores estejam a par de todas as alterações relativamente a transações.
  
  Conforme as suas necessidades, pode usar a API ISteamMicroTxn/RefundTxn para reembolsar transações de clientes. Contudo, existem outras formas de reverter transações que deve ter em mente. Se uma transação entrar num estado revertido (por exemplo, "Refunded", "PartialRefund", "Chargedback", "RefundedSuspectedFraud" ou "RefundedFriendlyFraud", consulte: Anexo A: Valores referentes ao estado), o seu backend deve tentar recuperar os itens associados à transação revertida, se possível. Consulte a secção "Prevenção de fraudes" deste artigo e certifique-se de que tomou as medidas necessárias para prevenir os tipos de fraude mais comuns.

Anexo A: Valores referentes ao estado

Estes são os possíveis valores referentes ao estado retornados pela Web API ISteamMicroTxn. A chave da resposta que contém estes valores tem normalmente a denominação status.

• Init – A compra foi criada, mas não foi autorizada pelo utilizador.
  
• Approved – A compra foi aprovada pelo utilizador.
  
• Succeeded – A compra foi processada com sucesso.
  
• Failed – A compra falhou ou foi negada.
  
• Refunded – A compra foi reembolsada e o produto deve ser revogado pelo jogo. Um reembolso pode ser solicitado pelo utilizador.
  
• PartialRefund – Um ou mais itens do carrinho foram reembolsados. Consulte o campo "itemstatus" de cada item para mais detalhes.
  
• Chargedback – A compra foi fraudulenta ou contestada e o produto deve ser revogado pelo jogo.
  
• RefundedSuspectedFraud – A compra foi reembolsada pela Valve devido a uma suspeita de fraude. O produto deve ser revogado pelo jogo.
  
• RefundedFriendlyFraud – A compra foi reembolsada pela Valve porque se constatou que se tratava de um caso de fraude amigável. O produto deve ser revogado pelo jogo.

Anexo B: Códigos de erro

Estes são os possíveis códigos de erro retornados pela Web API ISteamMicroTxn. A chave da resposta que contém estes valores tem normalmente a denominação errorcode.

• 1 – Sucesso
  
• 2 – A operação falhou
  
• 3 – Parâmetro inválido
  
• 4 – Erro interno
  
• 5 – O utilizador não aprovou a transação
  
• 6 – A transação já foi efetuada
  
• 7 – O utilizador não tem sessão iniciada
  
• 8 – A moeda não corresponde à moeda da conta Steam do utilizador
  
• 9 – A conta não existe ou está temporariamente indisponível
  
• 10 – A transação foi negada pelo utilizador
  
• 11 – A transação foi negada porque o utilizador está num país com acesso restrito
  
• 12 – A transação foi negada porque o acordo de cobrança não está ativo
  
• 13 – O acordo de cobrança não pode ser processado por não ser do tipo GAME
  
• 14 – O acordo de cobrança foi suspenso devido a contestação ou estorno
  
• 15 – O acordo de cobrança não pode ser processado por não ser do tipo STEAM
  
• 16 – O utilizador já possui um acordo de cobrança para este jogo
  
• 100 – Saldo insuficiente
  
• 101 – Tempo limite para finalização esgotado
  
• 102 – Conta desativada
  
• 103 – Conta não autorizada a comprar
  
• 104 – Transação negada devido a deteção de fraude
  
• 105 – Nenhum método de pagamento em cache
  
• 106 – Transação ultrapassaria o limite de gastos do acordo de cobrança
  
• 107 – O utilizador tem uma transação pendente que tem de ser concluída antes de iniciar uma nova

Perguntas ou dúvidas?

Faça perguntas no fórum de discussão sobre compras em jogos.