Configurar la visualización y compra del catálogo de suscripciones

La implementación del catálogo de suscripciones depende de cómo integre las suscripciones en su proyecto:

Si integra la venta de suscripciones en su propia aplicación o sitio web, puede:
- Crear la interfaz de usuario del catálogo por su cuenta utilizando los datos del plan de suscripción de la API de Xsolla o sus datos locales.
- Mostrar el catálogo de suscripciones utilizando la interfaz de pago de Xsolla, sin necesidad de obtener los datos del plan aparte.
Si está creando un sitio web con Xsolla Site Builder, la interfaz de usuario del catálogo debe colocarse directamente dentro del diseño del sitio web. En este caso, no es necesario obtener los datos del plan ni implementar la interfaz de pago por separado.

Elija dónde quiere mostrar el catálogo de suscripciones:

Elija una opción de autenticación para comprar suscripciones:

En este escenario, usted implementa la visualización del catálogo de suscripciones por su cuenta y gestiona el flujo de compras a través de su propio servidor. Todas las interacciones con Xsolla se efectúan mediante llamadas al servidor de la API de Xsolla.

Para implementar la visualización del catálogo de suscripciones y la apertura de la interfaz de pago:

Implemente la obtención de una lista de planes de suscripción utilizando la llamada del lado del servidor Obtener planes (opcional).

Puede almacenar la lista de planes localmente y utilizar esos datos para crear el catálogo. En este caso, no es necesario llamar al método API para obtener la lista de planes.

Implemente la visualización del catálogo por su parte.
Implemente la generación de tokens para abrir la interfaz de pago para comprar suscripciones de una de las siguientes maneras:
- en la página de selección del método de pago
- en la página de introducción de los datos de pago
Implemente la apertura de la interfaz de pago.

Generar token para abrir la interfaz de pago en la página de selección del método de pago

Para que la interfaz de usuario de pago muestre la página de selección del método de pago cuando se abra, transmita el parámetro purchase.subscription.plan_id con el ID del plan seleccionado a la llamada API Crear token. Transmita parámetros de personalización adicionales si es necesario.

Si en su proyecto se establecen planes con una cuota de suscripción asociada al primer pago, también deberá transmitir los siguientes parámetros:

purchase.checkout.amount con el precio del plan de suscripción
purchase.checkout.currency con el valor de la moneda

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}'

Ejemplo de página de selección del método de pago:

Generar token para abrir la interfaz de pago al entrar en la página de datos de pago

Para que la interfaz de usuario de pago muestre la página de introducción de datos de pago cuando se abra, transmita los siguientes parámetros en la llamada API Crear token:

purchase.subscription.plan_id con el ID del plan seleccionado.
settings.payment_method con el ID del método de pago. Para encontrar la lista de identificadores, en su proyecto en Cuenta del editor, vaya a Payments > Payment methods, o solicítela a su gestor del éxito del cliente.

Si en su proyecto se establecen planes con una cuota de suscripción asociada al primer pago, también deberá transmitir los siguientes parámetros:

purchase.checkout.amount con el precio del plan de suscripción
purchase.checkout.currency con el valor de la moneda

Transmita parámetros adicionales para la personalización si es necesario.

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}'

Ejemplo de página de introducción de datos de pago:

Abrir la interfaz de pago

Si quiere que los usuarios puedan cambiar su plan de suscripción, configure los ajustes necesarios en su proyecto e implemente la interfaz de pago tal y como se describe en las instrucciones de Cómo permitir que un usuario cambie un plan de suscripción.

EJEMPLO: CARGA ASINCRÓNICA DE SCRIPTS

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>

Pay Station Embed permite obtener eventos de la interfaz de pago a través de postMessage. Puede enviar estos eventos a sistemas de análisis. Para configurar el procesamiento de eventos en su sistema analítico, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

El equipo de Xsolla ha creado un widget que simplifica la integración de la interfaz de pago en su sitio web. El script del widget está disponible en nuestro repositorio de GitHub.

Parámetros de inicialización del script:

Parámetro	Tipo	Descripción
access_token	string	Token, recibido a través de API. Obligatorio.
sandbox	boolean	Establécelo en `true` para probar el proceso de pago: `sandbox-secure.xsolla.com` se utilizará en lugar de `secure.xsolla.com`.
lightbox	object	Parámetros del Lightbox (objeto, solo versión de escritorio).
payment_widget_ui.lightbox.width	string	Anchura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `null`.
payment_widget_ui.lightbox.height	string	Altura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define el orden de disposición. Por defecto es `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidad del fondo del widget (`0` - totalmente transparente, `1` - totalmente opaco). El valor por defecto es 60 % (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Color de fondo de la superposición. Por defecto es `#000000`.
payment_widget_ui.lightbox.modal	boolean	Si es `true`, el marco del Lightbox no se puede cerrar. Por defecto es `false`.
lightbox.closeByClick	boolean	Si es `true`, al hacer clic en la superposición se cerrará el Lightbox. Por defecto es `true`.
lightbox.closeByKeyboard	boolean	Si es `true`, al pulsar ESC se cerrará el Lightbox. Por defecto es `true`.
payment_widget_ui.lightbox.contentBackground	string	Color de fondo del marco. Por defecto es `#ffffff`. Tenga en cuenta que estos cambios de color no afectan al propio iframe de Pay Station, solo a la configuración del Lightbox que lo contiene.
payment_widget_ui.lightbox.contentMargin	string	Margen del marco. Por defecto es `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carga animado. Puede ser `xsolla` o `round`. Por defecto es `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Color del indicador giratorio. Sin valor por defecto.
childWindow	object	Opciones para la ventana secundaria que contiene la interfaz de usuario de Pay Station. Compatible con la versión móvil.
childWindow.target	string	Dónde abrir la ventana de Pay Station. Puede ser `_blank`, `_self`, `_parent`. Por defecto es `_blank`.

El script permite realizar un seguimiento de los eventos de la interfaz de pago. En función del tipo de evento, puede realizar diversas acciones en la página web.

Lista de eventos:

Parámetro	Descripción
init	Widget inicializado.
open	Widget abierto.
load	Interfaz de pago (Pay Station) cargada.
close	Interfaz de pago (Pay Station) cerrada.
status	El usuario está en la página de estado.
status-invoice	El usuario está en la página de estado; pago en curso.
status-delivering	Evento cuando el usuario se movió en la página de estado, el pago se finalizó, y estamos enviando la notificación de pago.
status-done	El usuario está en la página de estado; pago abonado en la cuenta del usuario.
status-troubled	Evento cuando el usuario se movió en la página de estado, pero el pago no se pudo procesar.

Si desea inicializar la apertura de la interfaz de pago, utilice el siguiente enlace: https://secure.xsolla.com/paystation4/?token=TOKEN.

Es necesario utilizar el enlace con el prefijo https:// solamente para la apertura de la interfaz de pago.

Utilice la siguiente URL para hacer pruebas: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

El parámetro access_token contiene datos privados del usuario. Asegúrese de utilizar la comunicación de servidor a servidor al obtener este parámetro.

Para abrir la interfaz de pago en un iframe:

Implemente el mecanismo postMessage para recibir eventos de la interfaz de pago.
Abra la interfaz de pago pulsando en el enlace https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, en el cual TOKEN es el token recibido.

Problema potencial: si no aparece un botón para copiar un código de confirmación de pago requerido por algunos sistemas de pago al abrir la interfaz de pago en un iframe, transmita el atributo allow=“clipboard-read; clipboard-write; payment” al iframe.

Ejemplo:

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>

En este escenario, todas las operaciones con datos del plan de suscripción se gestionan mediante llamadas del lado del cliente de la API de Xsolla. Esto le permite obtener la lista de planes, mostrar el catálogo y lanzar la interfaz de pago directamente desde el cliente.

Si su proyecto incluye planes de suscripción con una cuota de suscripción asociada al primer pago, utilice el escenario del lado del servidor para obtener el enlace para abrir la interfaz de pago.

Para implementar la visualización del catálogo de suscripciones y la apertura de la interfaz de pago:

Implemente la obtención de una lista de planes de suscripción mediante una llamada del lado del cliente (opcional).
- si su proyecto tiene productos basados en suscripción configurados, utilice el método para obtener los planes de suscripción por productos
- si su proyecto no tiene productos basados en suscripción configurados, utilice el método para obtener la lista de planes

Puede almacenar la lista de planes localmente y utilizar esos datos para crear el catálogo. En este caso, no es necesario llamar al método API para obtener la lista de planes. También puede utilizar las bibliotecas del SDK para implementar un catálogo en su propia interfaz. Las bibliotecas prediseñadas facilitan la integración de los productos de Xsolla en su proyecto suministrando estructuras de datos listas para usar y métodos para trabajar con la API de Xsolla.

Implemente la visualización del catálogo por su parte.
Implemente la generación de tokens para abrir la interfaz de pago para comprar la suscripción. Para ello, utilice la llamada del lado del cliente para obtener el enlace de la interfaz de pago.
Implemente la apertura de la interfaz de pago.

Método del lado cliente para obtener los planes de suscripción por productos

En el lado cliente de su aplicación, utilice una solicitud HTTP GET para implementar la obtención de la lista de planes: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/products/{productId}/plans.

La solicitud debe contener un encabezado Authorization: Bearer <client_user_jwt>, en el cual <client_user_jwt> es el JSON Web Token (JWT) del usuario, un token único codificado en Base64 según el estándar Base64. Para obtener el token:

Utilice las llamadas API Register new user y Auth by username y de contraseña si su aplicación utiliza la autorización de inicio de sesión y contraseña.
Utilice la llamada API Auth via social network si su aplicación utiliza autorización mediante redes sociales.

Especifique como los parámetros de ruta lo siguiente:

el ID del proyecto (projectId). Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

productID (ID de producto de pago por suscripción). Para obtenerlo, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

Especifique como parámetros de consulta:

Parámetro	Tipo	Descripción
plan_id	array of integers	ID del plan.
plan_external_id	array of strings	ID externo del plan. Puede encontrarse en Cuenta del editor en Items catalog > Subscriptions > Subscription plans > su plan o a través de la llamada API Obtener planes.
limit	integer	Límite para el número de elementos de la página. Por defecto se muestran 15 elementos.
offset	integer	Número del elemento a partir del cual se genera la lista. El recuento comienza en el 0 por defecto.
locale	string	Idioma de la interfaz en dos letras minúsculas conforme a la norma ISO 639-1. Si no se transmite este parámetro, el idioma se determinará mediante la dirección IP del usuario. Si la configuración regional transmitida no figura en la lista de Xsolla, se utilizará el inglés por defecto.
country	string	La designación de dos caracteres ISO 3166-1 alpha-2 se utiliza para identificar el país del usuario. Este parámetro afecta a la elección de la configuración regional y la moneda. Si no se transmite este parámetro, el país viene determinado por la dirección IP del usuario.

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 del lado cliente para obtener la lista de planes

En el lado cliente de su aplicación, utilice una solicitud HTTP GET para obtener la lista de planes: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/plans.

Utilice las llamadas API Register new user y Auth by username y de contraseña si su aplicación utiliza la autorización de inicio de sesión y contraseña.
Utilice la llamada API Auth via social network si su aplicación utiliza autorización mediante redes sociales.

Especifique el ID del proyecto como parámetro de la ruta projectId. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

Especifique como parámetros de consulta:

Parámetro	Tipo	Descripción
plan_id	array of integers	ID del plan.
plan_external_id	array of strings	ID externo del plan. Puede encontrarse en Cuenta del editor en Items catalog > Subscriptions > Subscription plans > su plan o a través de la llamada API Obtener planes.
limit	integer	Límite para el número de elementos de la página. Por defecto se muestran 15 elementos.
offset	integer	Número del elemento a partir del cual se genera la lista. El recuento comienza en el 0 por defecto.
locale	string	Idioma de la interfaz en dos letras minúsculas conforme a la norma ISO 639-1. Si no se transmite este parámetro, el idioma se determinará mediante la dirección IP del usuario. Si la configuración regional transmitida no figura en la lista de Xsolla, se utilizará el inglés por defecto.
country	string	La designación de dos caracteres ISO 3166-1 alpha-2 se utiliza para identificar el país del usuario. Este parámetro afecta a la elección de la configuración regional y la moneda. Si no se transmite este parámetro, el país viene determinado por la dirección IP del usuario.

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 de cliente para obtener un enlace para abrir una interfaz de pago

En el lado cliente de su aplicación, utilice una solicitud HTTP POST para implementar la apertura de la interfaz de pago: https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions/buy.

Utilice las llamadas API Register new user y Auth by username y de contraseña si su aplicación utiliza la autorización de inicio de sesión y contraseña.
Utilice la llamada API Auth via social network si su aplicación utiliza autorización mediante redes sociales.

Especifique el ID del proyecto como parámetro de la ruta projectId. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

Especifique country como parámetro de consulta: la designación de dos letras del país del usuario según la norma ISO 3166-1 alpha-2. Afecta a la elección de la configuración regional y de la moneda. Si no se especifica este parámetro, el país vendrá determinado por la dirección IP del usuario.

Introduzca los siguientes parámetros en la solicitud:

plan_external_id para abrir la interfaz de pago en la página de selección del método de pago.

Un ejemplo de interfaz de pago:

plan_external_id y settings.payment_method para abrir la interfaz de pago presente en la página de introducción de los datos de pago.

Un ejemplo de interfaz de pago:

Parámetros del cuerpo de la solicitud:

Parámetro	Tipo	Descripción
plan_external_id	string	Obligatorio. El ID externo del plan de suscripción. Puede encontrarlo en Cuenta del editor > Items catalog > Subscriptions > Subscription plans.
settings	object	Configuración personalizada del proyecto (objeto).
settings.ui	object	Configuración de la interfaz (objeto).
settings.ui.theme	string	Tema de la interfaz de pago. Puede ser `default`, `default_dark` o ID de tema personalizado.
settings.ui.version	string	Tipo de dispositivo. Puede ser `desktop` (por defecto) o `mobile`.
settings.ui.desktop	object	Configuración de la interfaz para la versión de escritorio (objeto).
settings.ui.desktop.header	object	Configuración del encabezado (objeto).
settings.ui.desktop.header.close_button	boolean	Si se muestra un botón Close en el escritorio de Pay Station. El botón cierra Pay Station y redirige al usuario a la URL especificada en el parámetro `settings.return_url`. `false` por defecto.
settings.ui.desktop.header.is_visible	boolean	Mostrar o no el encabezado en la interfaz de pago.
settings.ui.desktop.header.type	string	Aspecto del encabezado. Puede ser `compact` (en cuyo caso el nombre del juego y el ID de usuario no se muestran en el encabezado) o `normal`.
settings.ui.desctop.header.visible_logo	boolean	Si es `true`, el encabezado muestra su logotipo (proporcione primero la imagen a su gestor del éxito del cliente).
settings.ui.desktop.header.visible_name	boolean	Mostrar o no el nombre del proyecto en el encabezado.
settings.ui.desktop.header.type	string	Cómo mostrar el encabezado. Puede ser `compact` (oculta el nombre del proyecto y el ID de usuario) o `normal` (por defecto).
settings.ui.mobile.header.close_button	boolean	Si se muestra o no un botón Close en la versión móvil de Pay Station. El botón cierra Pay Station y redirige al usuario a la URL especificada en el parámetro `settings.return_url`. `false` por defecto.
settings.ui.mode	string	Modo de interfaz en Pay Station. Solo puede ser `user_account`: el encabezado solo contiene el menú de navegación de la cuenta, y el usuario no puede seleccionar un producto ni realizar un pago. Este modo solo está disponible en la versión de escritorio.
settings.currency	string	Moneda de pago preferida. Código de moneda de tres letras ISO 4217.
settings.external_id	string	ID de la transacción en el juego. Tiene que ser único para cada pago de usuario.
settings.payment_method	integer	ID del método de pago. Puede obtener la lista de ID de métodos de pago en Cuenta del editor.
settings.return_url	string	Página a la que redirigir al usuario tras el pago. Los parámetros `user_id`, `foreigninvoice`, `invoice_id` y `status` se añadirán automáticamente al enlace.
settings.redirect_policy	object	Configuración de la política de redireccionamiento (objeto).
settings.redirect_policy.redirect_conditions	string	Un estado de pago que redirige al usuario a una URL de retorno después de realizar un pago. Puede ser `none`, `successful`, `successful_or_canceled` o `any`.
settings.redirect_policy.delay	integer	Retraso (en segundos) tras el cual un usuario es redirigido automáticamente a la URL de retorno.
settings.redirect_policy.status_for_manual_redirection	string	Un estado de pago que redirige al usuario a una URL de retorno después de realizar un pago. Puede ser `none`, `successful`, `successful_or_canceled` o `any`.
settings.redirect_policy.redirect_button_caption	string	Texto que aparece en el botón de redireccionamiento manual.

Transmita parámetros adicionales para la personalización si es necesario.

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}

Abrir la interfaz de pago

EJEMPLO: CARGA ASINCRÓNICA DE SCRIPTS

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>

El equipo de Xsolla ha creado un widget que simplifica la integración de la interfaz de pago en su sitio web. El script del widget está disponible en nuestro repositorio de GitHub.

Parámetros de inicialización del script:

Parámetro	Tipo	Descripción
access_token	string	Token, recibido a través de API. Obligatorio.
sandbox	boolean	Establécelo en `true` para probar el proceso de pago: `sandbox-secure.xsolla.com` se utilizará en lugar de `secure.xsolla.com`.
lightbox	object	Parámetros del Lightbox (objeto, solo versión de escritorio).
payment_widget_ui.lightbox.width	string	Anchura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `null`.
payment_widget_ui.lightbox.height	string	Altura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define el orden de disposición. Por defecto es `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidad del fondo del widget (`0` - totalmente transparente, `1` - totalmente opaco). El valor por defecto es 60 % (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Color de fondo de la superposición. Por defecto es `#000000`.
payment_widget_ui.lightbox.modal	boolean	Si es `true`, el marco del Lightbox no se puede cerrar. Por defecto es `false`.
lightbox.closeByClick	boolean	Si es `true`, al hacer clic en la superposición se cerrará el Lightbox. Por defecto es `true`.
lightbox.closeByKeyboard	boolean	Si es `true`, al pulsar ESC se cerrará el Lightbox. Por defecto es `true`.
payment_widget_ui.lightbox.contentBackground	string	Color de fondo del marco. Por defecto es `#ffffff`. Tenga en cuenta que estos cambios de color no afectan al propio iframe de Pay Station, solo a la configuración del Lightbox que lo contiene.
payment_widget_ui.lightbox.contentMargin	string	Margen del marco. Por defecto es `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carga animado. Puede ser `xsolla` o `round`. Por defecto es `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Color del indicador giratorio. Sin valor por defecto.
childWindow	object	Opciones para la ventana secundaria que contiene la interfaz de usuario de Pay Station. Compatible con la versión móvil.
childWindow.target	string	Dónde abrir la ventana de Pay Station. Puede ser `_blank`, `_self`, `_parent`. Por defecto es `_blank`.

El script permite realizar un seguimiento de los eventos de la interfaz de pago. En función del tipo de evento, puede realizar diversas acciones en la página web.

Lista de eventos:

Parámetro	Descripción
init	Widget inicializado.
open	Widget abierto.
load	Interfaz de pago (Pay Station) cargada.
close	Interfaz de pago (Pay Station) cerrada.
status	El usuario está en la página de estado.
status-invoice	El usuario está en la página de estado; pago en curso.
status-delivering	Evento cuando el usuario se movió en la página de estado, el pago se finalizó, y estamos enviando la notificación de pago.
status-done	El usuario está en la página de estado; pago abonado en la cuenta del usuario.
status-troubled	Evento cuando el usuario se movió en la página de estado, pero el pago no se pudo procesar.

Si desea inicializar la apertura de la interfaz de pago, utilice el siguiente enlace: https://secure.xsolla.com/paystation4/?token=TOKEN.

Es necesario utilizar el enlace con el prefijo https:// solamente para la apertura de la interfaz de pago.

Utilice la siguiente URL para hacer pruebas: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

El parámetro access_token contiene datos privados del usuario. Asegúrese de utilizar la comunicación de servidor a servidor al obtener este parámetro.

Para abrir la interfaz de pago en un iframe:

Implemente el mecanismo postMessage para recibir eventos de la interfaz de pago.
Abra la interfaz de pago pulsando en el enlace https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, en el cual TOKEN es el token recibido.

Ejemplo:

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>

En este escenario, el catálogo de suscripciones se muestra directamente en la interfaz de pago de Xsolla, lo que evita tener que implementar una interfaz personalizada para la lista de planes. Este método simplifica la integración y garantiza que los datos de los planes de suscripción se actualicen automáticamente.

Para configurar la generación de tokens y abrir la interfaz de pago con el catálogo de suscripciones:

Implemente la obtención de tókenes a través de la llamada API del lado del servidor Crear token. Transmita los siguientes parámetros en la solicitud:
- user.id - ID de usuario en su sistema de autorización.
- user.email - Correo electrónico del usuario. Debe ser válido conforme al protocolo RFC 822.
- settings.project_id - ID de proyecto. Puede encontrar este parámetro en su Cuenta del editor junto al nombre del proyecto.

Ejemplo de solicitud:

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 la apertura de la interfaz de pago de una de las siguientes formas:

EJEMPLO: CARGA ASINCRÓNICA DE SCRIPTS

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>

El equipo de Xsolla ha creado un widget que simplifica la integración de la interfaz de pago en su sitio web. El script del widget está disponible en nuestro repositorio de GitHub.

Parámetros de inicialización del script:

Parámetro	Tipo	Descripción
access_token	string	Token, recibido a través de API. Obligatorio.
sandbox	boolean	Establécelo en `true` para probar el proceso de pago: `sandbox-secure.xsolla.com` se utilizará en lugar de `secure.xsolla.com`.
lightbox	object	Parámetros del Lightbox (objeto, solo versión de escritorio).
payment_widget_ui.lightbox.width	string	Anchura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `null`.
payment_widget_ui.lightbox.height	string	Altura del marco del Lightbox. Si es `null`, depende de la altura de Pay Station. Por defecto es `100%`.
payment_widget_ui.lightbox.zIndex	integer	Define el orden de disposición. Por defecto es `1000`.
payment_widget_ui.lightbox.overlayOpacity	integer	Opacidad del fondo del widget (`0` - totalmente transparente, `1` - totalmente opaco). El valor por defecto es 60 % (`.6`).
payment_widget_ui.lightbox.overlayBackground	string	Color de fondo de la superposición. Por defecto es `#000000`.
payment_widget_ui.lightbox.modal	boolean	Si es `true`, el marco del Lightbox no se puede cerrar. Por defecto es `false`.
lightbox.closeByClick	boolean	Si es `true`, al hacer clic en la superposición se cerrará el Lightbox. Por defecto es `true`.
lightbox.closeByKeyboard	boolean	Si es `true`, al pulsar ESC se cerrará el Lightbox. Por defecto es `true`.
payment_widget_ui.lightbox.contentBackground	string	Color de fondo del marco. Por defecto es `#ffffff`. Tenga en cuenta que estos cambios de color no afectan al propio iframe de Pay Station, solo a la configuración del Lightbox que lo contiene.
payment_widget_ui.lightbox.contentMargin	string	Margen del marco. Por defecto es `10px`.
payment_widget_ui.lightbox.spinner	string	Tipo de indicador de carga animado. Puede ser `xsolla` o `round`. Por defecto es `xsolla`.
payment_widget_ui.lightbox.spinnerColor	string	Color del indicador giratorio. Sin valor por defecto.
childWindow	object	Opciones para la ventana secundaria que contiene la interfaz de usuario de Pay Station. Compatible con la versión móvil.
childWindow.target	string	Dónde abrir la ventana de Pay Station. Puede ser `_blank`, `_self`, `_parent`. Por defecto es `_blank`.

El script permite realizar un seguimiento de los eventos de la interfaz de pago. En función del tipo de evento, puede realizar diversas acciones en la página web.

Lista de eventos:

Parámetro	Descripción
init	Widget inicializado.
open	Widget abierto.
load	Interfaz de pago (Pay Station) cargada.
close	Interfaz de pago (Pay Station) cerrada.
status	El usuario está en la página de estado.
status-invoice	El usuario está en la página de estado; pago en curso.
status-delivering	Evento cuando el usuario se movió en la página de estado, el pago se finalizó, y estamos enviando la notificación de pago.
status-done	El usuario está en la página de estado; pago abonado en la cuenta del usuario.
status-troubled	Evento cuando el usuario se movió en la página de estado, pero el pago no se pudo procesar.

Si desea inicializar la apertura de la interfaz de pago, utilice el siguiente enlace: https://secure.xsolla.com/paystation4/?token=TOKEN.

Es necesario utilizar el enlace con el prefijo https:// solamente para la apertura de la interfaz de pago.

Utilice la siguiente URL para hacer pruebas: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN.

El parámetro access_token contiene datos privados del usuario. Asegúrese de utilizar la comunicación de servidor a servidor al obtener este parámetro.

Para abrir la interfaz de pago en un iframe:

Implemente el mecanismo postMessage para recibir eventos de la interfaz de pago.
Abra la interfaz de pago pulsando en el enlace https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, en el cual TOKEN es el token recibido.

Ejemplo:

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>

Un ejemplo de visualización del catálogo de suscripciones en Xsolla Pay Station:

En este escenario, todos los elementos del catálogo y la lógica de compra se configuran directamente en el creador de sitios web, sin necesidad de utilizar la API.

Para añadir la venta de suscripciones, es necesario añadir un botón a su sitio web y configurar la acción Purchase subscription. Puede utilizar botones personalizables en los bloques Header, Card grid y Game editions.

Recomendamos utilizar el bloque Cards grid para la venta de suscripciones, ya que ofrece varias opciones de personalización tanto para las fichas como para su diseño.

Para que las suscripciones estén a la venta en el sitio web:

Abra su proyecto en Cuenta del editor y vaya a Storefronts > Websites.
Seleccione su sitio y haga clic en Open Site Builder.
En el área principal del creador, seleccione el lugar donde quiera añadir un nuevo bloque y haga clic en Add block.
Añada el bloque Card grid y configúrelo. Por ejemplo, especifique un título, establezca un fondo y añada textos.
En el área principal del creador, configure la cuadrícula de fichas:

1. Para dividir cualquier área de la cuadrícula vertical u horizontalmente, haga clic en el icono que tiene una línea vertical u horizontal en la esquina superior izquierda del área.

1. Para establecer la altura o el ancho de un área, arrastre el icono ║ o ═.

Vaya a la configuración de la ficha. Para ello, haga clic en el icono ⚙.

Añada un botón de compra de suscripción a la ficha:

1. Haga clic en Add button.

1. En la lista desplegable Action, seleccione Purchase subscription.
2. En la lista desplegable Subscription plan, seleccione el plan que creó anteriormente.

La lista muestra solo las suscripciones del tipo Regular plan.

Si el plan que necesita no aparece en la lista, haga clic en Add new plan y configure un plan de suscripción en Cuenta del editor.

1. Cambie el estilo del botón (opcional).

Personalice el texto del botón de compra de la suscripción (opcional):

1. En el área principal del creador, haga clic en el texto del botón.
2. Introduzca el texto deseado. Por defecto, el botón muestra el precio de la suscripción o el número de días de prueba si se ha establecido un periodo de prueba en el plan de suscripción seleccionado. Al editar el texto, también puede incluir el precio de la suscripción o el periodo de prueba utilizando las siguientes variables:

1. - {priceDefault}: precio base. Si hay un descuento, este valor aparecerá tachado.
  - {pricePromo}: precio final de suscripción con descuento.
  - {trial}: número de días de prueba.

Por defecto, el texto se determina automáticamente siguiendo estas reglas:

{trial} day(s) for free: si la suscripción tiene un periodo de prueba.
{priceDefault} {pricePromo} per month: si la suscripción no tiene un periodo de prueba, pero tiene descuento.
{priceDefault} per month: si la suscripción no tiene un periodo de prueba y no tiene descuento.
Manage plan: si el usuario autorizado actual tiene una suscripción activa. Este texto no se puede modificar en el creador y se mostrará incluso si se configura manualmente un texto personalizado para el botón.

Para restaurar el texto predeterminado, haga clic en el texto del botón, elimine el texto personalizado y desactive el botón.

Configure otros ajustes de la ficha. Por ejemplo, añada texto, imágenes y fondo.
Configure otras fichas en la cuadrícula.

Ejemplo de suscripción recurrente:

Ejemplo de suscripción con periodo de prueba:

Ejemplo de suscripción con descuento:

Ejemplo de tabla de precios de suscripción:

Complete la configuración de su sitio web:
- Configure el tema visual del sitio web.
- Añada bloques al sitio web. Para ello, haga clic en Add block y seleccione el bloque que aparecerá en el sitio. Para ver la lista completa de bloques, consulte las instrucciones.
- Edite el contenido de cada bloque. Para ello, añada imágenes y edite los textos en la parte principal del creador que verán los usuarios.
- Configure los ajustes de SEO y localización (opcional).
- Añada páginas al sitio (opcional).
Para que su sitio esté disponible, publíquelo:

1. En la esquina superior derecha del creador de sitios web, haga clic en Publish.

1. Marque las casillas junto a las páginas que quiera publicar.

1. Confirme que el sitio web está listo para su publicación y haga clic en Publish.

Si la opción para publicar en el sitio web no está disponible, compruebe que cumple con todos los requisitos:

No hay secciones vacías en el sitio web (marcadas con un indicador rojo).
Se ha firmado el acuerdo de licencia con Xsolla.
La página principal está publicada o seleccionada para su publicación. No puede publicar páginas secundarias antes de publicar la página principal.

Mejore la configuración (opcional):
1. 1. Vaya a Storefronts > Websites y haga clic en Configure en el panel de su sitio web.
1. 1. Para conectar su propio dominio, vaya a Site settings > Domain y haga cambios en Xsolla Domain o conecte su propio dominio.
1. 1. Para hacer un seguimiento de la eficacia del sitio web, vaya a Site settings > Apps y seleccione y conecte servicios para promociones y análisis..

¡Gracias por tu mensaje!

Nos ayudará a mejorar tu experiencia.

Última actualización: 12 de Diciembre de 2025

¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.

Contenidos

Generar token para abrir la interfaz de pago en la página de selección del método de pago
Generar token para abrir la interfaz de pago al entrar en la página de datos de pago
Abrir la interfaz de pago
Método del lado cliente para obtener los planes de suscripción por productos
Método del lado cliente para obtener la lista de planes
Método de cliente para obtener un enlace para abrir una interfaz de pago
Abrir la interfaz de pago

Your browser is not supported. Please try a different browser

Configurar la visualización y compra del catálogo de suscripciones

Generar token para abrir la interfaz de pago en la página de selección del método de pago

Generar token para abrir la interfaz de pago al entrar en la página de datos de pago

Abrir la interfaz de pago

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 del lado cliente para obtener los planes de suscripción por productos

plan_id

plan_external_id

limit

offset

locale

country

Método del lado cliente para obtener la lista de planes

plan_id

plan_external_id

limit

offset

locale

country

Método de cliente para obtener un enlace para abrir una interfaz de pago

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

Abrir la interfaz de pago

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