Obtener información sobre la suscripción

Puede obtener información sobre la actividad relacionada con las suscripciones de las siguientes maneras:

• solicitar información mediante las llamadas API (idónea para la integración sin servidor);
• obtener información cuando el estado de la suscripción cambia automáticamente mediante webhooks (idónea para la integración con servidor).

Configurar mediante API

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

Especifique como parámetros de consulta:

• limit - límite para el número de elementos que aparecen en la página (por defecto se muestran 15 elementos).
• offset - número del elemento a partir del cual se genera la lista (el recuento empieza en el 0).
• locale - idioma de la interfaz (inglés por defecto). Acepta valores de conformidad con la norma ISO 639-1.

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

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

Configurar webhooks

La solución Subscriptions admite webhooks para los siguientes eventos:

• Pago de una suscripción:
  • Validación del usuario
  • Pago
  • Suscripción creada

• Renovar una suscripción:
  • Validación del usuario
  • Pago
  • Suscripción actualizada
• Cancelar una suscripción: Suscripción cancelada (la suscripción se canceló en la Cuenta del editor o se cancelaron todos los pagos de todos los períodos válidos).

• Reembolso:
  • Reembolso (el pago se canceló en la Cuenta del editor)
  • Suscripción actualizada (el pago se canceló, pero la suscripción sigue activa. Esto puede pasar si el usuario pagó accidentalmente la suscripción dos veces y solo canceló el último pago)
  • Suscripción cancelada (el pago se canceló en la Cuenta del editor o se cancelaron todos los pagos para todos los períodos válidos)

Para activar la recepción de webhooks:

1. En el proyecto en Cuenta del editor, vaya a Project settings > Webhooks.
2. En el campo Webhook server, indique la URL de su servidor en la que quiere recibir los webhooks con el formato https://example.com. También puede especificar la URL que encuentre en una herramienta para probar webhooks.

3. Genere una clave secreta:

1. En la sección Secret keys, haga clic en Add key.
2. En la ventana modal que se abre, introduzca el nombre de la clave que le permitirá identificarla en la lista general.
3. Haga clic en Create key.
4. Haga clic en Copy secret y guarde la clave creada en un lugar seguro.
5. Haga clic en Done.
6. Confirme que ha guardado la clave y haga clic en Ok, close.

4. Haga clic en Enable webhooks.

Rotación de clave secreta

Puede crear hasta 5 claves secretas en su proyecto para habilitar su rotación.

Solo puede haber una clave secreta activa por proyecto. Si quiere cambiarla, haga clic en Set as active en la fila de otra clave y confirme la acción. Cuando haya completado correctamente la migración a una nueva clave, le recomendamos eliminar las claves desactivadas.

5. Pruebe los webhooks en Cuenta de editor.
6. Pruebe la compra de suscripción.
7. Pruebe la renovación de suscripción.
8. Pruebe la cancelación de suscripción.

Probar los webhooks en Cuenta del editor

En la pestaña Subscriptions, puede probar los siguientes webhooks:

• Validación del usuario (user_validation)
• Pago (payment)

Para probar los webhooks:

1. En la sección de pruebas, vaya a la pestaña Subscriptions.
2. Rellene los campos necesarios:
   • User ID: al realizar pruebas, puede utilizar cualquier combinación de letras y números.
   • Xsolla invoice ID: ID de la transacción en Xsolla. Al hacer pruebas, puede usar cualquier valor numérico.
   • Public user ID: ID conocido por el usuario, por ejemplo, una dirección de correo electrónico o un apodo. Este campo se muestra si ha marcado la casilla Use public user ID en su proyecto en Project settings > Integration settings.
   • Amount: importe del pago. Al hacer pruebas, puede utilizar cualquier valor numérico.
   • Currency: seleccione una moneda de la lista desplegable.
   • Plan ID: un plan de suscripción. Elija un plan de la lista desplegable.
   • Subscription product: seleccione un producto de la lista desplegable (opcional). La lista se muestra si hay productos configurados en su proyecto.
   • Invoice ID: ID de transacción en el juego. Al hacer pruebas, puede usar cualquier combinación de letras y números. No es un parámetro obligatorio para que el pago se realice correctamente, pero puede indicarlo para vincular el ID de transacción de su sistema con el de Xsolla.
   • Trial period. Para probar la compra de una suscripción sin periodo de prueba o para probar la renovación de una suscripción, indique el valor 0.
3. Haga clic en Test.

En la URL indicada, recibirá webhooks con los datos rellenados. Los resultados de las pruebas de cada webhook, tanto en el caso de que se haya realizado correctamente como en el de que se haya producido un error, se muestran debajo del botón Test.

Hacer prueba de compra de suscripción

Cuando se pruebe un pago, los webhooks Validación del usuario, Pago y Suscripción creada se enviarán a la URL que especificó en el paso Establecer webhooks. Para probar el proceso de pago, puede:

• Utilizar el modo sandbox (para suscripciones con un período de prueba de 0 días)
• Realizar un pago real y, luego, iniciar un reembolso a través de Cuenta del editor (para suscripciones con un periodo de prueba de más de 0 días)

Modo de aislador de proceso (sandbox)

1. Obtenga un token para el modo sandbox. Transmita el valor 0 al parámetro Trial period (trial_days).
2. Elija el grupo de métodos de pago Credit/debit cards.
3. Introduzca los datos de la tarjeta bancaria de prueba. Introduzca cualquier valor en los campos restantes. También puede especificar datos incorrectos (número de tarjeta, fecha de caducidad o clave CVV) para generar un error.

4. Reciba los webhooks para Validación del usuario, Pago y Suscripción actualizada en la URL que especificó en el paso Establecer webhooks.

Pago real

1. Lleve a cabo una Prueba de webhooks en Cuenta del editor.
2. Firme el Acuerdo de licencia.

3. Obtener un token para pagos reales.

4. Abra la interfaz de pago con el siguiente enlace: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, en el cual ACCESS_TOKEN es el token obtenido en el paso anterior.
5. Elija el grupo de métodos de pago Credit/debit cards.
6. Introduzca los datos de una tarjeta bancaria válida.

7. Reciba los webhooks Validación del usuario, Pago y Suscripción actualizada en la URL de webhook que proporcionó en el paso para establecer webhooks.
8. Reembolse su pago. Para ello, vaya a Cuenta del editor > Player support > Transaction search.
9. Elija la transacción de prueba y haga clic en el botón del menú More (•••). Haga clic en Refund en el menú emergente (la transacción debe tener el estado Complete). Esto enviará los webhooks Suscripción cancelada y Reembolso.

Hacer prueba de renovación de suscripción

1. Obtenga un token para el modo sandbox. Transmita el valor 0 al parámetro Trial period (trial_days).
2. Pague su suscripción usando cualquier método de pago.
3. Vuelva a abrir la interfaz de pago en modo sandbox.
4. Vuelva a pagar para renovar su suscripción usando cualquier método de pago.
5. Obtenga los webhooks Validación del usuario, Pago y Suscripción actualizada en la URL del webhook que especificó en el paso Establecer webhooks.

Hacer prueba de cancelación de suscripción

Para probar la cancelación de suscripciones, utilice:

• Búsqueda por suscripción
• Búsqueda por transacciones recientes
• Utilizar llamadas API

Búsqueda por suscripción

1. Abra su Cuenta del editor y vaya a Player support > Subscribers.
2. Busque la suscripción que quiere cancelar.
3. Abra el menú de estado de la suscripción y seleccione:
   1. Cancel and refund para recibir los webhooks Suscripción cancelada y Reembolso.
   2. Cancel without refund para recibir el webhook Suscripción cancelada.

Búsqueda por transacciones recientes

1. Abra su Cuenta del editor y vaya a Player support > Transaction search.
2. Busque las últimas transacciones que se hayan cancelado.
3. Haga clic en el icono More (•••). Haga clic en Refund en el menú emergente para recibir los webhooks Suscripción cancelada y Reembolso.

Utilizar llamadas API

Abrir la interfaz de pago en modo Aislador de proceso (Sandbox)

Para abrir la interfaz de pago en modo sandbox, obtenga un token con el modo sandbox activo. A continuación se indican las formas de obtener un enlace con el token necesario:

• Utilice Cuenta del editor
• Utilizar llamada API

Mediante Cuenta del editor

1. Pruebe los webhooks en Cuenta del editor. Especifique el valor 0 en el campo Trial period para probar una suscripción que no tenga un período de prueba. Cuando reciba un mensaje de confirmación relativo a que la prueba se ha realizado correctamente, aparecerá un enlace con el token necesario bajo el encabezado Sandbox URL.

2. Pulse en el enlace Sandbox URL.

Mediante llamada API

1. Transmita los parámetros "settings":{"mode":"sandbox"} al método Crear token. Transmita los parámetros "purchase": {"subscription":{"trial_days": 0}} para probar una suscripción que no tenga periodo de prueba.
2. Utilice el siguiente enlace: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, en el cual ACCESS_TOKEN es el token obtenido en el paso anterior.