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)

Configure por meio de chamadas de 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.

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

{
  "items": [
    {
      "id": 11111111,
      "plan_id": 11111,
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      },
      "period": {
        "value": 1,
        "unit": "day"
      }
    }
  ],
  "has_more": true
}

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)

1. Na Conta de Distribuidor, vá para Project settings > Webhooks.
2. Defina a opção no bloco Webhooks como On.

3. Especifique o URL do webhook. Clique em Save settings.

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

Teste webhooks na Conta de Distribuidor

1. Em Conta de Distribuidor > Project settings > Webhooks, vá para a aba Subscriptions.

2. Para testar webhooks, especifique valores do seu projeto (ID do Usuário, ID da Fatura) a serem enviados em uma solicitação para o URL do webhook que você forneceu. Na ausência de valores reais, você pode inserir valores arbitrários. Preencha os seguintes campos de formulário:
   • ID do usuário
   • ID da fatura Xsolla
   • Valor
   • Moeda
   • ID do Plano
   • Produto da assinatura (opcional)
   • ID da Fatura — número do pedido interno (opcional)
   • Período de teste (Para testar uma compra de assinatura no modo sandbox ou testar a renovação de assinaturas, defina um valor 0.)

3. Clique em Testar.
4. Verifique se você recebeu uma mensagem de êxito de teste. Se o teste for bem-sucedido, o servidor retornará um código de status HTTP 204. Se não for bem-sucedido, o servidor retornará um código de status HTTP 400 ou 500 junto com uma descrição do erro.

Teste a compra da assinatura

• 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 e ative o módulo Subscriptions.
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> Suporte > Transaction search.
9. Escolha a transação de teste e clique no botão de menu More (•••). Clique em 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

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

Pesquisar por assinatura

1. Em Conta de Distribuidor, vá para 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. Na Conta de Distribuidor, vá para 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

• 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.