Configure a exibição e compra do catálago de assinaturas

A implementação do catálogo de assinaturas depende de como você está integrando assinaturas no seu projeto:

Se você estiver integrando a venda de assinaturas no seu próprio aplicativo ou site, você pode:
- Construir a interface do catálogo inteiramente do seu lado usando os dados do plano de assinatura da Xsolla API ou os seus dados locais.
- Exibir o catálogo de assinaturas usando a interface de pagamento da Xsolla — não é preciso captar os dados separadamente.
Se você estiver criando um site usando o construtor de sites da Xsolla, a interface do catálogo deve ser posicionada diretamente dentro do layout do site. Nesse caso, você não precisa captar os dados do plano nem implementar a interface de pagamento separadamente.

Escolha onde deseja exibir o catálogo de assinaturas:

Escolha uma opção de autenticação para compras de assinaturas:

Nesse cenário, você implementa a exibição do catálogo de assinaturas do seu lado e gerencie o fluxo de compra através do seu próprio servidor. Todas as interações com a Xsolla são realizadas usando chamadas do lado do servidor da Xsolla API.

Para implementar a exibição de catálogos de assinaturas e a abertura da interface de pagamento:

Implemente a recuperação de uma lista de planos de assinaturas usando a chamada de servidor Get plans (opcional).

Você pode armazenar a lista de planos localmente e usar os dados para construir o catálogo. Nesse caso, não há a necessidade de chamar o método API para recuperar a lista de planos.

Implemente a exibição do catálogo do seu lado.
Implemente a geração de tokens para abrir a interface de pagamento para comprar assinaturas de uma das seguintes maneiras:
- na página de seleção do método de pagamento
- na página de inserção de dados de pagamento
Implemente a abertura de interface de pagamento.

Gere um token para abrir a interface de pagamento na página de seleção de métodos de pagamento

Para fazer com que a interface de pagamento exiba a página de seleção de método de pagamento quando aberta, passe o parâmetro purchase.subscription.plan_id com o ID do plano selecionado para a chamada de API Criar token. Passe parâmetros de personalização adicionais, se necessário.

Se os planos com uma taxa de assinatura associada ao primeiro pagamento estiverem definidos em seu projeto, você também precisará passar os seguintes parâmetros:

purchase.checkout.amount com o preço do plano de assinatura
purchase.checkout.currency com o valor da moeda

Copy

Full screen

Small screen

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "currency": "USD"
24  },
25  "purchase": {
26    "subscription": {
27      "plan_id": "54321"
28    }
29  }
30}'

Exemplo de página de seleção de forma de pagamento:

Gere um token para abrir a interface de pagamento ao entrar na página de dados de pagamento

Para fazer com que a interface de pagamento exiba a página de entrada de dados de pagamento quando aberta, passe os seguintes parâmetros na chamada de API Criar token:

purchase.subscription.plan_id com o ID do plano selecionado.
settings.payment_methodcom o ID do método de pagamento. Para encontrar a lista de identificadores, em seu projeto na Conta de Distribuidor, acesse a seção Pay Station > Payment methods ou solicite-a ao seu Gerente de Sucesso do Cliente.

Se os planos com uma taxa de assinatura associada ao primeiro pagamento estiverem definidos em seu projeto, você também precisará passar os seguintes parâmetros:

purchase.checkout.amount com o preço do plano de assinatura
purchase.checkout.currency com o valor da moeda

Passe parâmetros adicionais para personalização, se necessário.

Copy

Full screen

Small screen

 1curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
 2-X POST \
 3-u your_merchant_id:merchant_api_key \
 4-H 'Content-Type:application/json' \
 5-H 'Accept: application/json' \
 6-d '
 7{
 8  "user":{
 9    "id":{
10      "value": "1234567",
11      "hidden": true
12    },
13    "email": {
14      "value": "user1234@game1234.com"
15    },
16    "name": {
17      "value": "UserName",
18      "hidden": false
19    }
20  },
21  "settings": {
22    "project_id": 12345,
23    "payment_method": 1380,
24    "currency": "USD"
25  },
26  "purchase": {
27    "subscription": {
28      "plan_id": "54321"
29    }
30  }
31}'

Exemplo de página de entrada de dados de pagamento:

Abertura da interface de pagamento

Se quiser permitir que os usuários troquem seus planos de assinatura, defina as configurações necessárias no seu projeto e implemente a abertura da interface de pagamento como descrito na instrução How to allow a user to change a subscription plan.

EXEMPLO: CARREGAMENTO DE SCRIPT ASSÍNCRONO

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

A Pay Station Embed permite obter eventos da interface de pagamento via postMessage. Você pode enviar esses eventos para sistemas de análise. Para configurar o processamento de eventos em seu sistema de análise, entre em contato com seu Gerente de Sucesso da Conta ou envie um e-mail para csm@xsolla.com.

A equipe Xsolla criou um widget que simplifica a integração da interface de pagamento em seu site. O script do widget está disponível em nosso repositório GitHub.

Parâmetros de inicialização do script:

Parâmetro	Tipo	Descrição
access_token	string	Token, recebido via API. Obrigatório.
sandbox	boolean	Defina como `true` para testar o processo de pagamento: `sandbox-secure.xsolla.com` será usado em vez de `secure.xsolla.com`.
lightbox	object	Parâmetros da lightbox (objeto; somente versão desktop).
payment_widget_ui.lightbox.width	string	Largura do quadro da lightbox. Se `null`, depende da largura do Pay Station. O padrão é `null`.
payment_widget_ui.lightbox.height	string	Altura do quadro da lightbox. Se `null`, depende da altura do Pay Station. O padrão é `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define a ordem do arranjo. O padrão é `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidade do plano de fundo do widget (`0` — totalmente transparente, `1` — completamente opaco). O valor padrão é 60% (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Cor de fundo da sobreposição. O padrão é `#000000`.
payment_widget_ui.lightbox.modal	boolean	Se `true`, o quadro lightbox não poderá ser fechado. O padrão é `false`.
lightbox.closeByClick	boolean	Se `true`, clicar na sobreposição fechará a lightbox. O padrão é `true`.
lightbox.closeByKeyboard	boolean	Se `true`, pressionar ESC fechará a lightbox. O padrão é `true`.
payment_widget_ui.lightbox.contentBackground	string	Cor de fundo do quadro. O padrão é `#ffffff`. Observe que essas mudanças de cor não afetam o iframe do Pay Station em si, apenas as configurações da lightbox que o contém.
payment_widget_ui.lightbox.contentMargin	string	Margem do quadro. O padrão é `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carregamento animado. Pode ser `xsolla` ou `round`. O padrão é `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Cor do cata-vento. Sem valor padrão.
childWindow	object	Opções para a janela filho que contém a interface do Pay Station. Suportado na versão móvel.
childWindow.target	string	Onde abrir a janela do Pay Station. Pode ser `_blank`, `_self`, `_parent`. O padrão é `_blank`.

O script permite que você acompanhe eventos da interface de pagamento. Dependendo do tipo de evento, você pode executar várias ações na página da web.

Lista de eventos:

Parâmetro	Descrição
init	Widget inicializado.
open	Widget aberto.
load	Interface de Payments (Pay Station) carregada.
close	Interface de Pagamento (Pay Station) fechada.
status	O usuário está na página de status.
status-invoice	O usuário está na página de status; pagamento em andamento.
status-delivering	Evento em que o usuário foi movido na página de status, o pagamento foi concluído e estamos enviando uma notificação de pagamento.
status-done	O usuário está na página de status; pagamento creditado na conta do usuário.
status-troubled	Evento em que o usuário foi movido na página de status, mas o pagamento falhou.

Se você quiser inicializar a abertura da interface de pagamento, use o seguinte link: https://secure.xsolla.com/paystation4/?token=TOKEN.

É necessário usar o link com o prefixo https:// apenas para a abertura da interface de pagamento.

Use o seguinte URL para fins de teste: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

O parâmetro access_token contém dados privados do usuário. Certifique-se de usar a comunicação de servidor para servidor ao obter esse parâmetro.

Para abrir a interface de pagamento em um iframe:

Implemente o mecanismo postMessage para receber eventos da interface de pagamento.
Abra a interface de pagamento seguindo o link https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, onde TOKEN é o token recebido.

Problema em potencial: se um botão para copiar um código de confirmação de pagamento exigido por alguns sistemas de pagamento não for exibido ao abrir a interface de pagamento em um iframe, passe o atributo allow=“clipboard-read; clipboard-write; payment” ao iframe.

Exemplo:

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

Nesse cenário, todas as operações com dados do plano de assinatura são gerenciados usando chamadas de servidor da Xsolla API. Isso permite que você recupere a lista de planos, exiba o catálogo e publique a interface de pagamento diretamente do cliente.

Se seu projeto inclui planos de assinatura com uma taxa de assinatura associado com o primeiro pagamento, use o cenário do lado do servidor para obter o link de abertura da interface de pagamento.

Para implementar a exibição de catálogos de assinaturas e a abertura da interface de pagamento:

Implementar a recuperação de uma lista de planos de assinatura usando um chamado do lado do cliente (opcional).
- Se seu projeto possui produtos com base em assinatura configurados, use o método para obter os planos de assinatura por produtos
- se seu projeto não tem produtos com base em assinaturas configurados, use o método para obter a lista de planos

Você pode armazenar a lista de planos localmente e usar os dados para construir o catálogo. Nesse caso, não há a necessidade de chamar o método API para recuperar a lista de planos. Você também pode usar as bibliotecas SDK para implementar um catálogo na sua própria interface. Bibliotecas pré-prontas facilitam a integração de produtos Xsolla no seu projeto fornecendo estruturas de dados diferenciados e métodos para trabalhar com a Xsolla API.

Implemente a exibição do catálogo do seu lado.
Implemente a geração de tokens para abrir a interface de pagamento para a compra de assinatura. Para fazer isso, use a chamada do lado do cliente para obter o link da interface de pagamento.
Implemente a abertura de interface de pagamento.

Método do lado do cliente para obter os planos de assinatura por produtos

No lado do cliente do seu aplicativo, use uma solicitação HTTP GET para implementar a obtenção da lista de planos: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/products/{productId}/plans.

A solicitação deve conter um cabeçalho Authorization: Bearer <client_user_jwt>, onde <client_user_jwt> é o JSON Web Token (JWT) do usuário — um token exclusivo codificado em Base64. Para obter o token:

Use Register new user e Auth by username, e as chamadas de API de senha se seu aplicativo usar autorização de login e senha.
Use a chamada de API Auth via social network se seu aplicativo usar autorização por meio de redes sociais.

Especifique como os parâmetros de caminho:

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

productID — ID do produto baseado na assinatura. Para obtê-lo, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Especifique como parâmetros de consulta:

Parâmetro	Tipo	Descrição
plan_id	matriz de números inteiros	ID do plano.
plan_external_id	array of strings	ID externo do plano. Pode ser encontrado na Conta de Distribuidor na seção Items catalog > Subscriptions > Subscription plans > your plan ou por meio da chamada de API Obter Planos.
limit	integer	Limite para o número de elementos na página. 15 itens são exibidos por padrão.
offset	integer	Número do elemento a partir do qual a lista é gerada. A contagem começa em 0 por padrão.
locale	string	Idioma da interface em duas letras minúsculas, de acordo com o padrão ISO 639-1. Se este parâmetro não for passado, o idioma será determinado pelo endereço IP do usuário. Se a localização passada não estiver na lista da Xsolla, o idioma inglês será usado por padrão.
country	string	A designação de duas letras ISO 3166-1 alpha-2 é usada para identificar o país do usuário. Esse parâmetro afeta a escolha da localidade e moeda. Se esse parâmetro não for passado, o país será determinado pelo endereço IP do usuário.

Copy

Full screen

Small screen

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/products/{productId}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

Copy

Full screen

Small screen

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

Método do lado do cliente para obter a lista de planos

No lado do cliente do seu aplicativo, use uma solicitação HTTP GET para implementar a obtenção da lista de planos: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/plans.

Use Register new user e Auth by username, e as chamadas de API de senha se seu aplicativo usar autorização de login e senha.
Use a chamada de API Auth via social network se seu aplicativo usar autorização por meio de redes sociais.

Especifique a 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:

Parâmetro	Tipo	Descrição
plan_id	matriz de números inteiros	ID do plano.
plan_external_id	array of strings	ID externo do plano. Pode ser encontrado na Conta de Distribuidor na seção Items catalog > Subscriptions > Subscription plans > your plan ou por meio da chamada de API Obter Planos.
limit	integer	Limite para o número de elementos na página. 15 itens são exibidos por padrão.
offset	integer	Número do elemento a partir do qual a lista é gerada. A contagem começa em 0 por padrão.
locale	string	Idioma da interface em duas letras minúsculas, de acordo com o padrão ISO 639-1. Se este parâmetro não for passado, o idioma será determinado pelo endereço IP do usuário. Se a localização passada não estiver na lista da Xsolla, o idioma inglês será usado por padrão.
country	string	A designação de duas letras ISO 3166-1 alpha-2 é usada para identificar o país do usuário. Esse parâmetro afeta a escolha da localidade e moeda. Se esse parâmetro não for passado, o país será determinado pelo endereço IP do usuário.

Copy

Full screen

Small screen

1curl -X 'GET' \
2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/plans?country=RU  ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

Copy

Full screen

Small screen

 1{
 2  "items": [
 3    {
 4      "plan_id": 54321,
 5      "plan_external_id": "PlanExternalId",
 6      "plan_group_id": "TestGroupId",
 7      "plan_type": "all",
 8      "plan_name": "Localized plan name",
 9      "plan_description": "Localized plan description",
10      "plan_start_date": "2021-04-11T13:51:02+03:00",
11      "plan_end_date": "2031-04-11T13:51:02+03:00",
12      "trial_period": 7,
13      "period": {
14        "value": 1,
15        "unit": "month"
16      },
17      "charge": {
18        "amount": 4.99,
19        "setup_fee": 0.99,
20        "currency": "USD"
21      },
22      "promotion": {
23        "promotion_charge_amount": 3.99,
24        "promotion_remaining_charges": 3
25      }
26    }
27  ],
28  "has_more": false
29}

Método do cliente para obter um link para abrir uma interface de pagamento

No lado do cliente do seu aplicativo, use uma solicitação HTTP POST para implementar a abertura da interface de pagamento: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions/buy.

Use Register new user e Auth by username, e as chamadas de API de senha se seu aplicativo usar autorização de login e senha.
Use a chamada de API Auth via social network se seu aplicativo usar autorização por meio de redes sociais.

Especifique a 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 country como parâmetro de consulta — a designação de duas letras do país do usuário de acordo com o padrão ISO 3166-1 alfa-2. Afeta a escolha de localidade e moeda. Se esse parâmetro não for passado, o país será determinado pelo endereço IP do usuário.

Passe os seguintes parâmetros na solicitação:

plan_external_id para abrir a interface de pagamento na página de seleção de forma de pagamento.

Um exemplo de uma interface de pagamento:

plan_external_id e settings.payment_method abrir a interface de pagamento na página para inserir dados de pagamento.

Um exemplo de uma interface de pagamento:

Parâmetros do corpo da solicitação:

Parâmetro	Tipo	Descrição
plan_external_id	string	Obrigatório. O ID externo do plano de assinatura. Você pode encontrá-lo na seção Conta de Distribuidor > Items catalog > Subscriptions > Subscription plans.
settings	object	Configurações personalizadas do projeto (objeto).
settings.ui	object	Configurações da interface (objeto).
settings.ui.theme	string	Tema da interface de pagamento. Pode ser `default`, `default_dark` ou ID de tema personalizado.
settings.ui.version	string	Tipo de dispositivo. Pode ser `desktop` (padrão) ou `mobile`.
settings.ui.desktop	object	Configurações de interface para a versão desktop (objeto).
settings.ui.desktop.header	object	Configurações de cabeçalho (objeto).
settings.ui.desktop.header.close_button	boolean	Se deseja mostrar um botão Fechar na Pay Station para desktop ou não. O botão fecha a Pay Station e redireciona o usuário para o URL especificado no parâmetro `settings.return_url`. `false` por padrão.
settings.ui.desktop.header.is_visible	boolean	Se o cabeçalho deve ser exibido na interface de pagamento ou não.
settings.ui.desktop.header.type	string	Aparência do cabeçalho. Pode ser `compact` (caso em que o nome do jogo e ID do usuário não é mostrado no cabeçalho) ou `normal`.
settings.ui.desctop.header.visible_logo	boolean	Se `true`, o cabeçalho mostra seu logotipo (primeiro forneça a imagem ao seu Gerente de Sucesso do Cliente).
settings.ui.desktop.header.visible_name	boolean	Se o nome do projeto no cabeçalho deve ser exibido ou não.
settings.ui.desktop.header.type	string	Como mostrar o cabeçalho. Pode ser `compact` (oculta o nome do projeto e o ID do usuário) ou `normal` (padrão).
settings.ui.mobile.header.close_button	boolean	Se deseja mostrar um botão Fechar na Pay Station para dispositivos móveis ou não. O botão fecha a Pay Station e redireciona o usuário para o URL especificado no parâmetro `settings.return_url`. `false` por padrão.
settings.ui.mode	string	Modo de interface na Pay Station. Pode ser `user_account` apenas: o cabeçalho contém apenas o menu de navegação da conta e o usuário não pode selecionar um produto ou fazer um pagamento. Esse modo só está disponível na versão para desktop.
settings.currency	string	Moeda de pagamento preferida. Código de moeda de três letras ISO 4217.
settings.external_id	string	ID da transação no jogo. Deve ser único para cada pagamento de usuário.
settings.payment_method	integer	ID do método de pagamento. Você pode obter a lista de IDs de métodos de pagamento na Conta de Distribuidor.
settings.return_url	string	Página para redirecionar o usuário após o pagamento. Parâmetros `user_id`, `foreigninvoice`, `invoice_id` e `status` serão adicionados automaticamente ao link.
settings.redirect_policy	object	Configurações de política de redirecionamento (objeto).
settings.redirect_policy.redirect_conditions	string	Um status de pagamento que redireciona o usuário para um URL de retorno após fazer um pagamento. Pode ser `none`, `successful`, `successful_or_canceled` ou `any`.
settings.redirect_policy.delay	integer	Atraso (em segundos) após o qual um usuário é redirecionado automaticamente para o URL de retorno.
settings.redirect_policy.status_for_manual_redirection	string	Um status de pagamento que redireciona o usuário para um URL de retorno após fazer um pagamento. Pode ser `none`, `successful`, `successful_or_canceled` ou `any`.
settings.redirect_policy.redirect_button_caption	string	Texto no botão para redirecionamento manual.

Passe parâmetros adicionais para personalização, se necessário.

Copy

Full screen

Small screen

 1curl -X 'POST' \
 2'https://subscriptions.xsolla.com/api/user/v1/projects/{project_id}/subscriptions/buy?country=RU  ' \
 3  -H 'accept: application/json' \
 4  -H 'Authorization: Bearer client_user_jwt'
 5
 6  {
 7    "plan_external_id": "PlanExternalId",
 8    "settings": {
 9      "ui": {
10        "size": "large",
11        "theme": "string",
12        "version": "desktop",
13        "desktop": {
14          "header": {
15            "is_visible": true,
16            "visible_logo": true,
17            "visible_name": true,
18            "type": "compact",
19            "close_button": true
20          }
21        },
22        "mobile": {
23          "mode": "saved_accounts",
24          "footer": {
25            "is_visible": true
26          },
27          "header": {
28            "close_button": true
29          }
30        },
31        "mode": "user_account"
32        }
33      },
34      "currency": "string",
35      "locale": "string",
36      "external_id": "string",
37      "payment_method": 1,
38      "return_url": "string",
39      "redirect_policy": {
40        "redirect_conditions": "none",
41        "delay": 0,
42        "status_for_manual_redirection": "none",
43        "redirect_button_caption": "string"
44      }
45    }

Copy

Full screen

Small screen

1{
2  "link_to_ps": "https://secure.xsolla.com/paystation2/?access_token=<access_token>"
3}

Abertura da interface de pagamento

EXEMPLO: CARREGAMENTO DE SCRIPT ASSÍNCRONO

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

A equipe Xsolla criou um widget que simplifica a integração da interface de pagamento em seu site. O script do widget está disponível em nosso repositório GitHub.

Parâmetros de inicialização do script:

Parâmetro	Tipo	Descrição
access_token	string	Token, recebido via API. Obrigatório.
sandbox	boolean	Defina como `true` para testar o processo de pagamento: `sandbox-secure.xsolla.com` será usado em vez de `secure.xsolla.com`.
lightbox	object	Parâmetros da lightbox (objeto; somente versão desktop).
payment_widget_ui.lightbox.width	string	Largura do quadro da lightbox. Se `null`, depende da largura do Pay Station. O padrão é `null`.
payment_widget_ui.lightbox.height	string	Altura do quadro da lightbox. Se `null`, depende da altura do Pay Station. O padrão é `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define a ordem do arranjo. O padrão é `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidade do plano de fundo do widget (`0` — totalmente transparente, `1` — completamente opaco). O valor padrão é 60% (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Cor de fundo da sobreposição. O padrão é `#000000`.
payment_widget_ui.lightbox.modal	boolean	Se `true`, o quadro lightbox não poderá ser fechado. O padrão é `false`.
lightbox.closeByClick	boolean	Se `true`, clicar na sobreposição fechará a lightbox. O padrão é `true`.
lightbox.closeByKeyboard	boolean	Se `true`, pressionar ESC fechará a lightbox. O padrão é `true`.
payment_widget_ui.lightbox.contentBackground	string	Cor de fundo do quadro. O padrão é `#ffffff`. Observe que essas mudanças de cor não afetam o iframe do Pay Station em si, apenas as configurações da lightbox que o contém.
payment_widget_ui.lightbox.contentMargin	string	Margem do quadro. O padrão é `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carregamento animado. Pode ser `xsolla` ou `round`. O padrão é `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Cor do cata-vento. Sem valor padrão.
childWindow	object	Opções para a janela filho que contém a interface do Pay Station. Suportado na versão móvel.
childWindow.target	string	Onde abrir a janela do Pay Station. Pode ser `_blank`, `_self`, `_parent`. O padrão é `_blank`.

O script permite que você acompanhe eventos da interface de pagamento. Dependendo do tipo de evento, você pode executar várias ações na página da web.

Lista de eventos:

Parâmetro	Descrição
init	Widget inicializado.
open	Widget aberto.
load	Interface de Payments (Pay Station) carregada.
close	Interface de Pagamento (Pay Station) fechada.
status	O usuário está na página de status.
status-invoice	O usuário está na página de status; pagamento em andamento.
status-delivering	Evento em que o usuário foi movido na página de status, o pagamento foi concluído e estamos enviando uma notificação de pagamento.
status-done	O usuário está na página de status; pagamento creditado na conta do usuário.
status-troubled	Evento em que o usuário foi movido na página de status, mas o pagamento falhou.

Se você quiser inicializar a abertura da interface de pagamento, use o seguinte link: https://secure.xsolla.com/paystation4/?token=TOKEN.

É necessário usar o link com o prefixo https:// apenas para a abertura da interface de pagamento.

Use o seguinte URL para fins de teste: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

O parâmetro access_token contém dados privados do usuário. Certifique-se de usar a comunicação de servidor para servidor ao obter esse parâmetro.

Para abrir a interface de pagamento em um iframe:

Implemente o mecanismo postMessage para receber eventos da interface de pagamento.
Abra a interface de pagamento seguindo o link https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, onde TOKEN é o token recebido.

Exemplo:

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

Nesse cenário, o catálogo de assinaturas é exibido diretamente na interface de pagamento da Xsolla, eliminando a necessidade de se implementar uma interface personalizada para a lista de planos. Essa abordagem simplifica a integração e garante atualizações automáticas nos dados dos planos de assinatura.

Para configurar a geração de tokens e abrir a interface de pagamento com o catálogo de assinaturas:

Implemente a obtenção do token por meio da chamada de API Criar token do lado do servidor. Passe os seguintes parâmetros na solicitação:
- user.id — ID do usuário em seu sistema de autorização.
- user.email — e-mail do usuário. Deve ser válido de acordo com o protocolo RFC 822.
- settings.project_id — ID do projeto. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto.

Exemplo de solicitação:

Copy

Full screen

Small screen

 1{
 2    "user": {
 3        "name": {
 4            "value": "j.smith@email.com"
 5        },
 6        "id": {
 7            "value": "123a345b678c091d"
 8        }
 9    },
10    "settings": {
11        "project_id": 177226
12    }
13}

Implemente a abertura da interface de pagamento de uma das seguintes maneiras:

EXEMPLO: CARREGAMENTO DE SCRIPT ASSÍNCRONO

Copy

Full screen

Small screen

 1<script>
 2   var options = {
 3       access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
 4       sandbox: true //TODO please do not forget to remove this setting when going live
 5   };
 6   var s = document.createElement('script');
 7   s.type = "text/javascript";
 8   s.async = true;
 9   s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.0/widget.min.js";
10   s.addEventListener('load', function (e) {
11       XPayStationWidget.init(options);
12   }, false);
13   var head = document.getElementsByTagName('head')[0];
14   head.appendChild(s);
15</script>
16
17<button data-xpaystation-widget-open>Buy Credits</button>

A equipe Xsolla criou um widget que simplifica a integração da interface de pagamento em seu site. O script do widget está disponível em nosso repositório GitHub.

Parâmetros de inicialização do script:

Parâmetro	Tipo	Descrição
access_token	string	Token, recebido via API. Obrigatório.
sandbox	boolean	Defina como `true` para testar o processo de pagamento: `sandbox-secure.xsolla.com` será usado em vez de `secure.xsolla.com`.
lightbox	object	Parâmetros da lightbox (objeto; somente versão desktop).
payment_widget_ui.lightbox.width	string	Largura do quadro da lightbox. Se `null`, depende da largura do Pay Station. O padrão é `null`.
payment_widget_ui.lightbox.height	string	Altura do quadro da lightbox. Se `null`, depende da altura do Pay Station. O padrão é `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define a ordem do arranjo. O padrão é `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidade do plano de fundo do widget (`0` — totalmente transparente, `1` — completamente opaco). O valor padrão é 60% (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Cor de fundo da sobreposição. O padrão é `#000000`.
payment_widget_ui.lightbox.modal	boolean	Se `true`, o quadro lightbox não poderá ser fechado. O padrão é `false`.
lightbox.closeByClick	boolean	Se `true`, clicar na sobreposição fechará a lightbox. O padrão é `true`.
lightbox.closeByKeyboard	boolean	Se `true`, pressionar ESC fechará a lightbox. O padrão é `true`.
payment_widget_ui.lightbox.contentBackground	string	Cor de fundo do quadro. O padrão é `#ffffff`. Observe que essas mudanças de cor não afetam o iframe do Pay Station em si, apenas as configurações da lightbox que o contém.
payment_widget_ui.lightbox.contentMargin	string	Margem do quadro. O padrão é `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carregamento animado. Pode ser `xsolla` ou `round`. O padrão é `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Cor do cata-vento. Sem valor padrão.
childWindow	object	Opções para a janela filho que contém a interface do Pay Station. Suportado na versão móvel.
childWindow.target	string	Onde abrir a janela do Pay Station. Pode ser `_blank`, `_self`, `_parent`. O padrão é `_blank`.

O script permite que você acompanhe eventos da interface de pagamento. Dependendo do tipo de evento, você pode executar várias ações na página da web.

Lista de eventos:

Parâmetro	Descrição
init	Widget inicializado.
open	Widget aberto.
load	Interface de Payments (Pay Station) carregada.
close	Interface de Pagamento (Pay Station) fechada.
status	O usuário está na página de status.
status-invoice	O usuário está na página de status; pagamento em andamento.
status-delivering	Evento em que o usuário foi movido na página de status, o pagamento foi concluído e estamos enviando uma notificação de pagamento.
status-done	O usuário está na página de status; pagamento creditado na conta do usuário.
status-troubled	Evento em que o usuário foi movido na página de status, mas o pagamento falhou.

Se você quiser inicializar a abertura da interface de pagamento, use o seguinte link: https://secure.xsolla.com/paystation4/?token=TOKEN.

É necessário usar o link com o prefixo https:// apenas para a abertura da interface de pagamento.

Use o seguinte URL para fins de teste: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

O parâmetro access_token contém dados privados do usuário. Certifique-se de usar a comunicação de servidor para servidor ao obter esse parâmetro.

Para abrir a interface de pagamento em um iframe:

Implemente o mecanismo postMessage para receber eventos da interface de pagamento.
Abra a interface de pagamento seguindo o link https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, onde TOKEN é o token recebido.

Exemplo:

Copy

Full screen

Small screen

1<iframe
2  src="https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN"
3  width="800"
4  height="930"
5  allow="clipboard-read; clipboard-write; payment"
6></iframe>

Um exemplo de exibição do catálogo de assinaturas na Xsolla Pay Station:

Nesse cenário, todos os elementos do catálogo e lógica de compra são configurados diretamente dentro do construtor de sites, sem ser preciso usar a API.

Para adicionar a venda de assinaturas, você precisa adicionar um botão ao seu site e configurar a ação Purchase subscription para ele. Você pode personalizar botões nos blocos Header, Card grid, e Game editions.

Recomendamos usar o bloco Cards grid para a venda de assinaturas — ele oferece opções extensas de personalização tanto para os cartões em si quanto o layout deles.

Para disponibilizar as assinaturas para compra no site:

Abra seu projeto na Conta de Distribuidor e vá para a seção Storefronts > Websites.
Selecione seu site e pressione Open Site Builder.
Na área principal do construtor, escolha um lugar onde você deseja adicionar um novo bloco e selecione Add block.
Adicione o bloco Card grid e configure-o. Por exemplo, especifique um título, defina um plano de fundo e adicione textos.
Na área principal do construtor, configure a grade do cartão:

1. Para dividir qualquer área de grade verticalmente ou horizontalmente, clique no ícone com uma linha vertical ou horizontal no canto superior esquerdo da área.

1. Para definir a altura ou comprimento de uma área, arraste o ícone ║ ou ═.

Acesse as configurações do cartão. Para fazer isso, clique no ícone ⚙.

Adicione um botão de compra de assinatura ao cartão:

1. Selecione Add button.

1. Na lista suspensa Action, selecione Purchase subscription.
2. Na lista suspensa Subscription plan, selecione o plano que você criou anteriormente.

A lista exibe somente as assinaturas com o tipo Regular plan.

Se o plano que você precisa não estiver na lista, clique em Add new plan e configure um plano de assinatura na Conta de Distribuidor.

1. Altere o estilo do botão (opcional).

Personalize o texto do botão de compra de assinatura (opcional):

1. Na área principal do construtor, clique no texto do botão.
2. Insira o texto desejado. Por padrão, o botão exibe o preço de assinatura ou a quantidade de dias de teste, se houver um período de testes definido no plano de assinatura. Ao editar o texto, você também pode incluir o preço de assinatura ou período de testes usando as seguintes variáveis:

1. - {priceDefault} — preço base. Se houver um desconto, esse valor será riscado.
  - {pricePromo} — o preço final de assinatura com desconto.
  - {trial} — quantidade de dias de teste.

Por padrão, o texto é determinado automaticamente por essas regras:

{trial} day(s) for free — se a assinatura tiver um período de teste.
{priceDefault} {pricePromo} per month — se a assinatura não tiver um período de testes, mas estiver com desconto.
{priceDefault} per month — se a assinatura não tiver um período de teste e não estiver com desconto.
Manage plan — se o usuário atualmente autenticado tiver uma assinatura ativa. Esse texto não pode ser alterado no construtor e será exibido mesmo se você definir um texto personalizado para o botão.

Para restaurar o texto padrão, clique no texto do botão, exclua o texto personalizado e desfocalize o botão.

Defina as outras configurações do cartão. Por exemplo, você pode adicionar textos, imagens e um plano de fundo.
Configure outros cartões na grade.

Exemplo de assinatura recorrente:

Exemplo de assinatura com período de testes:

Exemplo de assinatura com desconto:

Exemplo de tabela de precificação de assinatura:

Conclua a configuração do seu site:
- Configure o tema visual do site.
- Adicione blocos adicionais ao site. Para fazer isso, selecione Add block e selecione o bloco que será exibido no site. Para ver a lista completa de blocos, consulte as instruções.
- Edite o conteúdo de cada bloco. Para fazer isso, adicione imagens e edite textos na parte principal do construtor que os usuários verão.
- Configure os termos de SEO e configurações de tradução (opcional).
- Adicione páginas de site adicionais (opcional).
Para tornar seu site publicamente disponível, publique-o:

1. No canto superior direito do construtor de sites, selecione Publish.

1. Marque as caixas próximas às páginas que deseja publicar.

1. Confirme que o site está pronto para publicação, e selecione Publish.

Se a publicação do site não estiver disponível, certifique-se de que todas as condições sejam cumpridas:

Não há seções vazias no site (marcadas com um indicador vermelho).
O Acordo de Licenciamento com a Xsolla foi assinado.
A página principal foi publicada ou selecionada para publicação. Você não pode publicar páginas descendentes antes da principal.

Aprimore as configurações (opcional):
1. 1. Acesse a selçai Storefronts > Websites e selecione Configure no painel do seu site.
1. 1. Para conectar seu próprio domínio, acesse a seção Site settings > Domain e faça alterações ao Domínio Xsolla ou conecte seu próprio domínio.
1. 1. Para monitorar a eficiência do site, acesse a seção Site settings > Apps e selecione e conecte serviços para promoção e análises.

Obrigado pelo seu feedback!

Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.

Última atualização: 12 de Dezembro de 2025

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Conteúdos

Gere um token para abrir a interface de pagamento na página de seleção de métodos de pagamento
Gere um token para abrir a interface de pagamento ao entrar na página de dados de pagamento
Abertura da interface de pagamento
Método do lado do cliente para obter os planos de assinatura por produtos
Método do lado do cliente para obter a lista de planos
Método do cliente para obter um link para abrir uma interface de pagamento
Abertura da interface de pagamento

Your browser is not supported. Please try a different browser

Configure a exibição e compra do catálago de assinaturas

Gere um token para abrir a interface de pagamento na página de seleção de métodos de pagamento

Gere um token para abrir a interface de pagamento ao entrar na página de dados de pagamento

Abertura da interface de pagamento

access_token

sandbox

lightbox

payment_widget_ui.lightbox.width

payment_widget_ui.lightbox.height

payment_widget_ui.lightbox.zIndex

payment_widget_ui.lightbox.overlayOpacity

payment_widget_ui.lightbox.overlayBackground

payment_widget_ui.lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

payment_widget_ui.lightbox.contentBackground

payment_widget_ui.lightbox.contentMargin

payment_widget_ui.lightbox.spinner

payment_widget_ui.lightbox.spinnerColor

childWindow

childWindow.target

Método do lado do cliente para obter os planos de assinatura por produtos

plan_id

plan_external_id

limit

offset

locale

country

Método do lado do cliente para obter a lista de planos

plan_id

plan_external_id

limit

offset

locale

country

Método do cliente para obter um link para abrir uma interface de pagamento

plan_external_id

settings

settings.ui

settings.ui.theme

settings.ui.version

settings.ui.desktop

settings.ui.desktop.header

settings.ui.desktop.header.close_button

settings.ui.desktop.header.is_visible

settings.ui.desktop.header.type

settings.ui.desctop.header.visible_logo

settings.ui.desktop.header.visible_name

settings.ui.desktop.header.type

settings.ui.mobile.header.close_button

settings.ui.mode

settings.currency

settings.external_id

settings.payment_method

settings.return_url

settings.redirect_policy

settings.redirect_policy.redirect_conditions

settings.redirect_policy.delay

settings.redirect_policy.status_for_manual_redirection

settings.redirect_policy.redirect_button_caption

Abertura da interface de pagamento

access_token

sandbox

lightbox

payment_widget_ui.lightbox.width

payment_widget_ui.lightbox.height

payment_widget_ui.lightbox.zIndex

payment_widget_ui.lightbox.overlayOpacity

payment_widget_ui.lightbox.overlayBackground

payment_widget_ui.lightbox.modal

lightbox.closeByClick

lightbox.closeByKeyboard

payment_widget_ui.lightbox.contentBackground

payment_widget_ui.lightbox.contentMargin

payment_widget_ui.lightbox.spinner

payment_widget_ui.lightbox.spinnerColor

childWindow

childWindow.target

access_token