# Webhooks

# Descripción general {% #overview %}

Los webhooks son notificaciones sobre eventos que se producen en el sistema. 
Cuando ocurre un evento específico, Xsolla envía una solicitud HTTP, en la cual 
se transmiten los datos del evento, a su aplicación. Generalmente, se trata de 
una solicitud POST en formato JSON.

<strong>Ejemplos de eventos:</strong>
- interacción del usuario con un catálogo de artículos
- pago o cancelación de un pedido

Cuando se produce un evento definido, Xsolla lo notifica a su sistema mediante 
un webhook. En consecuencia, puede realizar acciones como:
- reponer el saldo del usuario
- efectuar una devolución de pago
- abonar o cargar nuevos artículos en la cuenta de usuario
- empezar a proveer una suscripción
- bloquear a un usuario si hay una sospecha de fraude

<b>Ejemplo de un flujo de trabajo de webhook de procesamiento de pagos:</b>

![Webhook de procesamiento de 
pagos](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)

<div class="note">
<p><strong>Nota</strong></p><p>Dependiendo de la solución utilizada y del tipo de integración, el conjunto de webhooks y la secuencia de interacciones pueden ser distintos a los del ejemplo proporcionado.</p>
</div>

<b>Videoguía para la integración de webhooks con Xsolla:</b>

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 15px; overflow: hidden;">
  <iframe src="https://player.vimeo.com/video/1034591338" style="position: absolute; top:0; left: 0; width: 100%; height: 100%; border:0; border-radius: 15px;" allowfullscreen></iframe>
</div>


<b>Configuración de Webhooks para trabajar con productos y soluciones de Xsolla:</b>

<table>
<thead>
    <tr>
        <th>Producto/Solución</th>
        <th>Obligatorio/Opcional</th>
        <th>¿Para qué se utilizan los webhooks?</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Payments</td>
        <td>Obligatorio</td>
        <td>
          <ul>
            <li>Validación del usuario.</li>
            <li>Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago.</li>
            <li>Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Store</td>
        <td>Obligatorio</td>
        <td>
          <ul>
            <li>Validación del usuario.</li>
            <li>Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago.</li>
            <li>Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Game Sales</td>
        <td>Opcional</td>
        <td>Para vender claves del juego, la validación del usuario y el abono de los artículos no son necesarios. Puede conectar los webhooks si desea recibir información sobre eventos, como el pago o la cancelación de pedidos.<br />Si conecta webhooks, es esencial procesar todos los <a href="/es/webhooks/overview/#section/List-of-required-webhooks">webhooks requeridos</a> entrantes.
</td>
    </tr>
    <tr>
        <td>Suscripciones</td>
        <td>Opcional</td>
        <td>Recibir información sobre la creación, actualización o cancelación de una suscripción. También puede <a href="/doc/subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_information_set_up_via_api">solicitar información mediante la API</a>.
       </td>
    </tr>
    <tr>
        <td>Web Shop</td>
        <td>Obligatorio</td>
        <td>
          <ul>
            <li>Validación del usuario.</li>
            <li>Recibir información sobre los datos de la transacción en caso de pago aceptado o devolución del pago.</li>
            <li>Abonar a un usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.</li>
            <li>Autenticación de usuario, si usa la autenticación mediante ID de usuario. Como alternativa, puede utilizar <a href="/solutions/web-shop/authentication-and-analytics/set-up-authentication/#web_shop_guide_shop_with_auth_set_up_auth_xsolla_login_how_to_get_it">autenticación de usuario mediante Xsolla Login</a>.</li>
          </ul>
        </td>
    </tr>
    <tr>
        <td>Digital Distribution Hub</td>
        <td>Obligatorio</td>
        <td>
          <ul>
            <li>Validación del usuario.</li>
            <li>Vincular el ID de transacción en el lado de Xsolla con el ID de transacción en su sistema.</li>
            <li>Transferir parámetros de transacción adicionales en el pedido.</li>
            <li>Abonar al usuario los artículos comprados y cargar en su cuenta los artículos si se cancela el pedido.</li>
          </ul>
          <p>Consulte la <a href="/solutions/ddh/#integration_guide_ddh_webhook">documentación</a> para obtener información detallada sobre cómo establecer webhooks para el Digital Distribution Hub.</p>
        </td>
    </tr>
    <tr>
        <td>Login</td>
        <td>Opcional</td>
        <td>
          <p>Recibir información sobre un evento:</p>
          <ul>
            <li>registro/autorización del usuario</li>
            <li>Confirmación de la dirección de correo electrónico del usuario</li>
            <li>vincular la cuenta de redes sociales de un usuario</li>
          </ul>
          <p>Consulte la <a href="/api/login/operation/add-webhook-for-event/">documentación de Login</a> para obtener información detallada sobre cómo establecer webhooks.</p>
        </td>
    </tr>
</tbody>
</table>

# Lista de webhooks requeridos {% #list-of-required-webhooks %}
Si utiliza productos y soluciones que requieren trabajar con webhooks, <a 
href="/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account">active 
y pruebe los webhooks en su Cuenta del editor</a> y <a 
href="/webhooks/overview/#section/Webhook-listener">establezca su 
procesamiento</a>. Cuando se producen eventos específicos, los webhooks se 
envían secuencialmente. Por lo tanto, si no procesa uno de los webhooks, no se 
enviarán los posteriores. La lista de webhooks requeridos se muestra a 
continuación.

## Tienda y pagos {% #store-and-payments %}
Se han configurado dos opciones de envío de webhooks del lado de Xsolla para la 
compra y la devolución de artículos en el sitio web: los datos de pago y de la 
transacción, así como la información sobre los artículos comprados, se pueden 
enviar por separado o se pueden combinar en un webhook.

<b>Recibir información en webhooks combinados:</b>

Si se registró en <a href="https://publisher.xsolla.com/">Cuenta del editor</a> 
después del 22 de enero de 2025, recibirá toda la información en los webhooks 
<a href="/webhooks/operation/successful-order-payment">Successful payment for 
order</a> (`order_paid`) y <a href="/webhooks/operation/order-
cancellation">Order cancellation</a> (`order_canceled`). En este caso, no es 
necesario procesar los webhooks <a href="/webhooks/operation/payment">Pago</a> 
(`payment`) y <a href="/webhooks/operation/refund">Reembolso</a> (`refund`).

<b>Recibir información en webhooks separados:</b>

Si se registró en <a href="https://publisher.xsolla.com/">Cuenta del editor</a> 
el 22 de enero de 2025 o antes, recibirá los siguientes webhooks:
- <a href="/webhooks/operation/payment">Pago</a> (`payment`) y <a 
  href="/webhooks/operation/refund">Reembolso</a> (`refund`) con información 
  sobre los datos de pago y los detalles de la transacción.
- <a href="/webhooks/operation/successful-order-payment-separate">Successful 
  payment for order</a> (`order_paid`) y <a href="/webhooks/operation/order-
  cancellation-separate">Order cancellation</a> (`order_canceled`) con 
  información sobre los artículos comprados.

Debe procesar todos los webhooks entrantes. Para cambiar a la nueva opción con 
la recepción de webhooks combinados, contacte con sus gestores de éxito del 
cliente o escriba a <a href="mailto:csm@xsolla.com">csm@xsolla.com</a>.

Para el funcionamiento completo de la tienda del juego y la gestión de pagos, 
es necesario implementar el procesamiento de los principales webhooks.

<b>Si recibe webhooks combinados</b>:

<table>
<thead>
    <tr>
        <th>Nombre y tipo de webhook</th>
        <th>Descripción</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
        <td>Se envía en diferentes etapas del proceso de pago para garantizar que el usuario está registrado en el juego.</td>
    </tr>
    <tr>
        <td>&gt; Webhooks combinados &gt; de Game services <a href="/webhooks/operation/successful-order-payment">Successful payment for order</a> (<code>order_paid</code>)</td>
        <td>Contiene datos de pago, detalles de la transacción e información sobre los artículos comprados. Utilice los datos del webhook para añadir artículos al usuario.</td>
    </tr>
    <tr>
        <td>Servicios de juego &gt; Webhooks combinados &gt; <a href="/webhooks/operation/order-cancellation">Cancelación del pedido</a> (<code>order_canceled</code>)</td>
        <td>Contiene datos del pago cancelado, detalles de la transacción e información sobre los artículos comprados. Utilice los datos del webhook para eliminar los artículos comprados.</td>
    </tr>
</tbody>
</table>


<b>Si recibe webhooks separados</b>:

<table>
<thead>
    <tr>
        <th>Nombre y tipo de webhook</th>
        <th>Descripción</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
        <td>Se envía en diferentes etapas del proceso de pago para garantizar que el usuario está registrado en el juego.</td>
    </tr>
    <tr>
        <td>Pagos &gt; <a href="/webhooks/operation/payment">Pago</a> (<code>payment</code>)</td>
        <td>Contiene los datos del pago y los detalles de la transacción.</td>
    </tr>
    <tr>
        <td>&gt; Webhooks separados &gt;de Game services  <a href="/webhooks/operation/successful-order-payment-separate">Successful payment for order</a> (<code>order_paid</code>)</td>
        <td>Contiene información sobre los artículos comprados. Utilice los datos del webhook para añadir artículos al usuario.</td>
    </tr>
    <tr>
        <td>Pagos &gt; <a href="/webhooks/operation/refund">Reembolso</a> (<code>refund</code>)</td>
        <td>Contiene los datos del pago y los detalles de la transacción.</td>
    </tr>
    <tr>
        <td>Servicios de juego &gt; Webhooks separados &gt; <a href="/webhooks/operation/order-cancellation-separate">Cancelación del pedido</a> (<code>order_canceled</code>)</td>
        <td>Contiene información sobre los artículos comprados y el ID de la transacción cancelada. Utilice los datos del webhook para eliminar los artículos comprados.</td>
    </tr>
</tbody>
</table>

Si la <a href="/doc/in-game-store/features/personalization">personalización</a> 
del catálogo de artículos se implementa en el lado de su aplicación, establezca 
el procesamiento del webhook <a href="/webhooks/operation/personalized-partner-
catalog">Personalización del catálogo en el lado del socio</a>.

<div class="note">
<p><strong>Nota</strong></p>
<p>Para recibir pagos reales, solo es necesario <a href="/doc/in-game-store/integration-guide/sign-licensing-agreement/">firmar el acuerdo de licencia</a> e implementar el procesamiento de los webhooks:</p>
<p><ul><li><a href="/webhooks/operation/payment">Payment</a>, <a href="/webhooks/operation/successful-order-payment-separate">Successful payment for order</a> y <a href="/webhooks/operation/user-validation/">User validation</a> si recibe webhooks separados</li><li><a href="/webhooks/operation/successful-order-payment">Successful payment for order</a> y <a href="/webhooks/operation/user-validation/">User validation</a> si recibe webhooks combinados.</li></ul></p>
</div>

## Suscripciones {% #required-webhooks-subscriptions %}
Para gestionar automáticamente los planes de suscripción, es necesario 
implementar el procesamiento de los principales webhooks:
- <a href="/webhooks/operation/user-validation/">Validación del usuario</a> 
  (`user_validation`): se envía en diferentes etapas del proceso de pago para 
  garantizar que el usuario esté registrado en el juego.
- <a href="/webhooks/operation/payment">Pago</a> (`payment`): se envía cuando se 
  paga un pedido y contiene los datos del pago y los detalles de la transacción.
- <a href="/webhooks/operation/created-subscription/">Suscripción creada</a> 
  (`create_subscription`): se envía cuando se ha procesado correctamente un 
  webhook de <a href="/webhooks/operation/payment">Pago</a> o el usuario ha 
  adquirido una suscripción con un periodo de prueba. Contiene los detalles de la 
  suscripción adquirida y los datos del usuario. Use los datos del webhook para 
  agregar una suscripción al usuario.
- <a href="/webhooks/operation/updated-subscription/">Suscripción actualizada</a> 
  (`update_subscription`): se envía cuando se renueva o modifica una suscripción, 
  cuando se ha procesado correctamente un webhook de <a 
  href="https://developers.xsolla.com/es/webhooks/operation/payment">Pago</a>. 
  Contiene los detalles de la suscripción adquirida y los datos del usuario. Use 
  los datos del webhook para ampliar la suscripción del usuario o cambiar los 
  parámetros de la suscripción.
- <a href="/webhooks/operation/refund">Reembolso</a> (`refund`): se envía cuando 
  se cancela un pedido y contiene los datos del pago cancelado y los detalles de 
  la transacción.
- <a href="/webhooks/operation/canceled-subscription/">Suscripción cancelada</a> 
  (`cancel_subscription`): se envía cuando se ha procesado correctamente un 
  webhook de <a href="/webhooks/operation/refund">Reembolso</a> o se ha cancelado 
  la suscripción por otro motivo. Contiene información sobre la suscripción y los 
  datos del usuario. Use los datos del webhook para sustraer al usuario las 
  suscripciones adquiridas.

# Establecer webhooks en Cuenta del editor {% #set-up-webhooks-in-publisher-account %}

## Configuración general {% #general-settings %}

Para habilitar la recepción de webhooks:
1. En el proyecto en Cuenta del editor vaya a <a 
   href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>.
2. En el campo <b>Webhook server</b>, especifique la URL de su servidor en el que 
   desea recibir webhooks en el formato `https://example.com`. También puede 
   especificar la URL que encuentre en una herramienta para probar webhooks.

<div class="notice">
<p><strong>Aviso</strong></p>
<p> El protocolo HTTPS se utiliza para transferir datos; el protocolo HTTP no es compatible.</p>
</div>

<p></p>

3. Genere una clave secreta:

<ol><ol type="a">
<li>En la sección <strong>Secret keys</strong>, haga clic en <strong>Add key</strong>.</li>
<li>En la ventana modal que se abre, introduzca el nombre de la clave que le permita identificarla en la lista general.</li>
<li>Haga clic en <strong>Create key</strong>.</li>
<li>Haga clic en <strong>Copy secret</strong> y guarde la clave creada en un lugar seguro.</li>
<li>Haga clic en <strong>Done</strong>.</li>
<li>Confirme que ha guardado la clave y haga clic en <strong>Ok, close</strong>.</li>
</ol></ol>

![Añadir 
clave](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-key.svg)

<div class="notice">
<p><strong>Aviso</strong></p>
<p>Recomendaciones:<ul>
<li><strong>Guarde la clave secreta generada en un lugar seguro</strong>. Puede ver la clave en Cuenta del editor solo una vez cuando se crea.</li>
<li>No comparta su clave secreta con nadie.</li>
<li>La clave secreta debe guardarse en su servidor y nunca en binarios o en el front-end.</li></ul>
</p>
</div>

4. Haga clic en **Enable webhooks**.

<div class="note">
<p><strong>Tenga en cuenta</strong></p>
<p>Para probar los webhooks, puede seleccionar cualquier sitio web específico, como <a href="https://webhook.site/#!/">webhook.site</a>, o una plataforma, como <a href="https://ngrok.com/">ngrok</a>.</p>
</div>

<p></p>

<div class="notice">
    <p><strong>Aviso</strong></p>
    <p>No es posible enviar webhooks a diferentes URL a la vez. Lo que sí se puede hacer en Cuenta del editor es indicar primero una URL de prueba y, a continuación, sustituirla por la URL real.</p>
</div>

Para deshabilitar la recepción de webhooks:
1. En el proyecto en Cuenta del editor vaya a <a 
   href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>.
2. Haga clic en <b>Disable webhooks</b>.

## Rotación de clave secreta {% #secret-key-rotation %}

Actualizar las claves secretas con frecuencia mejora la seguridad de su 
integración. Puede crear hasta 5 claves secretas en su proyecto para habilitar 
su rotación. Para ello:

1. En <a href="https://publisher.xsolla.com/0/projects/0/edit/webhooks/">Project 
   settings &gt; Webhooks</a>, haga clic en **Add key**.

![Añadir 
clave](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/add-new-key.svg)

2. En la ventana modal que se abre, introduzca el nombre de la clave que le 
   permita identificarla en la lista general.
3. Haga clic en **Create key**.
4. Haga clic en **Copy secret** y guarde la clave creada.
5. Haga clic en **Done**.
6. Confirme que ha guardado la clave y haga clic en **Ok, close**.

<div class="notice">
<p><strong>Aviso</strong></p>
<p>Recomendaciones:<ul>
<li><strong>Guarde la clave secreta generada en un lugar seguro</strong>. Puede ver la clave en Cuenta del editor solo una vez cuando se crea.</li>
<li>No comparta su clave secreta con nadie.</li>
<li>La clave secreta debe guardarse en su servidor y nunca en binarios o en el front-end.</li></ul>
</p>
</div>

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 que elimine las claves desactivadas.

![Cambiar clave 
activa](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/activate-key.svg)

## Configuración avanzada {% #advanced-settings %}

Para los webhooks de la sección <a href="/webhooks/overview/#section/Test-
webhooks-in-Publisher-Account/Store">Payments and Store</a>, hay opciones de 
configuración avanzada disponibles. Aparecerán automáticamente en el bloque <a 
href="/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account/General-
settings">General settings</a> después de hacer clic en el botón <b>Get 
webhooks</b>.

<div class="note">
<p><strong>Nota</strong></p>
<p>Si no se muestra la configuración avanzada, asegúrese de que la recepción de webhooks está conectada en la configuración general y de que se encuentra en la pestaña <b>Testing &gt; Payments and Store</b>.</p>
</div>

En esta sección puede configurar la recepción de información adicional en 
webhooks. Para ello, active la opción. La línea de cada permiso indica los 
webhooks que se verán afectados al cambiar la configuración.

<table>
<thead>
    <tr>
        <th>Conmutador</th>
        <th>Descripción</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Mostrar información sobre la cuenta de pago guardada (solo se muestra si se registró en Cuenta del editor el 22 de enero de 2025 o antes y recibe webhooks separados).</td>
        <td>La información sobre el método de pago guardado se transmite en el objeto personalizado <code>payment_account</code>.</td>
    </tr>
    <tr>
        <td>Mostrar información sobre las transacciones realizadas a través de los métodos de pago guardados.</td>
        <td><p>La información se transmite en los siguientes parámetros personalizados del webhook:</p><ul><li><code>saved_payment_method</code>:<ul><li><code>0</code>: no se utilizó el método de pago guardado</li><li><code>1</code>: el método de pago se guardó al realizar el pago actual</li><li><code>2</code>: se utiliza el método de pago guardado previamente</li></ul></li><li><code>payment_type</code>:<ul><li><code>1</code>: pago único</li><li><code>2</code>: pago periódico</li></ul></li></ul></td>
    </tr>
    <tr>
        <td>Añadir el objeto <code>order</code> al webhook (solo se muestra si se registró en Cuenta del editor el 22 de enero de 2025 o antes y recibe webhooks separados).</td>
        <td>La información sobre el pedido se transmite en el objeto <code>order</code> del webhook <a href="/webhooks/operation/payment/">Pago</a>.</td>
    </tr>
    <tr>
        <td>Enviar solo los parámetros de usuario necesarios, sin incluir datos confidenciales.</td>
        <td><p>Solamente la siguiente información sobre el usuario se transmite en el webhook:</p><ul><li>ID</li><li>país</li></ul></td>
    </tr>
    <tr>
        <td>Enviar parámetros personalizados.</td>
        <td>La información sobre los <a href="/api/pay-station/operation/create-token/">parámetros de token personalizados</a> se transmite en el webhook.</td>
    </tr>
    <tr>
        <td>Mostrar el número BIN y el sufijo de la tarjeta.</td>
        <td><p>La siguiente información sobre el número de tarjeta bancaria se transmite en el webhook:</p><ul><li>los 6 primeros dígitos del parámetro <code>card_bin</code></li><li>los 4 últimos dígitos del <code>card_suffix</code></li></ul></td>
    </tr>
    <tr>
        <td>Mostrar la marca de la tarjeta.</td>
        <td>La marca de la tarjeta empleada para realizar el pago. Por ejemplo, Mastercard o Visa.</td>
    </tr>
    <tr>
        <td>Mostrar información sobre el motivo del reembolso.</td>
        <td>Información detallada sobre los motivos del reembolso.</td>
    </tr>
    <tr>
        <td>Mostrar la retención fiscal del país y las comisiones de adquisición de usuarios.</td>
        <td>Los objetos <code>payment_details.​country_wht</code> y <code>payment_details.​user_acquisition_fee</code> se transmitirán en el webhook. Esta opción está activada por defecto.</td>
    </tr>
    <tr>
        <td>Enviar información de 3DS.</td>
        <td>El objeto <code>cards</code> que contiene datos sobre la verificación 3-D Secure se transmitirá en el webhook.</td>
    </tr>
</tbody>
</table>

![Configuración 
avanzada](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/advanced-settings.png)

# Probar webhooks en Cuenta del editor {% #test-webhooks-in-publisher-account %}

Probar los webhooks ayuda a asegurar la correcta configuración del proyecto 
tanto en su lado como en el lado de Xsolla.

Si los webhooks están <a href="/webhooks/overview/#section/Set-up-webhooks-in-
Publisher-Account">establecidos</a> correctamente, aparecerá una sección de 
prueba de webhooks bajo la sección de configuración de webhooks.

![Sección de pruebas de 
webhooks](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-section.svg)

La sección de pruebas de Cuenta del editor varía en función de la opción de 
recepción de webhooks.

Si se registró en Cuenta del editor después del 22 de enero de 2025, recibirá 
webhooks combinados:

<table>
<thead>
    <tr>
        <th>Nombre de la pestaña para pruebas de webhooks</th>
        <th>Nombre y tipo de webhook</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><b>Payments and store</b></td>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>&gt; Webhooks combinados &gt; de Game services <a href="/webhooks/operation/successful-order-payment">Successful payment for order</a> (<code>order_paid</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Servicios de juego &gt; Webhooks combinados &gt; <a href="/webhooks/operation/order-cancellation">Cancelación del pedido</a> (<code>order_canceled</code>)</td>
    </tr>
    <tr>
        <td><b>Subscriptions</b></td>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Pagos &gt; <a href="/webhooks/operation/payment">Pago</a> (<code>payment</code>)</td>
    </tr>
</tbody>
</table>


Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, recibirá 
webhooks separados:

<table>
<thead>
    <tr>
        <th>Nombre de la pestaña para pruebas de webhooks</th>
        <th>Nombre y tipo de webhook</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><b>Store</b></td>
        <td>&gt; Webhooks separados &gt;de Game services  <a href="/webhooks/operation/successful-order-payment-separate">Successful payment for order</a> (<code>order_paid</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Servicios de juego &gt; Webhooks separados &gt; <a href="/webhooks/operation/order-cancellation-separate">Cancelación del pedido</a> (<code>order_canceled</code>)</td>
    </tr>
    <tr>
        <td><b>Payments</b></td>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Pagos &gt; <a href="/webhooks/operation/payment">Pago</a> (<code>payment</code>)</td>
    </tr>
    <tr>
        <td><b>Subscriptions</b></td>
        <td>Validación del usuario &gt; <a href="/webhooks/operation/user-validation/">Validación del usuario</a> (<code>user_validation</code>)</td>
    </tr>
    <tr>
        <td></td>
        <td>Pagos &gt; <a href="/webhooks/operation/payment">Pago</a> (<code>payment</code>)</td>
    </tr>
</tbody>
</table>

<div class="note">
<p><strong>Tenga en cuenta</strong></p>
<p>Si aparece un aviso de que la prueba no se ha superado en la sección de pruebas, verifique la configuración de la respuesta del webhook en su <a href="/webhooks/overview/#section/Webhook-listener">agente de escucha del webhook</a>. Los motivos de los errores en la prueba se indican en los resultados de la prueba. </p>
<p><b>Ejemplo:</b></p>
<p>Cuando utiliza el sitio especializado <a href="https://webhook.site/#!/">webhook.site</a> para la prueba.</p>
<p>Aparece un error en la sección <b>Testing response to invalid signature</b>.</p>
<p>Esto ocurre porque Xsolla envía un webhook con una firma incorrecta y espera que su controlador responda con un código HTTP <code>4xx</code> que especifique el código de error <code>INVALID_SIGNATURE</code>.</p>
<p><a href="https://webhook.site/#!/">webhook.site</a> envía un código HTTP <code>200</code> en respuesta a todos los webhooks, incluyendo un webhook con una firma incorrecta. No se puede obtener el código HTTP <code>4xx</code> esperado, por lo que aparece un error en el resultado de la prueba.</p>
</div>

A continuación se describe el proceso de pruebas para el escenario con webhooks 
combinados.

## Payments and Store {% #payments-and-store %}

En la pestaña <b>Payments and Store</b>, puede probar los siguientes webhooks:
- <a href="/webhooks/operation/user-validation/">Validación del usuario</a> 
  (`user_validation`)
- <a href="/webhooks/operation/successful-order-payment">Successful payment for 
  order</a> (`order_paid`)
- <a href="/webhooks/operation/order-cancellation">Cancelación del pedido</a> 
  (`order_canceled`)

Para probar los webhooks:
1. En la sección de pruebas de webhooks, vaya a la pestaña <b>Payments and 
   Store</b>.
2. En la lista desplegable, seleccione el tipo de artículo. Si aún no ha 
   configurado este tipo de artículo en Cuenta del editor, haga clic en el botón 
   para configurarlo. Una vez creado el artículo, vuelva a la sección de pruebas 
   del webhook y continúe con el siguiente paso.
3. Rellene los campos necesarios:
   * **User ID**: al realizar pruebas, puede utilizar cualquier combinación de 
     letras y números.
   * Introduzca cualquier valor en el campo **Xsolla order ID**.
   * **Xsolla invoice ID**: ID de la transacción en Xsolla. Al hacer pruebas, puede 
     usar cualquier valor numérico.
   * **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.
   * **Amount**: importe del pago. Al hacer pruebas, puede utilizar cualquier valor 
     numérico.
   * **Currency**: seleccione una moneda de la lista desplegable.
   * Seleccione el SKU de los artículos en la lista desplegable e indique la 
     cantidad. Puede seleccionar varios artículos del mismo tipo haciendo clic en 
     **+** y añadiéndolos en una nueva línea.
4. Haga clic en **Test webhooks**.

Los webhooks <a href="/webhooks/operation/user-validation/">User 
validation</a>, <a href="/webhooks/operation/successful-order-
payment">Successful payment for order</a> y <a href="/webhooks/operation/order-
cancellation">Order cancellation</a> con los datos especificados se envían a la 
URL facilitada. Los resultados de la prueba de cada tipo de webhook se muestran 
debajo del botón <b>Test webhooks</b>.

Si la casilla <b>Use public user ID</b> está marcada en <a 
href="https://publisher.xsolla.com/0/projects/0/edit/advanced">Project settings 
> Integration settings</a>, el webhook <a href="/webhooks/user-validation/user-
search">Búsqueda del usuario</a> también se enviará a la URL de su servidor de 
webhooks y se mostrará el resultado de la prueba.

Para cada webhook, tiene que establecer el procesamiento de ambos escenarios: 
uno, satisfactorio, y el otro, fallido.

¡[Sección de pruebas de 
pagos](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks/testing-results.svg)

## Suscripciones {% #test-webhooks-subscriptions %}

<div class="note">
<p><strong>Nota</strong></p>
<p>Para probar los webhooks, debe tener al menos un <a href="/sell-subscriptions/integration-guide/set-up-plan/">plan de suscripción creado</a> en Cuenta del editor en <a href="https://publisher.xsolla.com/0/projects/0/subscriptions/plans">Items catalog &gt; Subscriptions</a>.</p>
</div>

En la pestaña <b>Subscriptions</b> puede probar los siguientes webhooks:
- <a href="/webhooks/operation/user-validation/">Validación del usuario</a> 
  (`user_validation`)
- <a href="/webhooks/operation/payment">Pago</a> (`payment`)

<div class="note">
<p><strong>Nota</strong></p>
<p>Encontrará información detallada sobre cómo probar otros escenarios de gestión de suscripciones en la <a href="/sell-subscriptions/integration-guide/set-up-plan/#guides_subscriptions_set_up_plan_testing_purchase">guía de integración</a>.</p>
</div>

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](https://publisher.xsolla.com/0/projects/0/edit/advanced).
   * **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](/es/sell-subscriptions/integration-guide/get-started/#guides_subscriptions_glossary_product) 
     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](/es/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_sandbox) o 
     para probar la [renovación de una suscripción](/es/sell-subscriptions/integration-guide/get-subscription-information/#guides_subscriptions_get_subscription_set_up_webhooks_test_renewal)
     , 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 <b>Test</b>.

# Agente de escucha de webhooks {% #webhook-listener %}

El agente de escucha es un código de programa que permite recibir webhooks 
entrantes en una dirección URL especificada, <a 
href="/webhooks/overview/#section/Webhook-listener/Generation-of-
signature">generar una firma</a> y <a href="/webhooks/overview/#section/Webhook-
listener/Sending-responses-to-webhook">enviar una respuesta</a> al servidor de 
webhooks de Xsolla.

<div class="note">
<p><strong>Nota</strong></p>
<p>Puede utilizar la biblioteca de <a href="https://developers.xsolla.com/es/sdk/php/">SDK para PHP de Pay Station</a>, que contiene clases predefinidas para procesar webhooks.</p>
</div>

<!-- IMPORTANT! Changing the list of IP addresses should be coordinated with the administrators. Request for Director of Infrastructure and IT approval in the ticket for changing the IP address list. -->

En el lado de su aplicación, implemente la recepción de webhooks desde las 
siguientes direcciones IP:
- `185.30.20.0/24`
- `185.30.21.0/24`
- `185.30.22.0/24`
- `185.30.23.0/24`
- `34.102.38.178`
- `34.94.43.207`
- `35.236.73.234`
- `34.94.69.44`
- `34.102.22.197`

Si ha integrado el producto <a href="/doc/login/">Login</a>, añada webhooks de 
procesamiento desde las siguientes direcciones IP:

- `34.94.0.85`
- `34.94.14.95`
- `34.94.25.33`
- `34.94.115.185`
- `34.94.154.26`
- `34.94.173.132`
- `34.102.48.30`
- `35.235.99.248`
- `35.236.32.131`
- `35.236.35.100`
- `35.236.117.164`

Limitaciones:
- En la base de datos de su aplicación no debería haber varias transacciones 
  aceptadas con el mismo ID.
- Si el agente de escucha de webhooks recibió un webhook con un ID que ya existe 
  en la base de datos, deberá devolver el resultado del procesamiento anterior de 
  esta transacción. No se recomienda acreditar al usuario una compra duplicada ni 
  crear registros duplicados en la base de datos.

## Generación de firma {% #generation-of-signature %}

Para garantizar una transmisión de datos segura, debe comprobar que el webhook 
se ha enviado desde el servidor de Xsolla y que no ha sido manipulado durante 
el tránsito. Para ello, genere su propia firma basada en la carga útil del 
cuerpo de la solicitud y compárela con la firma proporcionada en el encabezado 
`authorization` de la solicitud entrante. Si las firmas coinciden, significa 
que el webhook es auténtico y seguro de procesar.

Pasos de verificación:

1. Obtenga la firma del encabezado `authorization` de la solicitud de webhook 
   entrante. El formato del encabezado es `Signature <signature_value>`.
2. Obtenga el cuerpo de la solicitud del webhook en formato JSON. <div 
   class="notice"><p><strong>Aviso</strong></p><p>Use la carga JSON tal y como la 
   ha recibido. No analice ni recodifique la carga, ya que esto alteraría el 
   formato y provocaría que la verificación de la firma fallara.</p></div><p></p>

3. Genere su propia firma para comparar: <ol type="a"> <li>Concatene la carga JSON 
   con la clave secreta de su proyecto al añadir la clave al final de la 
   cadena.</li> <li>Aplique la función hash criptográfica SHA-1 a la cadena 
   obtenida. El resultado será una cadena hexadecimal en minúsculas.</li> </ol>
4. Compare su firma generada con la del encabezado `authorization`. Si coinciden, 
   significa que el webhook es auténtico.

A continuación encontrará ejemplos de implementación de generación de firmas 
para los siguientes lenguajes: C#, C++, Go, PHP y Node.js.

### Ejemplo de webhook (HTTP): {% #example-of-a-webhook-http %}

```http
POST /your_uri HTTP/1.1
host: your.host
accept: application/json
content-type: application/json
content-length: 165
authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}
```

### Ejemplo de webhook (curl): {% #example-of-a-webhook-curl %}

```bash
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'
```

### Ejemplo C# de implementación de generación de firmas (muestra general): {% #csharp-signature-generation-general-sample %}

<div class="note">
<p><strong>Nota</strong></p>
<p>Este ejemplo de código es compatible con .NET Framework 4.0 y versiones posteriores, así como con .NET Core y otras versiones modernas de .NET. La verificación de firmas utiliza la comparación en tiempo constante a través del método <code>ConstantTimeEquals</code> para ayudar a prevenir ataques de temporización.</p>
</div>

```csharp
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        // Concatenation of the JSON from the request body and the project's secret key
        string dataToSign = jsonBody + secretKey;
        using (SHA1 sha1 = SHA1.Create())
        {
            byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
            // Convert hash bytes to lowercase hexadecimal string
            var hexString = new StringBuilder(hashBytes.Length * 2);
            foreach (byte b in hashBytes)
            {
                hexString.Append(b.ToString("x2"));
            }
            return hexString.ToString();
        }
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}
```

### Ejemplo C# de implementación de generación de firmas (.NET 5.0 y posteriores): {% #csharp-signature-generation-net-5-0-and-later %}

<div class="note">
<p><strong>Nota</strong></p>
<p>Para utilizar el método <code>Convert.ToHexString</code>, necesita .NET 5.0 y posterior.<p></p>Si tiene .NET 7.0 y posterior, también puede utilizar el método <code>CryptographicOperations.FixedTimeEquals</code> en lugar de <code>ConstantTimeEquals</code>.</p>
</div>

```csharp
// For .NET 5.0 and later, you can use the more concise Convert.ToHexString method:
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        string dataToSign = jsonBody + secretKey;
        using var sha1 = SHA1.Create();
        byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
        return Convert.ToHexString(hashBytes).ToLower();
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}
```

### Ejemplo C# de implementación de generación de firmas (.NET 7.0 y posteriores): {% #csharp-signature-generation-net-7-0-and-later %}

<div class="note">
<p><strong>Nota</strong></p>
<p>Si dispone de .NET 7.0 y versiones posteriores, puede utilizar el método <code>CryptographicOperations.FixedTimeEquals</code>.</p>
</div>

```csharp
// For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals:
using System.Security.Cryptography;
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
    string computedSignature = ComputeSha1(jsonBody, secretKey);
    byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature);
    byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower());
    return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes);
}
```

### Ejemplo C++ de implementación de generación de firmas: {% #cpp-signature-generation %}

```c++
#include <string>
#include <sstream>
#include <iomanip>
#include <openssl/sha.h>
class XsollaWebhookSignature {
public:
    static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        std::string dataToSign = jsonBody + secretKey;
        unsigned char digest[SHA_DIGEST_LENGTH];
        // Create SHA1 hash
        SHA1(reinterpret_cast<const unsigned char*>(dataToSign.c_str()),
             dataToSign.length(), digest);
        // Convert to lowercase hexadecimal string
        std::ostringstream hexStream;
        hexStream << std::hex << std::setfill('0');
        for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) {
            hexStream << std::setw(2) << static_cast<unsigned int>(digest[i]);
        }
        return hexStream.str();
    }
    static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) {
        std::string computedSignature = computeSha1(jsonBody, secretKey);
        // Timing-safe comparison
        if (computedSignature.length() != receivedSignature.length()) {
            return false;
        }
        volatile unsigned char result = 0;
        for (size_t i = 0; i < computedSignature.length(); ++i) {
            result |= (computedSignature[i] ^ receivedSignature[i]);
        }
        return result == 0;
    }
};
```

### Ejemplo Go de implementación de generación de firmas: {% #go-signature-generation %}

```go
package main
import (
	"crypto/sha1"
    "crypto/subtle"
	"encoding/hex"
	"strings"
)
type XsollaWebhookSignature struct{}
func (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {
	// Concatenation of the JSON from the request body and the project's secret key
	dataToSign := jsonBody + secretKey
	// Create SHA1 hash
	h := sha1.New()
	h.Write([]byte(dataToSign))
	signature := h.Sum(nil)
	// Convert to lowercase hexadecimal string
	return strings.ToLower(hex.EncodeToString(signature))
}
func (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {
	computedSignature := x.ComputeSha1(jsonBody, secretKey)
	receivedSignatureLower := strings.ToLower(receivedSignature)
	// Use constant time comparison to prevent timing attacks
	return subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1
}
```

### Ejemplo PHP de implementación de generación de firmas: {% #php-signature-generation %}

```php
<?php
class XsollaWebhookSignature
{
    /**
     * Compute SHA1 signature from webhook JSON body and secret key
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key
     * @return string The lowercase SHA1 signature
     */
    public static function computeSha1(string $jsonBody, string $secretKey): string
    {
        // Concatenation of the JSON from the request body and the project's secret key
        $dataToSign = $jsonBody . $secretKey;
        // Generate SHA1 signature
        $signature = sha1($dataToSign);
        return strtolower($signature);
    }
    /**
     * Verify webhook signature using timing-safe comparison
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key  
     * @param string $receivedSignature The signature from authorization header
     * @return bool True if signature is valid, false otherwise
     */
    public static function verifySignature(string $jsonBody, string $secretKey, string $receivedSignature): bool
    {
        $computedSignature = self::computeSha1($jsonBody, $secretKey);
        // Use hash_equals for timing-safe comparison
        return hash_equals($computedSignature, strtolower($receivedSignature));
    }
}
?>
```

### Ejemplo Node.js de implementación de generación de firmas: {% #nodejs-signature-generation %}

```js
const crypto = require('crypto');
class XsollaWebhookSignature {
    // IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla
    static computeSha1(jsonBody, secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        const dataToSign = jsonBody + secretKey;
        // Create SHA1 hash
        const hash = crypto.createHash('sha1');
        hash.update(dataToSign, 'utf8');
        // Convert to lowercase hexadecimal string
        return hash.digest('hex').toLowerCase();
    }
    static verifySignature(jsonBody, secretKey, receivedSignature) {
        const computedSignature = this.computeSha1(jsonBody, secretKey);
        const cleanReceivedSignature = receivedSignature.toLowerCase();
        // Check if signatures have the same length before using timingSafeEqual
        if (computedSignature.length !== cleanReceivedSignature.length) {
            return false;
        }
        try {
            return crypto.timingSafeEqual(
                Buffer.from(computedSignature, 'hex'),
                Buffer.from(cleanReceivedSignature, 'hex')
            );
        } catch (error) {
            // Return false if there's any error (e.g., invalid hex characters)
            return false;
        }
    }
}
```

## Enviar respuestas al webhook {% #sending-responses-to-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 satisfactoria.
* Código HTTP "400" con la <a 
  href="/webhooks/overview/#section/Errores">descripción del problema</a> si no se 
  encontró el usuario especificado o se transmitió una firma no válida. Su gestor 
  de webhooks también puede devolver un código HTTP "5xx" si hay problemas 
  temporales en su servidor.

Si el servidor de Xsolla no ha recibido respuesta a los webhooks <a 
href="/webhooks/operation/successful-order-payment">Successful payment for 
order</a> y <a href="/webhooks/operation/order-cancellation">Order 
cancellation</a> o ha recibido una respuesta con un código `5xx`, los webhooks 
se reenvían de la siguiente manera:
* 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 realiza un máximo de 20 intentos de envío de webhooks en un plazo de 12 
horas desde el primer intento.

La lógica de reintento para los webhooks de <a 
href="/webhooks/operation/payment">pago</a> y <a 
href="/webhooks/operation/refund">reembolso</a> se describe en la página del 
webhook correspondiente.

<div class="notice">
<p><strong>Aviso</strong></p>
<p>El pago se reembolsará al usuario si se cumplen las siguientes condiciones:<ul><li>El reembolso lo inició Xsolla.</li><li>En respuesta a un webhook, se devolvió un código de estado <code>4xx</code>, o no se recibió ninguna respuesta tras todos los intentos, o se devolvió un código de estado <code>5xx</code>.</li></ul></p>
</div>

Si el servidor de Xsolla no ha recibido respuesta al webhook <a 
href="/webhooks/operation/user-validation/">User validation</a> o ha recibido 
una respuesta con un código `400` o `5xx`, el webhook <a 
href="/webhooks/operation/user-validation/">User validation</a> no se reenvía. 
En este caso, el usuario ve un error y los webhooks <a 
href="/webhooks/operation/payment">Payment</a> y <a href="/webhooks/operation
/successful-order-payment">Successful payment for order</a> no se envían.

# Errores {% #errors %}

Códigos de error para el código HTTP 400:

<table>
<thead>
    <tr>
        <th>Código</th>
        <th>Mensaje</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>INVALID_USER</td>
        <td>Usuario no válido</td>
    </tr>
    <tr>
        <td>INVALID_PARAMETER</td>
        <td>Parámetro no válido</td>
    </tr>
    <tr>
        <td>INVALID_SIGNATURE</td>
        <td>Firma no válida</td>
    </tr>
    <tr>
        <td>INCORRECT_AMOUNT</td>
        <td>Importe incorrecto</td>
    </tr>
    <tr>
        <td>INCORRECT_INVOICE</td>
        <td>Factura incorrecta</td>
    </tr>
</tbody>
</table>

```
HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}
```

# Prácticas recomendadas {% #best-practices %}

## Seguridad {% #security %}

Siga estas directrices:

* Utilice solo HTTPS, con un certificado válido.
* Verifique siempre la firma comparándola con el cuerpo de la solicitud sin 
  procesar; no analice ni recodifique los datos.
* No transmita datos sensibles en las URL y evite revelar detalles técnicos en 
  los mensajes de error.
* Excluya el punto final del webhook del middleware 
  [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery): las 
  solicitudes de Xsolla no incluyen un token CSRF y se rechazarán si no se aplica 
  esta configuración.
* Incluya las [direcciones IP de Xsolla](/es/webhooks/section/webhook-listener) en 
  la lista de permitidos.


## Arquitectura del controlador de webhooks {% #webhook-handler-architecture %}

Siga estas directrices:

1. Acepte la solicitud `POST` con el cuerpo y los encabezados tal cual, **sin 
   modificaciones**.
2. [Verifique la firma del webhook](/es/webhooks/section/webhook-listener/generation-of-signature) y devuelva el código de estado correspondiente:
   * `4xx`: si las firmas no coinciden;
   * `2xx`: en casos de éxito. Recomendamos devolver `204 No Content` **antes** de 
     ejecutar la lógica de negocio principal. También es aceptable `200 OK`.
3. Transmita la carga útil a una tarea asíncrona o a una cola para su posterior 
   procesamiento.
4. Implemente la 
   [idempotencia](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning). Asegúrese de que su sistema admite [recibir el mismo webhook más de una 
   vez](/es/webhooks/section/webhook-listener/sending-responses-to-webhook).

**Ejemplo de flujo:**

```http
HTTP POST /webhooks/xsolla
  read raw_body, headers
  if !verify_signature(raw_body, headers['authorization']):
     return 400 {"error":{"code":"INVALID_SIGNATURE","message":"Invalid signature"}}
  enqueue(raw_body)
  return 204  # or 200
```

## Idempotencia y duplicados {% #idempotency-and-duplicates %}

Siga estas directrices:

* Utilice el ID de transacción o el [ID externo](/es/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id), ID de 
  pedido como claves de idempotencia.
* Almacene los ID procesados y devuelva el resultado anterior si se recibe un 
  duplicado.
* Evite la concesión duplicada de artículos, las entradas duplicadas en la base 
  de datos y los cobros duplicados.
* Tenga en cuenta que, en el caso de la entrega secuencial, un fallo en un evento 
  anterior bloquea el procesamiento de todos los siguientes.

## Resiliencia del sistema {% #system-resilience %}

Siga estas directrices:

* Utilice colas y el procesamiento asíncrono para operaciones que consumen muchos 
  recursos, como llamadas API de terceros, facturación y concesión de artículos.
* Configure los tiempos de espera en el controlador de webhook (1-3 s). En caso 
  de fallos temporales, utilice el [mecanismo de reintento de 
  Xsolla](/es/webhooks/section/webhook-listener/sending-responses-to-webhook).
* No implemente reintentos en el controlador del webhook: la reentrega la 
  gestiona Xsolla.
* Registre las marcas de tiempo de entrega de los webhooks y los estados de 
  procesamiento; configure avisos para los picos de errores `5xx` y los reenvíos.
* Propague los ID de correlación desde el webhook a sus registros y a su sistema 
  de monitorización (APM).
* Configure el registro y la supervisión de errores. En los casos de fallos 
  irrecuperables, traslade los trabajos a una cola de mensajes no entregados 
  (DLQ). Desarrolle una herramienta segura para reproducir eventos que esté 
  protegida por un mecanismo de idempotencia.

## Ejemplos de aplicación {% #implementation-examples %}

**Compra realizada con éxito: artículo concedido en el primer intento:**

![Compra](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/purchase-v2.svg)

**Entrega duplicada (tiempo de espera agotado en el primer intento por parte 
del socio):**

![Tiempo de espera](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/timeout-v2.svg)

**Reembolso:**

![Reembolso](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/refund-v2.svg)

**Interrupción del servicio del socio**:

![Interrupción del servicio del 
socio](https://cdn.xsolla.net/developers/current/images/api_docs/webhook-schemes/server-error.svg)

# Preguntas frecuentes {% #faqs %}

## ¿Es necesario utilizar HTTPS para un protocolo de webhook? {% #do-i-need-to-use-https-for-a-webhook-protocol %}

Sí.

## ¿Puedo recibir webhooks de pago en varias direcciones URL? {% #can-i-receive-payment-webhooks-at-several-urls %}

No. Los webhooks de pago utilizan el protocolo de servidor a servidor y se 
envían a una única URL especificada en la [configuración del proyecto 
](/es/webhooks/section/set-up-webhooks-in-publisher-account). Si quiere recibir 
notificaciones en su juego, sitio web o aplicación móvil, configure el envío de 
webhooks en su servidor para transferir datos entre Xsolla y su juego. También 
puede probar los webhooks desde la consola de desarrollador.

<div class="note">
<p><strong>Nota</strong></p>
<p>Si está probando la integración de forma local, las solicitudes `POST` de Xsolla no llegan a direcciones URL como <code>http://localhost:3000/my-webhook-endpoint</code>. Utilice servicios como <a href="https://ngrok.com/">ngrok</a> que permiten crear un túnel de acceso externo para recibir solicitudes de Xsolla en su entorno local. Encontrará más información al respecto en la <a href="https://ngrok.com/docs/guides/share-localhost/webhooks#test-webhooks-locally">documentación de ngrok</a>.</p>
</div>

## ¿Por qué no se ha enviado la notificación de Xsolla a la URL del webhook? {% #why-was-xsolla-notification-not-sent-to-the-webhook-url %}

Asegúrese de que su servidor de webhooks admita los tipos de solicitudes HTTP 
`POST` y `GET`.

## ¿Cómo puedo evitar que se dupliquen los ID de transacción durante el procesamiento? {% #how-do-i-prevent-duplicate-transaction-ids-during-processing %}

Utilice el ID externo: este es el ID de la transacción en su juego, asignado al 
pedido en su sistema. Del lado de Xsolla, el ID externo está vinculado al ID de 
la transacción, lo que permite a Xsolla evitar pagos duplicados para la misma 
transacción. Para obtener más información sobre la configuración, consulte 
nuestra [documentación](/es/dev-resources/faq/payments/#faq_payments_q_new_transaction_external_id).

## ¿Cuáles son las prácticas recomendadas para trabajar con webhooks? {% #are-there-any-best-practices-for-working-with-webhooks %}

Recomendamos:

* Devolver `204` o `200` inmediatamente después de la verificación de la firma.
* Comprobar la firma del webhook en relación con el cuerpo de la solicitud, sin 
  modificaciones.
* Implementar la idempotencia para todas las operaciones.
* Registrar todos los eventos y configurar la supervisión de errores.
* Evitar incluir datos sensibles en las URL y no exponer detalles técnicos en los 
  mensajes de error.

Consulte la sección [Prácticas recomendadas](/es/webhooks/section/best-practices) 
para obtener información detallada.

# Lista de comprobación para la integración de webhooks {% #webhook-integration-checklist %}

Para que los webhooks funcionen correctamente, asegúrese de tener lo siguiente 
configurado antes de activarlos:

* Se utiliza HTTPS.
* La [verificación de firma](/es/webhooks/section/webhook-listener/generation-of-signature) del webhook se implementa en función del cuerpo de la solicitud sin 
  procesar y sin modificación.
* Se devuelve una respuesta `204/200` en cuanto se confirma la firma.
* La idempotencia se aplica a todas las operaciones.
* Se han configurado el registro de errores y la supervisión.
* No se transmiten datos sensibles en las URL ni se exponen detalles técnicos en 
  los mensajes de error.
* Se admiten reintentos de webhooks conforme a la [lógica de reintentos de 
  Xsolla](/es/webhooks/section/webhook-listener/sending-responses-to-webhook).
* Toda la integración está documentada.

# Lista de webhooks {% #webhooks-list %}

<div class="note">
<p><strong>Observación</strong></p>
<p>El tipo de notificación se envía en el parámetro <code>notification_type</code>.</p>
</div>

<table>
<thead>
    <tr>
        <th>Webhook</th>
        <th>Tipo de notificación</th>
        <th>Descripción</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td><a href="/webhooks/operation/user-validation/">Validación del usuario</a></td>
        <td><code>user_validation</code></td>
        <td>Se envía para comprobar si un usuario existe en el juego.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/user-search/">Búsqueda de usuario</a></td>
        <td><code>user_search</code></td>
        <td>Se envía para obtener información de usuario basada en el ID público del usuario.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/payment/">Pago</a></td>
        <td><code>payment</code></td>
        <td>Se envía cuando un usuario realiza un pago.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/refund/">Reembolso</a></td>
        <td><code>refund</code></td>
        <td>Se envía cuando un pago debe cancelarse por cualquier motivo.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/partial-refund/">Reembolso parcial</a></td>
        <td><code>partial_refund</code></td>
        <td>Se envía cuando un pago debe cancelarse parcialmente por cualquier motivo.</td>
    </tr>
    <tr>
        <td><a href="/webhooks/operation/payment-declined/">Pago rechazado</a></td>
        <td><code>ps_declined</code></td>
        <td>Se envía cuando un pago es rechazado por el sistema de pago.</td>
    </tr>
    <tr>
        <td><a href="https://developers.xsolla.com/es/webhooks/operation/afs-rejected-transaction/">Transacción de AFS rechazada</a> </td>
        <td><code>afs_reject</code></td>
        <td>Se envía cuando se rechaza una transacción durante una comprobación de AFS.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/afs-rejected-blocklist/">Lista de bloqueo de AFS rechazada</a></td>
      <td><code>afs_black_list</code></td>
      <td>Se envía cuando se actualiza la lista de bloqueo de AFS.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/created-subscription/">Suscripción creada</a></td>
      <td><code>create_subscription</code></td>
      <td>Se envía cuando un usuario crea una suscripción.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/updated-subscription/">Suscripción actualizada</a></td>
      <td><code>update_subscription</code></td>
      <td>Se envía cuando se renueva o modifica una suscripción.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/canceled-subscription/">Suscripción cancelada</a></td>
      <td><code>cancel_subscription</code></td>
      <td>Se envía cuando se cancela una suscripción.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/nonrenewing-subscription/">Suscripción con renovación suspendida</a></td>
      <td><code>non_renewal_subscription</code></td>
      <td>Se envía cuando el estado es de renovación suspendida.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/add-payment-account/">Añadir cuenta de pago</a></td>
      <td><code>payment_account_add</code></td>
      <td>Se envía cuando un usuario añade o guarda una cuenta de pago.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/remove-payment-account/">Eliminar cuenta de pago</a></td>
      <td><code>payment_account_remove</code></td>
      <td>Se envía cuando un usuario elimina la cuenta de pago de las cuentas guardadas.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/user-validation-in-webshop">Validación del usuario en Web Shop</a></td>
      <td><code>-</code></td>
      <td>Se envía desde un sitio de Web Shop para comprobar si un usuario existe en el juego.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/personalized-partner-catalog">Personalización del catálogo en el lado del socio</a></td>
      <td><code>partner_side_catalog</code></td>
      <td>Se envía cuando un usuario interactúa con la tienda.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/successful-order-payment">Successful payment for order</a></td>
      <td><code>order_paid</code></td>
      <td>Se envía cuando se paga un pedido.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/order-cancellation">Order cancellation</a></td>
      <td><code>order_canceled</code></td>
      <td>Se envía cuando se cancela un pedido.</td>
    </tr>
    <tr>
      <td><a href="https://developers.xsolla.com/es/webhooks/operation/dispute">Dispute</a></td>
      <td><code>dispute</code></td>
      <td>Se envía cuando se abre una nueva disputa.</td>
    </tr>
</tbody>
</table>


Version: 1.0

## Servers

```
https://api.xsolla.com/merchant/v2
```

## Download OpenAPI description

[Webhooks](https://xsolla.redocly.app/_bundle/@l10n/es/webhooks/index.yaml)

## Validación del usuario

### Búsqueda del usuario

 - [POST user-search](https://xsolla.redocly.app/es/webhooks/user-validation/user-search.md): Public User ID es un parámetro que identifica al usuario de forma exclusiva y que este conoce, a diferencia de User ID (Public User ID puede ser correo electrónico, nombre de usuario, etc). Xsolla envía un webhook con el tipo user_search cuando se realiza una compra fuera de la tienda de juegos (p. ej., a través de quioscos de efectivo/cajeros automáticos).

### Validación del usuario

 - [POST user-validation](https://xsolla.redocly.app/es/webhooks/user-validation/user-validation.md): Xsolla envía un webhook con el tipo user_validation a la dirección URL del 
webhook para verificar que un usuario esté registrado en el juego. La solicitud 
se envía varias veces como parte del proceso de pago:

* cuando un usuario elige un método de pago en la interfaz de pago
* cuando un usuario introduce datos en el formulario de pago, p. ej., los datos 
  de la tarjeta bancaria o el código postal al pagar a través de PayPal
* cuando un usuario hace clic en Pagar ahora para proceder al pago
* cuando finalice el proceso de pago y el estado de la transacción cambie a done

La solicitud se envía al pagar con cualquier método de pago.

Al guardar la URL del webhook en Cuenta del editor, puede dar permisos para 
recibir información detallada en los webhooks. Para ello, active las opciones 
correspondientes en Cuenta del editor en Project 
settings &gt; Webhooks &gt; Advanced settings.


Nota
Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Conmutador
        Descripción
    


    
        Enviar solamente los parámetros de usuario necesarios sin datos confidenciales
        Solamente la siguiente información sobre el usuario se transmite en el webhook:IDpaís
    
    
        Enviar parámetros personalizados
        La información sobre los parámetros de token personalizados se transmite en el webhook.

### Validación de usuarios en Web Shop

 - [POST user-validation-in-webshop](https://xsolla.redocly.app/es/webhooks/user-validation/user-validation-in-webshop.md): Xsolla envía un webhook desde un sitio de Web Shop para comprobar si un usuario existe en el juego. El webhook se envió desde la siguiente dirección IP: "34.102.38.178".
ObservaciónEl webhook se utiliza solamente para la 
validación de usuarios en Web Shop. Consulte estas instrucciones  para obtener más información sobre cómo configurar este webhook en Site Builder.

## Payments

### Añadir cuenta de pago

 - [POST add-payment-account](https://xsolla.redocly.app/es/webhooks/payments/add-payment-account.md): Xsolla envía un webhook con el tipo de payment_account_add a la URL del webhook cada vez que un usuario añade una cuenta de pago o guarda una cuenta de pago al comprar algo dentro del juego. Para recibir este webhook, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

### Reembolso parcial

 - [POST partial-refund](https://xsolla.redocly.app/es/webhooks/payments/partial-refund.md): Cuando se realiza un reembolso parcial, Xsolla envía los detalles de la 
transacción cancelada en un webhook con el tipo de partial_refund a la URL 
del webhook. Obtenga más información sobre el proceso de reembolso parcial en 
estas instrucciones.

Al guardar la URL del webhook en Cuenta del editor, puede dar permisos para 
recibir información detallada en los webhooks. Para ello, active la siguiente 
opción en Cuenta del editor en Project 
settings &gt; Webhooks &gt; Advanced settings.


Nota
Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Conmutador
        Descripción
    


    
        Mostrar información sobre las transacciones mediante los métodos de pago guardados
        La información se transmite en los siguientes parámetros personalizados del webhook:saved_payment_method:0: no se utilizó el método de pago guardado1: el método de pago se guardó al realizar el pago actual2: se utiliza el método de pago guardado previamentepayment_type:1: pago único2: pago periódico
    



Códigos de reembolso:


    
    
        Código
        Motivo
        Descripción
    
    
    
    
        1
        Cancellation by the user request / the game request
        Cancelación iniciada desde Cuenta del editor.
    
    
        3
        Integration error
        Problemas con la integración entre Xsolla y el juego.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        5
        Test payment
        Transacción de prueba seguida de cancelación.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        7
        Fraud notification from PS
        El pago fue rechazado porque el sistema de pago detectó un posible fraude.Recomendación: Agregue al usuario a la lista de bloqueo.
    
    
        9
        Cancellation by the user request
        El usuario no quedó satisfecho con el juego o con la compra por cualquier motivo.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        10
        Cancellation by the PS request
        Cancelación solicitada por el juego.Recomendación: no añada el usuario a la lista de bloqueo.

### Pago

 - [POST payment](https://xsolla.redocly.app/es/webhooks/payments/payment.md): Cuando un usuario finaliza el proceso de pago, Xsolla envía los datos del pago 
en un webhook con el tipo payment a la URL del webhook.

Los códigos de respuesta esperados se describen en la sección Responses, 
pero también puede usar otros códigos de respuesta:


    
    
        Código de respuesta
        Descripción
    
    
    
    
        200, 201, 204
        Una respuesta correcta.
    
    
        4xx
        Se ha producido un error. Por ejemplo, si no se ha encontrado el usuario especificado o se ha transmitido una firma que no es válida.
    
    
        5xx
        Un error temporal del servidor. Cuando se recibe esta respuesta, Xsolla automáticamente volverá a intentar enviar el webhook, aumentando progresivamente el intervalo entre intentos hasta que su agente de escucha confirme la recepción. El número máximo de reintentos es de 12 en un periodo de 48 horas.
    
    


Cuando guarde la URL del webhook en Cuenta del 
editor, también podrá configurar la recepción de información adicional en 
webhooks.


Nota
Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en su proyecto en Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Conmutador
        Descripción
    


    
        Mostrar información sobre la cuenta de pago guardada
        La información sobre el método de pago guardado se transmite en el objeto personalizado payment_account.
    
    
        Mostrar información sobre las transacciones mediante los métodos de pago guardados
        La información se transmite en los siguientes parámetros personalizados del webhook:saved_payment_method:0: no se utilizó el método de pago guardado1: el método de pago se guardó al realizar el pago actual2: se utiliza el método de pago guardado previamentepayment_type:1: pago único2: pago periódico
    
    
        Añadir objeto del pedido al webhook
        La información sobre el pedido se transmite en el objeto order del webhook Pago.
    
    
        Enviar solamente los parámetros de usuario necesarios sin datos confidenciales
        Solamente la siguiente información sobre el usuario se transmite en el webhook:IDpaís
    
    
        Mostrar número de BIC y sufijo de la tarjeta
        La siguiente información sobre el número de tarjeta bancaria se transmite en el webhook:los 6 primeros dígitos del parámetro card_binlos 4 últimos dígitos del card_suffix
    
    
        Mostrar marca de tarjeta
        La marca de la tarjeta empleada para realizar el pago. Por ejemplo, Mastercard o Visa.
    
    
        Mostrar la retención fiscal del país y las comisiones de adquisición de usuarios.
        Los objetos payment_details.​country_wht y payment_details.​user_acquisition_fee se transmitirán en el webhook. Esta opción está activada por defecto.
    
    
        Enviar información de 3DS.
        El objeto cards que contiene datos sobre la verificación 3-D Secure se transmitirá en el webhook.
    




Aviso
Los campos que se envían en un webhook dependen de:los parámetros establecidos en la configuración avanzada de Cuenta del editorla configuración personalizada establecida en el lado de XsollaSi tiene alguna pregunta, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

### Pago rechazado

 - [POST payment-declined](https://xsolla.redocly.app/es/webhooks/payments/payment-declined.md): Si una transacción es rechazada por un sistema de pago, Xsolla envía los 
detalles de la transacción en un webhook del tipo ps_declined a la URL 
configurada de su webhook. El webhook se envía durante la fase de autorización 
o de procesamiento del pago. En este caso, el webhook 
payment\ order_paid no se envía.

Razones habituales del rechazo por parte de los sistemas de pago:

* Se produjo un error en la autorización de la tarjeta (por ejemplo, el sistema 
  de pago no pudo finalizar el proceso de autorización debido a un error técnico 
  o a la falta de respuesta del banco) o la transacción fue rechazada (por 
  ejemplo, el banco respondió pero denegó la transacción por fondos insuficientes 
  o porque los datos de la tarjeta no eran válidos).
* Se produjo un error en la verificación 3-D Secure, no se ha realizado o se 
  agotó el tiempo de confirmación del usuario.
* El procesador o el banco adquirente no está disponible temporalmente o devuelve 
  un rechazo definitivo debido a un error irreversible, como una cuenta cerrada o 
  un número de tarjeta no válido. Volver a intentarlo sin solucionar el problema 
  de fondo no resultará en una transacción satisfactoria.

No debe confundirse con:

* Rechazos por el sistema antifraude, que se notifican mediante el webhook 
  afs_reject.
* Reembolsos y reembolsos parciales tras un pago realizado con éxito, que se 
  notifican mediante los webhooks 
  refund y 
  partial_refund.


Observación
Para recibir el webhook ps_declined, contacte con su gestor de éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

### Reembolso

 - [POST refund](https://xsolla.redocly.app/es/webhooks/payments/refund.md): Cuando se cancela un pago, Xsolla envía los detalles de la transacción 
cancelada en un webhook con el tipo refund a la URL del webhook.

El mecanismo de reintento del webhook depende de quién haya iniciado el 
reembolso:
* Si el reembolso se inició desde su lado, el webhook no se volverá a enviar. El 
  pago se reembolsará al usuario independientemente de la respuesta al webhook.
* Si el reembolso lo inició un tercero (por ejemplo, un sistema de pagos o el 
  equipo de atención al cliente de Xsolla) y, en respuesta a un webhook, se 
  devolvió un código de estado 5xx, el webhook se reenvía a intervalos cada vez 
  mayores. El número máximo de reintentos es de 12 en un plazo de 48 horas desde 
  el primer intento.

Para obtener información detallada sobre el proceso de reembolso, consulte las 
instrucciones.


Aviso
El pago se reembolsará al usuario si se cumplen las siguientes condiciones:El reembolso lo inició Xsolla.En respuesta a un webhook, se devolvió un código de estado 4xx, o no se recibió ninguna respuesta tras todos los intentos, o se devolvió un código de estado 5xx.


Cuando guarde la URL del webhook en Cuenta del 
editor, también podrá configurar la recepción de información adicional en 
webhooks.


Nota
Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en su proyecto en Settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Conmutador
        Descripción
    


    
        Mostrar información sobre las transacciones mediante los métodos de pago guardados
        La información se transmite en los siguientes parámetros personalizados del webhook:saved_payment_method:0: no se utilizó el método de pago guardado1: el método de pago se guardó al realizar el pago actual2: se utiliza el método de pago guardado previamentepayment_type:1: pago único2: pago periódico
    
    
        Mostrar información sobre el motivo del reembolso.
        Información detallada sobre los motivos del reembolso.
    



Códigos de reembolso:


    
    
        Código
        Motivo
        Descripción
    
    
    
    
        1
        Cancellation by the user request / the game request
        Cancelación iniciada desde Cuenta del editor.
    
    
        2
        Chargeback
        Contracargo de transacción solicitado.
    
    
        3
        Integration error
        Problemas con la integración entre Xsolla y el juego.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        4
        Potential fraud – AFS reject
        La transacción ha sido rechazada porque el sistema antifraude de Xsolla ha detectado un posible fraude.
    
    
        5
        Test payment
        Transacción de prueba seguida de cancelación.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        6
        User invoice expired
        Factura vencida (se usa para el modelo de pospago).
    
    
        7
        Fraud notification from PS
        El pago fue rechazado porque el sistema de pago detectó un posible fraude.Recomendación: Agregue al usuario a la lista de bloqueo.
    
    
        8
        Cancellation by the PS request
        Cancelación solicitada por el sistema de pago.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        9
        Cancellation by the user request
        El usuario no quedó satisfecho con el juego o con la compra por cualquier motivo.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        10
        Cancellation by the PS request
        Cancelación solicitada por el juego.Recomendación: no añada el usuario a la lista de bloqueo.
    
    
        11
        Account holder called to report fraud
        El titular de la cuenta afirma que no hizo la transacción.Recomendación: Agregue al usuario a la lista de bloqueo.
    
    
        12
        Potential fraud – friendly fraud
        El titular legítimo de la tarjeta ha impugnado la transacción.
    
    
        13
        Duplicate
        Transacción duplicada para la misma factura.
    
    
        21
        Potential fraud – BIN attack
        Tarjetas robadas de uno o varios números de identificación bancaria (NIB) en un mismo lote. Un indicador clave es una oleada de intentos que comparten un rango de números de NIB en un intervalo de tiempo breve, a menudo con números de tarjeta enumerados.
    
    
        22
        Potential fraud – friendly fraud
        Tarjeta robada empleada para comprar artículos comercializables con el fin de revenderlos.
    
    
        23
        Potential fraud – low-scale card fraud
        Tarjetas robadas de uno o varios números NIB. No es tan generalizado ni tan coordinado como el ataque de NIB (código de reembolso 21).
    
    
        24
        Potential fraud – regional price abuse
        Uso indebido de los precios regionales o de la reventa. Los usuarios se aprovechaban de los precios regionales —normalmente falseando su ubicación o el método de pago— para adquirir artículos a bajo precio y revenderlos en mercados con precios más elevados.
    
    
        25
        Potential fraud – partner or PS exploit
        Robo de credenciales y apropiación de cuentas: uso indebido de una cuenta o integración en el lado de un socio o del sistema de pago, en lugar del uso indebido directo de una tarjeta.
    
    
        26
        Potential fraud – not definable
        Se ha confirmado el fraude, pero no hay pruebas suficientes para determinar el tipo exacto de ataque.
    
    
        27
        Fraud notification from PS – linked transactions
        La propia transacción no se especificaba en el informe de fraude del sistema de pago, pero está relacionada, p. ej., a través de una tarjeta o un dispositivo compartido, con transacciones que fueron reembolsadas por motivos de fraude.

### Eliminar cuenta de pago

 - [POST remove-payment-account](https://xsolla.redocly.app/es/webhooks/payments/remove-payment-account.md): Cuando un usuario elimina la cuenta de pago de las cuentas guardadas, Xsolla envía un webhook con el tipo payment_account_remove a la URL del webhook. Para recibir este webhook, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

## Webhooks combinados

### Cancelación del pedido (con los detalles del pago y la transacción)

 - [POST order-cancellation](https://xsolla.redocly.app/es/webhooks/combined-webhooks/order-cancellation.md): Xsolla envía el webhook order_canceled a la URL especificada 
cuando el pago es cancelado por el usuario, socio o de forma automática. El 
webhook contiene información sobre los artículos devueltos, los datos de pago y 
los detalles del pedido cancelado.

El webhook no se envía si el pago no se realiza correctamente, por ejemplo:
* se abrió la interfaz de pago, pero el usuario no pagó el pedido
* se abrió la interfaz de pago, pero hubo errores durante el pago

El tiempo de procesamiento recomendado del webhook es de menos de 3 segundos.

### Pago del pedido realizado correctamente (con detalles del pago y de la transacción)

 - [POST successful-order-payment](https://xsolla.redocly.app/es/webhooks/combined-webhooks/successful-order-payment.md): Xsolla envía el webhook order_paid a la URL especificada cuando el 
usuario paga el pedido.

El webhook order_paid contiene información sobre los artículos 
comprados, los datos de pago y los detalles de la transacción.

El webhook order_paid no se envía si el pago no se realiza 
correctamente, por ejemplo:
* se abrió el formulario de pago, pero el usuario no pagó el pedido
* se abrió el formulario de pago, pero hubo errores durante el pago

Se recomienda que el tiempo de procesamiento del webhook 
order_paid sea inferior a 3 segundos.


Aviso
Los campos que se envían en un webhook dependen de los siguientes parámetros de configuración:los que haya establecido en Cuenta del editor en Project settings &gt; Webhooks &gt; Advanced settings los establecidos en el lado de XsollaSi tiene alguna duda, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.


Las respuestas esperadas se describen en la sección Responses. Puede 
utilizar otros códigos de respuesta. Dependiendo del código de respuesta y de 
la conexión de la función de reembolso automático de pagos, la lógica de 
procesamiento del webhook por parte de Xsolla es la siguiente:


    
    
        Código de respuesta
        El reembolso automático de pagos está desactivado (por defecto)
        El reembolso automático de pagos está activado
    
    
    
    
        400, 401, 402, 403, 404, 409, 422, 415
        Ninguna acción
        Reembolso automático al usuario
    
    
        200, 201, 204
        Ninguna acción
        Ninguna acción
    
    
        Diferente código o ninguna respuesta al webhook
        Se envían varios webhooks en un intervalo de tiempo especificado: 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 envían varios webhooks en un intervalo especificado: 2 intentos con un intervalo de 5 minutos, 7 intentos con un intervalo de 15 minutos, 10 intentos con un intervalo de 60 minutos. Si se envían todos los webhooks pero no se recibe una respuesta satisfactoria, se emite un reembolso automático al usuario.
    
    


Para conectar la función de reembolso automático, contacte con sus gestores de 
éxito del cliente o escriba a csm@xsolla.com.

## Webhooks independientes

### Cancelación del pedido (sin los detalles del pago y la transacción)

 - [POST order-cancellation-separate](https://xsolla.redocly.app/es/webhooks/separate-webhooks/order-cancellation-separate.md): Xsolla envía el webhook order_canceled a la URL especificada 
cuando el pago ha sido cancelado por el usuario, el socio o automáticamente. El 
webhook contiene información sobre los artículos devueltos y los detalles del 
pedido cancelado.

El webhook no se envía si el pago no se ha realizado correctamente, por ejemplo:
* se abrió la interfaz de pago, pero el usuario no pagó el pedido
* se abrió la interfaz de pago, pero hubo errores durante el pago

El tiempo de procesamiento recomendado del webhook es de menos de 3 segundos.

### Pago del pedido realizado correctamente (sin los detalles del pago ni de la transacción)

 - [POST successful-order-payment-separate](https://xsolla.redocly.app/es/webhooks/separate-webhooks/successful-order-payment-separate.md): Xsolla envía el webhook order_paid a la URL especificada cuando se 
cumplen las siguientes condiciones:
1. El usuario pagó correctamente el pedido.
2. Xsolla recibió una respuesta sobre el procesamiento correcto del webhook 
   payment.

El webhook order_paid contiene información sobre los artículos 
comprados y los datos de la transacción.

El webhook order_paid no se envía si:
* El pago no se realizó correctamente, por ejemplo:
  * se abrió el formulario de pago, pero el usuario no pagó el pedido
  * se abrió el formulario de pago, pero hubo errores durante el pago
* No se ha recibido la respuesta sobre el procesamiento correcto del webhook 
  payment.

Se recomienda que el tiempo de procesamiento del webhook 
order_paid sea inferior a 3 segundos.

Las respuestas esperadas se describen en la sección Responses. Puede 
utilizar otros códigos de respuesta. Dependiendo del código de respuesta y de 
la conexión de la función de reembolso automático de pagos, la lógica de 
procesamiento del webhook por parte de Xsolla es la siguiente:


    
    
        Código de respuesta
        El reembolso automático de pagos está desactivado (por defecto)
        El reembolso automático de pagos está activado
    
    
    
    
        400, 401, 402, 403, 404, 409, 422, 415
        Ninguna acción
        Reembolso automático al usuario
    
    
        200, 201, 204
        Ninguna acción
        Ninguna acción
    
    
        Diferente código o ninguna respuesta al webhook
        Se envían varios webhooks en un intervalo de tiempo especificado: 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 envían varios webhooks en un intervalo especificado: 2 intentos con un intervalo de 5 minutos, 7 intentos con un intervalo de 15 minutos, 10 intentos con un intervalo de 60 minutos. Si se envían todos los webhooks pero no se recibe una respuesta satisfactoria, se emite un reembolso automático al usuario.
    
    


Para conectar la función de reembolso automático, contacte con sus gestores de 
éxito del cliente o escriba a csm@xsolla.com.

## Webhook de personalización

### Personalización del catálogo en el lado del socio

 - [POST personalized-partner-catalog](https://xsolla.redocly.app/es/webhooks/personalization/personalized-partner-catalog.md): Xsolla enviará un webhook partner_side_catalog que contenga los 
parámetros del usuario y del proyecto a la URL del webhook cuando un usuario 
interactúe con la tienda.

Devuelve una lista de item_id o de SKU de artículos que están 
disponibles para el usuario como respuesta. En este caso, también puede incluir 
información de que un usuario concreto puede comprar un determinado producto un 
número especificado de veces. Esta función le permite controlar el número y el 
tipo de productos que el usuario puede añadir a la cesta y comprar.



Aviso
Al procesar el webhook, tenga en cuenta las siguientes limitaciones:El webhook debe procesarse en menos de 3 segundos. Si el procesamiento tarda más, las llamadas API obtener lista de artículos virtuales, crear token de pago y crear pedido devolverán un error.El tamaño de la respuesta del webhook no debe superar los 64 KB. Las respuestas que superen este límite no se procesarán: el usuario verá un catálogo vacío y no podrá comprar artículos. Para cambiar el tamaño máximo de la respuesta, contacte con su gestor de éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

## Anti-fraud

### Actualización de la lista de bloqueo antifraude

 - [POST afs-rejected-blocklist](https://xsolla.redocly.app/es/webhooks/anti-fraud/afs-rejected-blocklist.md): Cuando se actualiza la lista de bloqueo del sistema antifraude (agregar o eliminar un parámetro), Xsolla envía un webhook con el tipo de afs_black_list a la URL del webhook. La adición del parámetro se realiza automáticamente en el lado de Xsolla o previa solicitud. La eliminación de un parámetro solo puede realizarse previa solicitud. Para recibir este webhook, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

### Transacción rechazada por el sistema Anti-fraud

 - [POST afs-rejected-transaction](https://xsolla.redocly.app/es/webhooks/anti-fraud/afs-rejected-transaction.md): Cuando se rechaza una transacción durante una comprobación del sistema 
Antifraude, Xsolla envía los detalles de la transacción en el webhook con el 
tipo de afs_reject a la URL del webhook. Para recibir este webhook, contacte 
con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

Al guardar la URL del webhook en Cuenta del editor, puede dar permisos para 
recibir información detallada en los webhooks. Para ello, active la siguiente 
opción en Cuenta del editor en Project 
settings &gt; Webhooks &gt; Advanced settings.


Nota
Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en Project settings &gt; Webhooks &gt; Testing &gt; Payments &gt; Advanced settings.




    
        Conmutador
        Descripción
    


    
        Mostrar información sobre las transacciones mediante los métodos de pago guardados
        La información se transmite en los siguientes parámetros personalizados del webhook:saved_payment_method:0: no se utilizó el método de pago guardado1: el método de pago se guardó al realizar el pago actual2: se utiliza el método de pago guardado previamentepayment_type:1: pago único2: pago periódico

### Disputa

 - [POST dispute](https://xsolla.redocly.app/es/webhooks/anti-fraud/dispute.md): Cuando se abre una nueva disputa o una disputa cambia de estado, Xsolla envía un webhook con el tipo dispute a la URL del webhook. Para recibir este webhook, contacte con su gestor de éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

## Suscripciones

### Suscripción cancelada

 - [POST canceled-subscription](https://xsolla.redocly.app/es/webhooks/subscriptions/canceled-subscription.md): Cuando se cancela una suscripción, Xsolla envía un webhook con el tipo de cancel_subscription a la URL del webhook.

### Suscripción creada

 - [POST created-subscription](https://xsolla.redocly.app/es/webhooks/subscriptions/created-subscription.md): Cuando un usuario crea una suscripción, Xsolla envía un webhook con el tipo de create_subscription a la URL del webhook.

### Suscripción con renovación suspendida

 - [POST nonrenewing-subscription](https://xsolla.redocly.app/es/webhooks/subscriptions/nonrenewing-subscription.md): Cuando el estado de una suscripción se establece como "con renovación suspendida", Xsolla envía un webhook con el tipo non_renewal_subscription a la URL del webhook. Para recibir este webhook, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

### Suscripción actualizada

 - [POST updated-subscription](https://xsolla.redocly.app/es/webhooks/subscriptions/updated-subscription.md): Si algunos parámetros de la suscripción (plan_id, date_next_charge) fueran modificados, y en el caso de cada renovación de suscripción, Xsolla envía un webhook con el tipo update_subscription a la URL del webhook.