Transferir compras al usuario

Implemente la concesión de compras al usuario en su aplicación empleando la información recibida en los webhooks de Xsolla sobre los detalles de la transacción y los artículos adquiridos.

Para que la tienda en el juego y el sistema de gestión de pagos funcionen a pleno rendimiento, es necesario implementar el procesamiento de los principales webhooks:

El siguiente esquema muestra el proceso de compra y de devolución de artículos utilizando webhooks combinados.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as Usuario
    participant GameClient as Cliente del juego
    participant Xsolla as Xsolla
    participant GameServer as Servidor del juego
    %% Item Purchase
    rect rgb(243, 243, 241)
        Note over User, GameServer: Compra de artículos
    end
        User ->> GameClient: Inicia sesión
        activate GameClient
        GameClient ->> Xsolla: Envía una solicitud de autenticación de usuario
        activate Xsolla
        Xsolla -->> GameClient: Devuelve un token JWT/OAuth 2.0
        deactivate Xsolla
        GameClient ->> Xsolla: Envía el JWT, el ID del proyecto y los parámetros de paginación
        activate Xsolla
        Xsolla -->> GameClient: Devuelve una matriz de artículos
        deactivate Xsolla
        GameClient -->> User: Muestra el escaparate
        deactivate GameClient
        User ->> GameClient: Selecciona el artículo y pulsa en Comprar
        activate GameClient
        GameClient ->> Xsolla: Crea una solicitud de pedido
        deactivate GameClient
        activate Xsolla
        Xsolla -->> GameClient: Devuelve un token de pago
        deactivate Xsolla
        activate GameClient
        GameClient ->> Xsolla: Abre la URL de la interfaz de pago con el token recibido
        deactivate GameClient
        activate Xsolla
        Xsolla ->> GameServer: Envía el webhook para validación del usuario
        activate GameServer
        GameServer -->> Xsolla: Devuelve el código de estado de operación realizada correctamente
        deactivate GameServer
        Xsolla -->> User: Muestra la interfaz de pago
        deactivate Xsolla
        User ->> Xsolla: Elige el método de pago y pulsa en Pagar
        activate Xsolla
        Xsolla ->> GameServer: Envía el pago realizado correctamente para el webhook del pedido
        activate GameServer
        activate GameServer
        Note right of GameServer: Transfiere las compras al usuario
        deactivate GameServer
        GameServer -->> Xsolla: Devuelve el código de estado de operación realizada correctamente
        deactivate GameServer
        Xsolla -->> User: Muestra la pantalla de compra realizada correctamente
        deactivate Xsolla
    %% Refund / Chargeback
    rect rgb(243, 243, 241)
        Note over User, GameServer: Reembolso/Contracargo
    end
        User ->> Xsolla: Solicita reembolso o contracargo
        activate Xsolla
        Xsolla ->> GameServer: Envía webhook de cancelación del pedido
        activate GameServer
        activate GameServer
        Note right of GameServer: Elimina artículos del inventario del usuario
        deactivate GameServer
        GameServer -->> Xsolla: Devuelve el código de estado de operación realizada correctamente
        deactivate GameServer
        Xsolla -->> User: Reembolsa el pago
        deactivate Xsolla

Si la personalización del catálogo de artículos está implementada en el lado de su aplicación, establezca el procesamiento de Personalización del catálogo en el lado del socio.

Establecer webhooks en Cuenta del editor

1. Abra su proyecto en Cuenta del editor y vaya a Project settings > Webhooks.
2. En el campo Webhook server, especifique la URL de su servidor donde quiere recibir los webhooks en formato https://example.com. También puede especificar la URL que encuentre en una herramienta para probar webhooks.
3. Por defecto, se genera una clave secreta para firmar los webhooks del proyecto. Si quiere generar una nueva clave secreta, haga clic en el icono de actualización.
4. Haga clic en Enable webhooks.

Probar los webhooks en Cuenta del editor

Cuando habilite los webhooks en su proyecto, aparecerá una sección para probarlos en Cuenta del editor, debajo de la configuración avanzada.

Puede probar los siguientes webhooks:

En ausencia de valores reales, puede introducir valores arbitrarios.

También puede probar los webhooks al realizar compras en el modo Aislador de proceso (sandbox) o en el modo real. La prueba de Refund solo está disponible en modo real.

Enviar respuestas al webhook

Para confirmar la recepción del webhook, su servidor debe devolver:

• código HTTP 200, 201 o 204 en el caso de una respuesta correcta.
• Código HTTP 400 con descripción del problema si no se ha encontrado el usuario especificado o se ha transmitido una firma no válida.

Su controlador de webhook también puede devolver un código 5xx en caso de problemas temporales en su servidor.

Próximos pasos

1. Configurar la venta de suscripciones (opcional).
2. Configurar la autenticación de usuarios.

Configurar la información de los artículos en los webhooks

Puede configurar qué datos de los artículos se incluyen en los webhooks Pago del pedido realizado correctamente y Cancelación del pedido a través de la matriz de items.

Activar la inclusión de parámetros adicionales

Active la inclusión de parámetros adicionales que indiquen:

• si el artículo es gratuito (is_free)
• si el artículo es una bonificación (is_bonus)
• si el artículo forma parte de un lote (is_bundle_content)

Para recibir estos parámetros, debe cambiar sus webhooks a la versión 2 mediante la llamada a la API Actualizar la información sobre la configuración de webhooks. En la versión 1 (predeterminada), estos parámetros no están disponibles.

Ejemplo de matriz de artículos con parámetros adicionales:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Desactivar la inclusión del contenido del lote

Por defecto, los webhooks incluyen todos los artículos del lote como una lista de artículos individuales. Puede configurar el webhook para que solo incluya el lote en sí, sin detallar su contenido.

En este caso, los artículos incluidos en el lote no se incluyen en la matriz de items. En la matriz que se muestra arriba, el artículo con el SKU com.xsolla.gold_1, que forma parte del lote, está excluido.

Ejemplo de matriz de artículos cuando el contenido del lote está desactivado:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Para desactivar la inclusión del contenido del lote, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

Enlaces útiles