Inicio rápido

Flujo de integración

Para integrar la solución Payments:

Cree un proyecto en Cuenta del editor. A cada juego le corresponde un proyecto. Si tiene varios juegos, agregue un proyecto para cada juego.
Añada los artículos que desea vender a un catálogo en el lado de Xsolla.
Pruebe a crear un pedido que abonará un usuario.
Pruebe a hacer una compra de prueba y establezca las notificaciones.
Firme el acuerdo de licencia con Xsolla en Cuenta del editor para empezar a procesar pagos reales.

Puede firmar el acuerdo de licencia en cualquier paso de la integración, pero tenga en cuenta que el proceso de revisión puede tardar hasta 3 días laborables.

Crear catálogo

Los artículos virtuales son contenidos internos del juego que un usuario puede comprar por moneda real y virtual. La creación de un catálogo de artículos virtuales en el lado de Xsolla le permitirá personalizar los precios y las restricciones regionales, así como usar el sistema de promociones de Xsolla y otras funciones que se añaden y actualizan periódicamente.

Crear artículos virtuales

Obtener lista de artículos

Para obtener la lista de artículos, haga una llamada al método API Obtener lista de artículos virtuales:

En el encabezado de la solicitud, transmita el JWT de Xsolla Login (token de portador) utilizado para la autorización por defecto. Para hacer una llamada de prueba a este método API, puede usar el siguiente token de prueba: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI.
En el parámetro de ruta project_id, transmita el ID del proyecto que puede encontrar en la Cuenta del editor:

En la respuesta, recibirá información detallada sobre los artículos virtuales creados en su proyecto. Para la posterior creación del pedido, necesita el SKU del artículo que se transmite en el parámetro items.sku.

Crear pedido

Un pedido se compone de artículos que un usuario quiere comprar en la tienda. Una vez pagado el pedido, el usuario recibe los artículos. Para realizar un pago, el usuario debe estar autorizado en el juego.

Seleccione un método de integración que se adapte a su juego para ver las instrucciones de configuración.

Características	Lado del servidor	Lado del cliente
Tener un servidor	Necesita tener su propio servidor para obtener tókenes y controlar la carga del servidor.	No necesita su propio servidor.
Determinar el país del usuario	Debe transmitir el país o la dirección IP en el token de pago. Esto determina la disponibilidad de los métodos de pago.	Xsolla determina el país del usuario por su dirección IP.
Determinar la moneda de pago	Si no transmite la moneda en el token, esta se determinará en función del país. Si transmite la moneda en el token, el usuario pagará en esta moneda.	La moneda viene determinada por el país.

Llame al método API Crear token de pago para compras e introduzca información sobre un usuario y los artículos en este método. Con esta llamada API, puede vender tanto un artículo como varios.

Para utilizar el modo Aislador de proceso (Sandbox), transmita el parámetro “sandbox”: true en el cuerpo de la solicitud para obtener un token.

El valor del parámetro user_id:

cuando haga pruebas, puede transmitir cualquier símbolo en este parámetro.
Para aceptar pagos reales, transmita el ID de usuario procedente de su sistema en este parámetro. Este ID se transmite en el webhook Validación del usuario.

Ejemplo de solicitud:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Integrar Xsolla Login:

Utilizando el método de Login de sesión configurado, cree y guarde el token de autenticación para recibir un token de pago. El token de pago se usa para abrir la interfaz de pago y realizar el pago.

Para probar el flujo de pagos, cree un pedido utilizando la llamada API Create order with specified item:

Si desea realizar una prueba en el sitio web de documentación de la API, haga clic en Try it para abrir la interfaz y crear una solicitud.
En el bloque Security, en el campo Bearer Token, introduzca el token obtenido al transmitir el procedimiento de autenticación.
En el bloque Body, transita los detalles del pedido, p. ej., cantidad de artículos. Para acceder al modo sandbox, introduzca "sandbox": true.
En el bloque Parameters, introduzca:
- project_id - ID de proyecto que puede encontrar en Cuenta del editor.
- item_sku - SKU del artículo.

En la respuesta, recibirá los datos que necesita para seguir trabajando:

token - token de pago

Ejemplo de solicitud:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Para llamar a la API de Xsolla, puede utilizar los métodos del SDK prediseñados para motores y plataformas de juegos:

Realizar compra de prueba

Las pruebas no requieren retirar dinero de cuentas bancarias reales: puede emplear una de nuestras tarjetas de prueba.

Antes de firmar un contrato con Xsolla, probar el proceso de pago solo está disponible en modo sandbox.

Abrir la interfaz de pago en modo sandbox

Para abrir la interfaz de pago en una nueva ventana, use la siguiente URL: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, en la cual TOKEN es el token obtenido al crear un pedido.

Para abrir la interfaz de pago usando otros métodos, consulte la documentacion.

Realizar pago de prueba

Abra la interfaz de pago en modo Aislador de proceso (Sandbox).
Elija el método de pago Tarjeta bancaria.
Introduzca los datos de la tarjeta bancaria. En otros campos (p. ej., nombre o dirección), puede introducir cualquier dato. También puede especificar detalles incorrectos (número de tarjeta o fecha de expiración) para comprobar si se genera un error.
Haga clic en Pagar.

Lista de tarjetas de prueba

Consulte la lista de tarjetas bancarias de pruebas.

Información sobre los códigos postales

Además de los datos de la tarjeta, debe especificar el código postal si se cumple al menos una de las siguientes condiciones:

El país del usuario es EE. UU. o Canadá.
El número de identificación bancaria (BIN) indica que la tarjeta se emitió en EE. UU.

Puede especificar cualquier código postal válido (p. ej., 12345). Esto determina el tipo impositivo sobre las ventas y no afecta al proceso del pago de prueba.
Los pagos con tarjeta bancaria sandbox (aislador de proceso) pueden realizarse en las siguientes divisas: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND y ZAR.

En el modo sandbox, puede probar un pago único y el pago con los métodos de pago guardados utilizando tarjetas bancarias y PayPal.

Configurar webhooks

Si establece la integración en el lado del servidor, deberá validar los pedidos creados mediante el envío del código correspondiente en respuesta a los webhooks. Si establece la integración en el lado del cliente, los webhooks le permitirán recibir notificaciones sobre eventos configurados (p. ej., cambio del estado del pago).

Para habilitar la recepción de webhooks:

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

SDK PHP

Emplee clases listas para procesar webhooks.

Para probar los webhooks, también puede seleccionar cualquier sitio web específico, como webhook.site, o una plataforma, como ngrok.

Para recibir notificaciones sobre la validación del usuario y los pagos aceptados, configure los siguientes webhooks:

Validación del usuario — para notificaciones que confirmen que el usuario está registrado en el juego.
Pago — para notificaciones que confirmen que se realizó el pago.

Consulte la documentación para obtener información detallada sobre cómo establecer y probar webhooks.

Configurar el agente de escucha de webhooks

El agente de escucha de webhooks es un código de programa que permite recibir webhooks entrantes en una dirección URL especificada, generar una firma, y enviar una respuesta al servidor de webhooks de Xsolla.

Información sobre la generación de la firma y el envío de respuestas al webhook

Generación de firma

Cuando reciba un webhook, se debe garantizar la seguridad de la transmisión de datos. Para conseguirlo, se debe generar una firma a partir de los datos del webhook y verificar que coincide con la firma enviada en el encabezado de la solicitud HTTP. Para generar una firma:

Concatene el JSON del cuerpo de la solicitud y la clave secreta del proyecto.
Aplique la función hash criptográfica SHA-1 a la cadena obtenida en el primer paso.

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. Si no se recibió una respuesta para los webhooks Successful payment of the order y Order cancellation o si se ha recibido una respuesta con un código 5xx, los webhooks se reenvían con arreglo al siguiente esquema temporal:

2 intentos con un intervalo de 5 minutos
7 intentos con un intervalo de 15 minutos
10 intentos con un intervalo de 60 minutos

Se realizan un máximo de 20 intentos de envío de webhooks en un plazo de 12 horas desde el primer intento. Si para el webhook Pago no se recibió una respuesta o si se recibió una respuesta con un código 5xx, los webhooks también se reenvían con un intervalo mayor. Se realiza un máximo de 12 intentos en 12 horas. Si no se recibió una respuesta para el webhook Validación del usuario o si se recibió una respuesta con un código 400 o 5xx, el webhook Validación del usuario no se reenvía. En este caso, se muestra un error al usuario y no se envían los webhooks Pago y Successful payment of the order.

Lanzamiento

Antes de firmar el contrato de licencia, sólo puede abrir la interfaz de pago en modo sandbox.

Firmar el acuerdo de licencia

La firma del acuerdo de licencia le permitirá recibir pagos reales mediante cualquier método de pago admitido por Xsolla. Para firmar el acuerdo de licencia:

Abra su Cuenta del editor.
En el menú lateral, vaya a la sección Agreements and taxes > Agreements.
En la pestaña Licensing Agreement, haga clic en Fill out application form.
Introduzca sus datos en los campos correspondientes.

Su solicitud será revisada en un plazo de 3 días laborables. Si hay alguna duda durante el proceso de verificación, Xsolla se la notificará a la persona de contacto indicada en la solicitud. Una vez terminado el procedimiento de verificación por parte de Xsolla, el estado de tu acuerdo cambiará a Signed.

Сonmutación al entorno de producción

Después de realizar el primer pago real, entra en vigor una estricta política de pagos en modo sandbox. Los pagos realizados en modo sandbox solo están disponibles para los usuarios especificados en Cuenta del editor en la sección Company settings > Users.

Después de realizar los pasos anteriores, puede empezar a recibir pagos reales:

Asegúrese de haber firmado el acuerdo de licencia con Xsolla.
Elimine el parámetro “sandbox”: true del cuerpo de la solicitud al obtener un token.
Abre la interfaz de usuario de pago utilizando el siguiente enlace: https://secure.xsolla.com/paystation4/?token=TOKEN.

Esta guía describe los ajustes mínimos necesarios para iniciar rápidamente la integración. Si tiene alguna pregunta, contacte con nosotros a través de Xsolla Chat en la esquina inferior derecha de la página o envíe un correo electrónico a un gestor del éxito del cliente a csm@xsolla.com.

¡Gracias por tu mensaje!

Nos ayudará a mejorar tu experiencia.

Valore esta página

Prefiero no responder

¡Gracias por tu mensaje!

Última actualización: 18 de Marzo de 2024

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

Your browser is not supported. Please try a different browser

Payments

Inicio rápido

Flujo de integración

Crear catálogo

Crear artículos virtuales

Obtener lista de artículos

Crear pedido

Realizar compra de prueba

Abrir la interfaz de pago en modo sandbox

Realizar pago de prueba

Configurar webhooks

Configurar el agente de escucha de webhooks

Generación de firma

Enviar respuestas al webhook

Lanzamiento

Firmar el acuerdo de licencia

Сonmutación al entorno de producción

¿Te ha resultado útil este artículo?

Valore esta página

¡Gracias por tu mensaje!