Documentación de Steamworks
Guía de implementación de microtransacciones

Descripción general

El objetivo del sistema de pagos de Steam dentro del juego es ofrecer a los desarrolladores un modo sencillo de vender artículos arbitrarios a los usuarios, sin que estos tengan que abandonar en ningún momento la experiencia del juego. Los productos a la venta dependen por completo de cada vendedor. Pueden ser objetos del juego, como armas y munición, moneda del juego (como monedas u oro), o incluso atuendos para los personajes. Dentro del juego, se pueden vender tantos o tan pocos objetos como se desee, ya sean sueltos o en paquetes. Steam no restringe lo que se puede vender ni la manera de hacerlo, ni tampoco limita en modo alguno el uso de los mecanismos que puede tener tu juego para vender artículos. Su objetivo es dotar a tu juego de una experiencia de pago con la que los usuarios ya están acostumbrados, gracias a nuestra plataforma, para que nada les impida invertir en tus productos el contenido de su Cartera de Steam. Con una integración así, tu juego tendrá acceso inmediato a los nuevos usuarios y métodos de pago de Steam en cuanto estén disponibles.

En este sistema, las compras están completamente bajo tu control. Una respuesta positiva a una solicitud de compra se convertirá de forma fiable en un cobro al usuario y en una notificación inmediata para ti. Una vez aprobada la compra, la entrega y gestión de los artículos es responsabilidad tuya. Si, por ejemplo, un artículo solo está disponible por tiempo limitado, tu sistema es el que dicta el plazo de disponibilidad.

Además de las compras integradas dentro de los juegos, el sistema ofrece funciones adicionales que tus sistemas de contabilidad y asistencia pueden usar, por ejemplo:
  1. Permite recibir notificaciones si los clientes no pagan.
  2. Permite emitir reembolsos y consultar el estado de las transacciones a través de un servicio web.
  3. Otorga acceso a los informes detallados de nuestro sitio de estadísticas para asociados de Steam, mostrando las ventas de artículos y juegos en tiempo real.

Prácticas recomendadas sobre compras dentro de los juegos

Si se quiere traer a Steam un juego con compras integradas, tenemos algunas sugerencias, procedimientos recomendados y recursos que pueden ser de ayuda. Tanto si se trata de juegos gratis o Free to Play como si se compraron por anticipado, todos los títulos que ofrecen compras integradas comparten algunos elementos que conviene considerar a la hora de preparar su lanzamiento en Steam.

Por favor, consulta la Microtransacciones (compras integradas) documentación para ver sugerencias sobre la economía dentro de los juegos y prácticas recomendadas.

Funcionamiento del sistema de pago

El sistema de pago es una combinación de los procesos de compra integrados en tus juegos, el servicio de facturación web de Steam y un procedimiento de aprobación de los usuarios.

El proceso de compra sigue esta secuencia: Tu usuario siempre inicia y completa su pedido dentro de tu juego.
  1. Cuando el usuario desea comprar algo en el juego, este envía una solicitud de compra a tu servidor de compras. El servidor de compras puede ser cualquier entidad de servicio habilitada por los sistemas de tu juego para ocuparse de este tipo de solicitudes. Puede ser tanto un servidor web como tu sistema de autenticación. Dicho servidor debe comunicarse por HTTP con los servidores de facturación de Steam. Además, el servidor de compras puede solicitar a los servidores de facturación de Steam el país, el idioma y la divisa del usuario. Estos datos te servirán para realizar ajustes de precio según sea necesario.
  2. A continuación, el servidor de compras inicia una transacción de pago al servicio web de Steam en nombre del cliente. Se trata de una solicitud POST HTTP segura. La solicitud incluye tanto los metadatos del usuario como la descripción y precio de cada artículo que desea comprar.
  3. Al recibirla, Steam activará automáticamente la interfaz de Steam y le mostrará al usuario un cuadro de diálogo con una lista de todos los artículos, su costo y un botón para confirmar o autorizar la transacción. Si el usuario no tiene fondos suficientes en su cuenta de Steam, la interfaz lo guiará en el proceso de recarga de fondos. La interfaz de Steam se encarga de obtener todos los datos de facturación del usuario. Una vez completado este proceso, se le notifica al usuario si la compra se ha autorizado o denegado. Tu juego debe estar registrado para recibir una función callback para esta notificación y remitir el resultado a tu servidor de compras.
  4. Tu servidor de compras recibe la notificación y envía la llamada FinalizeTransaction a Steam para completar la operación. Si esta llamada se completa correctamente, se efectúa el cargo en la cuenta del cliente, momento en el que podrás otorgarle el artículo.

Como alternativa para juegos que ejecutan las operaciones de compra a través de una página web, o en el caso de que desees ofrecer directamente Steam como método de pago en tu sitio web, puedes optar por realizar una integración basada en navegador. En ese caso, el proceso de compra sigue esta secuencia:
  1. El usuario desea comprar algo dentro del juego o en tu sitio web. En el primer caso, se abriría tu página web en su navegador.
  2. El servidor de compras inicia una transacción web en nombre del usuario, usando un protocolo POST HTTP seguro. Si se completa correctamente, este devuelve una URL de Steam única hacia la que puedes remitir la misma sesión del navegador del usuario, para que autorice la transacción. Al redirigir al navegador del usuario, especificas también una dirección URL a la que volverá una vez completado el proceso de autorización.
  3. Una vez que el usuario vuelve a tu sitio web, tu servidor de compras solicita el estado de la transacción y, si esta ha sido autorizada, puedes recibir los fondos con una última llamada de FinalizeTransaction a Steam.

Establecimiento de la conexión

Requisitos previos

Primero creas una clave WebAPI de editor. Las instrucciones se pueden encontrar en la Autenticación mediante claves de Web de API página de documentación. Esta clave, que se pasa con todas las solicitudes al servidor web, se usa para autenticar las solicitudes al servidor. Esto tiene que enviarse con las solicitudes como un parámetro key=<your key here>.

Guardar el pedido

Guarda los pedidos en tu sistema por si los necesitas como referencia más adelante. Usa un id. de pedido de 64 bits único para identificar las transacciones en Steam.

Envío de solicitudes

Todas las solicitudes deben enviarse mediante GET o POST HTTP 1.1 utilizando una conexión segura TLS. El tipo de contenido debe ser "application/x-www-form-urlencoded" y los parámetros de POST tienen que estar en el cuerpo de la solicitud en el formato estándar de codificación de URL. El texto se debe transmitir como UTF-8.

Las solicitudes pasarán por el URI básico:
https://partner.steam-api.com/ISteamMicroTxn/*

Algunos comandos devuelven un resultado de completado o de error. Para los casos donde se devuelve el resultado de error, se agrega un código de error adicional y su descripción. Estas claves no estarán presentes en caso de que se complete la acción.

De forma predeterminada, las respuestas se entregan en formato JSON. Opcionalmente puedes especificar un formato XML. añadiendo el parámetro "format=xml" a la solicitud.
Nota: debes implementar una solución flexible de JSON o de XML que permita claves de parámetros que se publiquen y se devuelvan en un orden arbitrario.

Pruebas

Steam ofrece a los desarrolladores un entorno de pruebas para poner a prueba la integración. El entorno de pruebas es compatible con todas las solicitudes disponibles a través de la API normal, solo que no se retiran fondos de la Cartera de Steam del usuario.

Se puede acceder al entorno de pruebas a través de un URI base diferente:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Pasos de la integración

Compras dentro del juego


Esto es para juegos que cuentan con una tienda integrada, en los que la experiencia del usuario permanece dentro del título.
  • Paso 1
    Tu juego tiene que lanzarse con la API de Steamworks. Esto significa: incluir un archivo de encabezado, vincular un archivo .lib y enviar una DLL con el producto. Consulta Steamworks API Overview para ver más detalles. ¡Hay que iniciar correctamente la API de Steamworks antes de continuar!
  • Paso 2
    El usuario decide comprar uno o más artículos dentro del juego. Una vez identificado un artículo (o más de uno), el juego debe recopilar algunos metadatos sobre el usuario:
    • Id. de Steam: Este número de 64 bits identifica al usuario de manera inequívoca dentro del sistema de Steam.
    • Código de país: El código ISO 3166 del usuario indica desde dónde lo compra. Se usa para determinar el precio que se debe aplicar a la compra.
    • Código de divisa: Código ISO 4217 de la moneda en la que se le pasará el cargo al usuario.
    • Código de idioma del cliente de juego: Código ISO 639-1 del idioma en el que se está ejecutando el cliente de juego en Steam.

    El id. de Steam y el idioma se pueden obtener mediante llamadas a la API de Steamworks:

    Para obtener el país y la divisa del usuario, se usa una solicitud a la Web de API ISteamMicroTxn/GetUserInfo en la que se pasa el id. de Steam del usuario.

    Estos metadatos, deben agruparse y enviarse al servidor de compras, junto con los datos de compra normales.
  • Paso 3
    Tu servidor de compras envía una solicitud de compra a través del servicio web de Steam en nombre del cliente. Usa la Web de API ISteamMicroTxn/InitTxn descrita más adelante en este documento. Tendrás que enviar los siguientes datos junto con la solicitud:
    • Id. de pedido: un número único de 64 bits que asignas a la compra. Este número es tu clave de la transacción. Se usa para hacer referencia a la transacción dentro del sistema de Steam.
    • Id. de Steam: id. de usuario recibido del cliente de Steam en el paso 3.
    • Id. de aplicación: identificador único de tu juego en Steam.
    • Idioma: código ISO 639-1 de idioma en el que se lista tu artículo (o artículos).
    • Divisa: Código ISO 4217 de divisa del artículo (o artículos) listado. Si esto no coincide con el código de divisa que el usuario proporcionó en el paso 2, entonces se aplicará una conversión automática al tipo de mercado actual. Steam presentará el precio convertido al usuario, en su divisa local, para que dé su aprobación. Para una mejor experiencia del cliente, se recomienda que proporciones precios específicos para cada moneda que creas que tus clientes vayan a usar.
    • Una lista con uno o más artículos que desea comprar el usuario. Para cada artículo, se especifican los siguientes datos:
      • Id. de artículo: identificador de 32 bits que le has asignado al artículo.
      • Cantidad: número de artículos de este tipo que incluye la transacción.
      • Importe: importe que quieres cobrar al usuario por el artículo (o artículos), expresado en centésimas de una moneda (centavos, centavos, etc.). Algunas monedas tienen que mostrar el precio con su valor completo, véase Divisas admitidas para obtener más información. Si el valor de cantidad del artículo es superior a 1, este será el total que se cobre (importe = cantidad x costo_del_artículo).
      • Descripción del artículo: un texto que describe el artículo. Se le mostrará al usuario cuando se le pida que autorice la transacción. Se puede optar por traducir la descripción en función del código de idioma indicado por el cliente en Steam.
      • Categoría de artículo: un texto opcional en el que se describe la categoría a la que pertenece el artículo. Este valor, que se usa para agrupar los datos sobre ventas en los informes de Steam en el backend, nunca se muestra al usuario.

    Si Steam acepta la transacción, se enviará automáticamente una notificación al cliente en Steam para pedirle que autorice la compra. En caso de que se produzca un error, habrá que corregir el problema y enviar una nueva transacción de compra.
  • Paso 4
    Si se completa correctamente un intento de ISteamMicroTxn/InitTxn, el usuario recibirá una notificación de la interfaz en la partida de Steam donde se le indicará que debe autorizar la transacción. Los detalles de esta transacción se mostrarán usando las descripciones del artículo incluidas en tu solicitud de compra. A continuación, el usuario podrá autorizar la transacción. Si el usuario no cuenta con fondos suficientes en su cuenta, Steam lo guiará por un proceso de recarga de fondos. Al final del proceso, se notificará al juego si la transacción ha sido autorizada o rechazada.

    El juego tendrá que registrar un controlador de función callback ISteamUser::MicroTxnAuthorizationResponse_t para recibir la notificación con la aprobación o rechazo de la operación. El resultado de esta función callback contiene el id. de aplicación, el id. de pedido y el estado de autorización de la transacción. A continuación, el juego puede enviar este resultado al servidor de compras para que este complete la transacción. Consulta la documentación Callbacks para obtener más detalles.
  • Paso 5
    El servidor de compras usa el comando de la API ISteamMicroTxn/FinalizeTxn para completar la transacción con los siguientes parámetros:
    • Id. de pedido: id. de pedido creado por ti para iniciar la transacción.
    • Id. de aplicación: identificador único de tu juego en Steam.

    Una respuesta positiva significa que se ha aceptado la compra y han de otorgarse los artículos. Una respuesta de error indica que no se ha completado correctamente la compra. Va acompañada por el correspondiente mensaje de error.
  • Paso 6
    Tu servidor de compras necesita llamar con regularidad a la API ISteamMicroTxn/GetReport para recibir notificaciones sobre los cambios en el estado de liquidación de las transacciones. Deberías llamar a esta API por lo menos una vez al día para conciliar las actualizaciones de liquidación, pero no es poco razonable llamar a esta API cada minuto para asegurarte de que tus servidores estén al día con la actualización de transacciones.

    A tu discreción, puedes reembolsar transacciones de clientes utilizando la API ISteamMicroTxn/RefundTxn. Sin embargo, existen otras maneras de revertir las transacciones que probablemente requieran tu atención. Cuando una transacción entra en un estado revertido, por ejemplo, "Refunded" (reembolsada), "PartialRefund"(reembolso parcial), "Chargedback" (contracargo), "RefundedSuspectedFraud" (reembolso presuntamente fraudulento) o "RefundedFriendlyFraud" (contracargo fraudulento reembolsado) (consulta Apéndice A: Valores de estado), luego tu backend intentará recuperar los artículos vinculados a la transacción revertida de ser posible. Revisa nuestra documentación en Prevención de fraudes y asegúrate de que tomaste pasos para impedir los tipos más comunes de fraude.

Compras en la web

Si la tienda de tu juego es una página web o, simplemente, quieres agregar Steam como método de pago, puedes usar los siguientes pasos en el proceso de integración:
  • Paso 1
    Obtener el id. de Steam del usuario.
    • Si el usuario está jugando en ese momento, se usa la API de Steamworks para que devuelva el id. de Steam: ISteamUser::GetSteamID.
    • Si el usuario está en el sitio web, se puede usar la API OpenID de Steamworks para obtener su id. de Steam de manera segura. Puedes encontrar más información sobre OpenID en la página de documentación de Steamworks Autenticación basada en navegador con OpenID.

    Nota: Es recomendable vincular la cuenta de juego del usuario con su id. de Steam para que solo tenga que llevar a cabo este proceso de inicio de sesión secundario una sola vez.
  • Paso 2
    Obtén el país y la divisa del usuario con la solicitud vía web de la API ISteamMicroTxn/GetUserInfo en la que se pasa el id. de Steam del usuario. Estos datos se pueden usar para que tu tienda muestre los valores correctos de precios y de divisa.

    Nota: GetUserInfo cuenta con un parámetro opcional de dirección IP que puedes usar para indicarle a Steam el origen del usuario. Envía la dirección IP del usuario para todas sus compras en web o siempre que no haya iniciado sesión de manera activa en el cliente de Steam y esté jugando a tu juego.
  • Paso 3
    El servidor de compras envía al servicio web de Steam una solicitud de compra utilizando la Web de API ISteamMicroTxn/InitTxn. Aparte de lo que es habitual para las compras en el juego normales hay que facilitar dos datos más:
    • usersession: con el valor "web", para indicar que el usuario autentificará la transacción a través de un navegador.
    • ipaddress: dirección IP pública del usuario.

    Cuando el valor de usersession es web, la solicitud InitTxn devuelve un parámetro steamurl adicional. Esta es una dirección única a la que puedes redirigir la sesión web del usuario, que identifica la transacción creada mediante la llamada a esta API.

  • Paso 4
    El servidor de compras redirige la sesión web del usuario a la URL de Steam devuelta por la llamada a la API InitTxn. Aparte de la redirección, incluye tu propia dirección URL, a la que volverá el usuario una vez autorizada (o rechazada) la transacción. Utiliza un URL completo (p. ej., http://www.steamgames.com) con el formato
    returnurl=pon_tu_URL_aquí
    Cuando un usuario sea redirigido al URL de Steam, tendrá que iniciar sesión en Steam antes de autenticarse. Si el usuario selecciona Steam como método de pago desde tu web, esto le parecerá normal. Sin embargo, si ya había iniciado sesión en Steam y estaba jugando, sería preferible saltarse el requisito de este segundo inicio de sesión. Esto se puede solucionar utilizando la funcionalidad de la interfaz de juego dentro del navegador. Si se usa el navegador de la interfaz del juego para la autorización, el usuario iniciará sesión automáticamente. Para abrir el navegador, usa una llamada a la API de Steamworks
    ISteamFriends::ActivateGameOverlayToWebPage

    Puedes encontrar más detalles sobre el uso de la interfaz del juego aquí.
  • Paso 5
    Cuando el usuario vuelve a tu sitio, emite una llamada a la API ISteamMicroTxn/QueryTxn para obtener los resultados. Si el estado del pedido es "Aprobado" captura los fondos con la llamada a la API ISteamMicroTxn/FinalizeTxn. Abandona la transacción si se devuelve cualquier otro estado.

    Nota: si el usuario cierra el navegador o cualquier imprevisto le impide volver a tu sitio, abandona la transacción y no emitas una llamada FinalizeTxn. Aunque el usuario haya aprobado la transacción y, por lo que sea, no ha sido redireccionado, abandónala y comienza de nuevo.
  • Paso 6
    Tu servidor de compras necesitará llamar con regularidad a la API ISteamMicroTxn/GetReport para recibir notificaciones sobre cambios en el estado de liquidación de las transacciones. Deberías llamar a esta API por lo menos una vez al día para conciliar las actualizaciones de liquidación, pero no es poco razonable llamar a esta API cada minuto para asegurarte de que tus servidores estén al día con la actualización de transacciones.

    A tu discreción, puedes reembolsar transacciones de clientes utilizando la API ISteamMicroTxn/RefundTxn. Sin embargo, hay otras maneras de revertir las transacciones que probablemente requieran tu atención. Cuando una transacción pasa a un estado revertido, (p. ej., "Refunded" (reembolsada), "PartialRefund"(reembolso parcial), "Chargedback" (contracargo), "RefundedSuspectedFraud" (reembolso presuntamente fraudulento) o "RefundedFriendlyFraud" (contracargo fraudulento reembolsado), consulta Apéndice A: Valores de estado), posteriormente, tu backend debe intentar recuperar los elementos asociados a la transacción revertida de ser posible. Revisa nuestra documentación en Prevención de fraudes y asegúrate de que tomaste pasos para impedir los tipos más comunes de fraude.

Apéndice A: Valores de estado

Estos son los valores de estado posibles que devuelve la Web de API ISteamMicroTxn. La clave de respuesta que llevan estos valores suele llamarse status o estado.
  • Init - El pedido se ha creado pero el usuario no lo ha autorizado.
  • Approved - El pedido ha sido autorizado por el usuario.
  • Succeeded - El pedido se ha procesado correctamente.
  • Failed - El pedido ha fallado o se ha denegado.
  • Refunded - El pedido se ha reembolsado y el juego debe revocar el producto. El cliente puede iniciar un reembolso.
  • PartialRefund - Se han reembolsado uno o varios artículos del carro. Los detalles pueden verse en el campo itemstatus de cada artículo.
  • Chargedback - El pedido es fraudulento o está en disputa y el juego debe revocar el producto.
  • RefundedSuspectedFraud - Valve ha reembolsado el pedido porque se sospechaba que era un fraude. El producto debe ser revocado por el juego.
  • RefundedFriendlyFraud - Valve ha reembolsado el pedido porque se determinó que era un fraude amistoso. El juego debe revocar el producto.

Apéndice B: Códigos de error

Estos son los códigos de error posibles que devuelve la Web de API ISteamMicroTxn. La clave de respuesta que lleva estos valores suele ser errorcode.
  • 1 - Éxito
  • 2 - La operación ha fallado
  • 3 - Parámetro no válido
  • 4 - Error interno
  • 5 - El usuario no ha aprobado la transacción
  • 6 - La transacción ya se ha enviado
  • 7 - El usuario no ha iniciado sesión
  • 8 - La divisa no coincide con la de la cuenta de Steam del usuario
  • 9 - La cuenta no existe o está temporalmente inaccesible
  • 10 - El usuario rechazó la transacción
  • 11 - La transacción se rechazó porque el usuario está en un país restringido
  • 12 - La transacción se rechazó porque el acuerdo de facturación no está activo
  • 13 - No se puede procesar el acuerdo de facturación porque no es del tipo GAME
  • 14 - El acuerdo de facturación está en suspenso porque hay una disputa o un reembolso
  • 15 - No se puede procesar el acuerdo de facturación porque no es del tipo STEAM
  • 16 - El usuario ya tiene un acuerdo de facturación para este juego
  • 100 - Sin fondos suficientes
  • 101 - Se superó el límite de tiempo para la finalización
  • 102 - La cuenta está desactivada
  • 103 - La cuenta no tiene autorización para comprar
  • 104 - La transacción se denegó porque se detectó un fraude
  • 105 - No hay ningún método de pago en caché
  • 106 - La transacción superaría el límite de gasto del acuerdo de facturación
  • 107 - El usuario tiene una transacción pendiente que debe completarse antes de comenzar una nueva

¿Tienes más preguntas?

Haz tus preguntas en el panel de discusión sobre la integración de compras dentro del juego.