Obter informações de assinatura

Você pode obter informações sobre a atividade com assinaturas das seguintes maneiras:

• solicitar informações usando as chamadas de API (adequado para integração sem servidor)
• obter informações quando o status da assinatura for alterado automaticamente usando webhooks (adequado para integração de servidor)

Configuração via API

Especifique o ID do projeto como o parâmetro de caminho projectId. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto.

Especifique como parâmetros de consulta:

• limit — limite para o número de elementos na página (15 elementos são exibidos por padrão).
• offset — número do elemento a partir do qual a lista é gerada (a contagem começa a partir de 0).
• locale — idioma da interface (inglês por padrão). Aceita valores de acordo com a norma ISO 639-1.

1curl -X 'GET' \
2  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "id": 11111111,
 5      "plan_id": 11111,
 6      "plan_external_id": "TestChangePlanBase",
 7      "plan_name": "package_recurrent_name_66053",
 8      "plan_description": "package_recurrent_description_66053",
 9      "product_id": null,
10      "product_external_id": null,
11      "product_name": null,
12      "product_description": null,
13      "status": "active",
14      "date_create": "2021-03-11T13:50:11+03:00",
15      "date_next_charge": "2031-04-11T13:51:02+03:00",
16      "date_last_charge": "2021-03-11T13:51:02+03:00",
17      "charge": {
18        "amount": "0.2500",
19        "currency": "USD"
20      },
21      "period": {
22        "value": 1,
23        "unit": "day"
24      }
25    }
26  ],
27  "has_more": true
28}

Configurar webhooks

A solução Subscriptions oferece suporte a webhooks para os seguintes eventos:

• Pagamento de uma assinatura:
  • Validação de Usuário
  • Pagamento
  • Assinatura Criada

• Renovando uma assinatura:
  • Validação de usuário
  • Pagamento
  • Assinatura Atualizada
• Cancelando uma assinatura: Assinatura Cancelada (a assinatura foi cancelada na Conta de Distribuidor ou todos os pagamentos foram cancelados por todos os períodos válidos)

• Reembolso:
  • Reembolso (o pagamento foi cancelado na Conta de Distribuidor)
  • Assinatura Atualizada (o pagamento foi cancelado, mas a assinatura ainda está ativa. Isso é possível se o usuário pagou acidentalmente pela assinatura duas vezes e cancelou apenas o último pagamento)
  • Assinatura Cancelada (o pagamento foi cancelado na Conta de Distribuidor ou todos os pagamentos foram cancelados para todos os períodos válidos)

Para habilitar o recebimento de webhooks:

1. No projeto na Conta de Distribuidor, acesse a seção Configurações do projeto > Webhooks.
2. No campo Servidor de Webhooks, especifique o URL do seu servidor onde você deseja receber webhooks no formato https://example.com. Você também pode especificar o URL que encontrar em uma ferramenta para testar webhooks.

3. Gere uma chave secreta:

1. Na seção Chaves secretas, selecione Adicionar chave.
2. Na janela modal que surgir, insira o nome da chave que permitirá identificá-la na lista geral.
3. Selecione Criar chave.
4. Selecione Copiar segredo e salve a chave criada do seu lado.
5. Pressione Pronto.
6. Confirme que você salvou a chave e pressione Ok, fechar.

4. Selecione Enable webhooks.

Rotação de chave secreta

Você pode criar até 5 chaves secretas no seu projeto para habilitar a rotação delas.

Pode haver apenas uma chave secreta ativa por projeto. Se você quiser alterá-la, selecione Definir como ativa na linha de outra chave e confirme a ação. Assim que você migrar com sucesso para uma nova chave, recomendamos excluir as chaves desativadas.

5. Teste webhooks na Conta de Distribuidor.
6. Teste a compra da assinatura.
7. Teste a renovação da assinatura.
8. Teste o cancelamento de assinatura.

Teste webhooks na Conta de Distribuidor

Na aba Assinaturas, você pode testar os seguintes webhooks:

• Validação do Usuário (user_validation)
• Pagamento (payment)

Para testar webhooks:

1. Na seção de testes, acesse a aba Assinaturas.
2. Preencha os campos necessários:
   • ID do Usuário — ao testar, você pode usar qualquer combinação de letras e dígitos.
   • ID da fatura Xsolla — ID da transação no lado da Xsolla. Ao testar, você pode usar qualquer valor numérico.
   • ID público do usuário — ID conhecido por um usuário, por exemplo, um e-mail ou apelido. Este campo é exibido se você marcou a caixa Usar ID público do usuário no seu projeto na seção Configurações do projeto > Configurações de integração.
   • Quantia — quantia do pagamento. Ao testar, você pode usar qualquer valor numérico.
   • Moeda — selecione uma moeda na lista suspensa.
   • ID do plano — um plano de assinatura. Escolha um plano na lista suspensa.
   • Produto de assinatura — escolha um produto na lista suspensa (opcional). A lista é exibida se produtos estiverem configurados no seu projeto.
   • ID da fatura — ID da transação no lado do seu jogo. Ao testar, você pode usar qualquer combinação de letras e dígitos. Não é um parâmetro obrigatório para um pagamento bem-sucedido, mas você pode passá-lo para vincular o ID da transação do seu lado ao ID da transação no lado da Xsolla.
   • Provação. Para testar a compra de uma assinatura sem um período de provação ou para testar a renovação de uma assinatura, especifique o valor 0.
3. Selecione Teste.

No URL especificado, você receberá webhooks com os dados preenchidos. Os resultados dos testes de cada webhook, tanto para um cenário bem-sucedido quanto para um cenário de falha, são exibidos sob o botão Teste.

Teste a compra da assinatura

Ao testar um pagamento, os webhooks Validação do usuário, Pagamento e Assinatura criada serão enviados para o URL especificado na etapa Configure webhooks. Para testar o processo de pagamento, você pode:

• Usar o modo sandbox (para assinaturas com um período de avaliação de 0 dias)
• Faça um pagamento real e, em seguida, inicie um reembolso via a Conta de Distribuidor (para assinaturas com um período de avaliação de mais de 0 dias)

Modo sandbox

1. Obtenha um token para o modo sandbox. Passe o valor 0 para o parâmetro Trial period (trial_days).
2. Escolha o grupo de métodos de pagamento Cartões de crédito/débito.
3. Insira os dados do cartão bancário de teste. Insira quaisquer valores nos campos restantes. Você também pode especificar detalhes incorretos (número do cartão, data de validade ou CVV) para gerar um erro.

4. Receba webhooks para Validação do usuário, Pagamento e Assinatura atualizada no URL especificado na etapa Configure webhooks.

Pagamento real

1. Conclua o Teste de webhooks na Conta de Distribuidor.
2. Assine um Contrato de Licença.

3. Obtenha um token para pagamentos reais.

4. Abra a interface de pagamento com o seguinte link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, onde ACCESS_TOKEN é o token obtido na etapa anterior.
5. Escolha o grupo Cartão de crédito/débito nos métodos de pagamento.
6. Insira os dados válidos do cartão bancário.

7. Receba os webhooks Validação do usuário, Pagamento e Assinatura atualizada no URL do webhook que você forneceu na etapa Configure webhooks.
8. Reembolse o seu pagamento. Para fazer isso, vá para a Conta de Distribuidor > Player support > Transaction search.
9. Escolha a transação de teste e selecione o botão de menu More (•••). Selecione Refund no menu pop-up (a transação deve ter o status Concluída). Isso enviará os webhooks Assinatura cancelada e Reembolso.

Teste a renovação da assinatura

1. Obtenha um token para o modo sandbox. Passe o valor 0 para o parâmetro Trial period (trial_days).
2. Pague pela sua assinatura usando qualquer método de pagamento.
3. Reabra a interface de pagamento no modo sandbox.
4. Pague novamente para renovar sua assinatura usando qualquer método de pagamento.
5. Obtenha os webhooks Validação do usuário, Pagamento e Assinatura atualizada no URL do webhook que você especificou na etapa Configure webhooks.

Testar cancelamento de assinatura

Para testar o cancelamento de assinatura, use:

• Pesquisar por assinatura
• Pesquisar por transações recentes
• Chamadas de API

Pesquisar por assinatura

1. Abra sua Conta de Distribuidor e acesse a seção Player suporte > Subscribers.
2. Encontre a assinatura que você deseja cancelar.
3. Abra o menu de status da assinaturas e selecione:
   1. Cancel and refund para receber os webhooks Assinatura cancelada e Reembolso.
   2. Cancel without refund para receber o webhook Assinatura cancelada.

Pesquisar por transações recentes

1. Abra sua Conta de Distribuidor e acesse a seção Player support > Transaction search.
2. Encontre as últimas transações a serem canceladas.
3. Clique no ícone More (•••). Clique em Refund no menu pop-up para receber os webhooks Assinatura cancelada e Reembolso.

Use chamadas de API

Abra a interface de pagamento no modo sandbox

Para abrir a interface de pagamento do modo sandbox, obtenha um token com o modo sandbox ativo. A seguir estão maneiras de obter um link com o token necessário:

• Use a Conta de Distribuidor
• Use a chamada de API

Via Conta de Distribuidor

1. Teste webhooks na Conta de Distribuidor. Especifique o valor 0 no campo Trial period para testar uma assinatura que não tenha um período de avaliação. Depois de receber uma mensagem de confirmação de um teste bem-sucedido, um link com o token necessário aparecerá sob o cabeçalho Sandbox URL.

2. Siga o link Sandbox URL.

Via chamada de API

1. Passe os parâmetros "settings":{"mode":"sandbox"} para o método Criar token. Passe os parâmetros "purchase": {"subscription":{"trial_days": 0}} para testar uma assinatura que não tenha um período de avaliação.
2. Use o seguinte link: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, onde ACCESS_TOKEN é o token obtido na etapa anterior.