Xsolla-logo
  • Documentación
  • Crear cuenta

Successful payment for order (with payment and transaction details)Webhook POST

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.

Las respuestas esperadas se describen en la sección Respuestas. 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.

Request
Request Body schema: application/json
notification_type
required
string

Tipo de notificación.

required
Array of version = 1 (object) or version = 2 (object)

Lista de artículos adquiridos por el usuario.

The set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: is_free, is_bonus, and is_bundle_content. To switch the version, pass its number in the version parameter in the Update information about webhook settings API call.

Array
One of:
sku
required
string

ID único del artículo. Para los artículos con el tipo game_key, se utiliza un valor con el formato sku_drm.

type
required
string

Tipo de artículos. Puede tener los siguientes valores: virtual_good, virtual_currency, game_key o bundle. Para los artículos del tipo bundle, incluidos los paquetes de monedas virtuales, la matriz de artículos mostrará:

  • parámetros del lote o paquete de monedas virtuales
  • artículos incluidos en el lote o monedas incluidas en el paquete
Enum: "virtual_good" "virtual_currency" "game_key" "bundle"
quantity
required
integer

Cantidad de artículos.

amount
required
string

Coste total de los artículos en función de su cantidad.

required
Array of objects

Promociones aplicadas. Si no se ha aplicado ninguna promoción, se transmite una matriz vacía en el parámetro.

Array
amount_with_discount
string

Coste total de los artículos con descuento.

amount_without_discount
string

Coste total de los artículos sin descuento.

sequence
integer

Pedido de aplicación de promociones.

is_pre_order
required
boolean

Si es true, el artículo se reserva (prepedido).

custom_attributes
object

Un objeto JSON que contiene los atributos y valores del artículo.

required
object

Información sobre el pedido.

id
required
integer

Identificador único del pedido del usuario en el lado de Xsolla.

mode
required
string

Modo de pago. default se utiliza para pagos reales; sandbox para pagos de prueba.

Enum: "default" "sandbox"
currency_type
required
string

Tipo de moneda de pago. Para realizar un pedido gratuito, se especifica el valor unknown.

Enum: Description
real

para moneda real

unknown

para un pedido gratuito

virtual

para moneda virtual

currency
required
string

Moneda del pedido. La moneda virtual utiliza el código de artículo (SKU) y la moneda real usa un código de tres letras según la ISO 4217.

amount
required
string

El coste total de una cesta en función de la moneda elegida.

status
required
string

Estado del pedido.

platform
required
string or null

Plataforma de pago. Para pagos a través de Xsolla se utiliza el valor xsolla. Para otros pagos, se utiliza el valor correspondiente al nombre de la plataforma de publicación de juegos.

Enum: "xsolla" "playstation_network" "xbox_live" "pc_standalone" "nintendo_shop" "google_play" "app_store_ios" "android_standalone" "ios_standalone" "android_other" "ios_other" "pc_other"
comment
required
string or null

Comentario del usuario sobre el pedido.

invoice_id
required
string or null

ID de factura de pagos en moneda real. Los pagos en moneda virtual o los artículos gratuitos tienen un valor de null.

required
Array of objects

Promociones aplicadas. Si no se ha aplicado ninguna promoción, se transmite una matriz vacía en el parámetro.

Array
amount_with_discount
string

Coste total de los artículos con descuento.

amount_without_discount
string

Coste total de los artículos sin descuento.

sequence
integer

Pedido de aplicación de promociones.

Array of objects

Cupones aplicados. Si no se aplica el cupón, la matriz no devuelve.

Array
code
string

El código de un cupón aplicado.

external_id
string

ID externo.

Array of objects

Códigos promocionales aplicados. Si no se aplica el código promocional, la matriz no devuelve.

Array
code
string

El código de un código promocional aplicado.

external_id
string

ID externo.

required
object

Información del usuario.

external_id
required
string

ID de usuario.

email
required
string

Dirección de correo electrónico del usuario.

object

Datos de la transacción y del pago.

notification_type
required
string

Tipo de notificación.

required
object

Datos de la transacción (objeto).

agreement
integer

ID del acuerdo.

dry_run
integer

Transacción de prueba. El parámetro tiene el valor 1 si es una transacción de prueba, o no se envía si la transacción es real.

external_id
string

ID externo de la transacción. Consulte FAQs para obtener información detallada.

id
integer

ID de la transacción.

payment_date
string

Fecha del pago.

payment_method
integer

ID del método de pago.

payment_method_name
string

Nombre del método de pago.

payment_method_order_id
string

ID de pago en el sistema de pago.

required
object

Datos del pago (objeto).

object

Retención fiscal aplicada en determinados países debido a transacciones transfronterizas (objeto).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

percent
number <float>

Tipo de retención fiscal del país, %.

object

Retención fiscal directa.

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

percent
number <float>

Tipo de retención fiscal directa.

object

Importe pagado por el usuario (objeto).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Comisión del sistema de pago.

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Importe cargado en el sistema de pago.

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Datos del desembolso (objeto).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

payout_currency_rate
string

Tipo de cambio entre las monedas de pago y de desembolso.

object

Objeto con datos sobre costes de repatriación, que son impuestos a Xsolla por terceros.

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Impuesto sobre las ventas (objeto; solo en EE. UU. y Canadá).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

percent
number <float>

Tipo impositivo sobre las ventas.

object

Importe total de los costes de adquisición del usuario deducidos por las compras realizadas mediante redes de afiliación e influencers (objeto).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

percent
number <float>

Tasa del coste de adquisición del usuario, %.

object

Datos sobre el IVA (objeto; solo en la UE).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

percent
number <float>

Tipo de IVA.

object

Importe cargado en el saldo de Xsolla.

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Comisión de Xsolla (objeto).

amount
number <float>

Importe.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Datos de la compra (objeto).

required
object

Precio total de la compra (objeto).

amount
number <float>

Importe total del pago.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

object

Detalles del cupón (objeto; si se utilizó un cupón al crear la suscripción).

campaign_code
string

Código de campaña.

coupon_code
string

Código de cupón.

object

Datos del regalo (objeto).

giver_id
string

ID del obsequiador.

hide_giver_from_receiver
string

Si se oculta la identidad del obsequiador al destinatario.

message
string

Mensaje del obsequiador.

receiver_email
string

Correo electrónico del destinatario del regalo.

receiver_id
string

ID del destinatario del regalo.

Array of objects

Promociones aplicadas a esta transacción.

Array
id
integer

ID de promoción.

technical_name
string

Nombre técnico de la promoción.

object

Datos de la suscripción (objeto).

amount
number <float>

Precio en moneda real.

currency
string

Moneda. Código de moneda de tres letras de conformidad con la norma ISO 4217.

date_create
string

Fecha de creación de la suscripción. Fecha y hora de conformidad con la norma ISO 8601.

date_next_charge
string

Próxima fecha de facturación. Fecha y hora de conformidad con la norma ISO 8601.

plan_id
string

ID del plan (externo si el plan se creó usando una API).

product_id
string

ID del producto (si se envía en el token de acceso).

subscription_id
integer

ID de suscripción en la base de datos de Xsolla.

tags
Array of strings

Etiquetas del plan.

object

Configuración del proyecto personalizada (objeto).

merchant_id
integer

ID de vendedor.

project_id
integer

ID del proyecto. Encontrará este parámetro en su cuenta Publisher junto al nombre del proyecto.

custom_parameters
object

Información adicional.

Responses
200

Devuelve para indicar un procesamiento realizado correctamente.

400

Devuelve en caso de error en la información proporcionada (p. ej., falta un parámetro obligatorio, autorización fallida, etc.).

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "order_paid",
    "items": [
      {
        "sku": "com.xsolla.item_1",
        "type": "virtual_good",
        "is_pre_order": false,
        "quantity": 3,
        "amount": "1000",
        "promotions": [
          {
            "amount_without_discount": "6000",
            "amount_with_discount": "5000",
            "sequence": 1
          },
          {
            "amount_without_discount": "5000",
            "amount_with_discount": "4000",
            "sequence": 2
          }
        ],
        "custom_attributes":
          {
            "purchased": 0,
            "attr": "value"
          }
      },
      {
        "sku": "com.xsolla.item_new_1",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": []
      },
      {
        "sku": "com.xsolla.gold_1",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 1500,
        "amount": "[null]",
        "promotions": []
      }
    ],
    "order": {
      "id": 1,
      "mode": "default",
      "currency_type": "virtual",
      "currency": "sku_currency",
      "amount": "2000",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": "1",
      "promotions": [
        {
          "amount_without_discount": "4000",
          "amount_with_discount": "2000",
          "sequence": 1
        }
      ],
      "promocodes": [
        {
          "code": "promocode_some_code",
          "external_id": "promocode_sku"
        }
      ],
      "coupons": [
        {
          "code": "WINTER2021",
          "external_id": "coupon_sku"
        }
      ]
    },
    "user": {
      "external_id": "id_xsolla_login_1",
      "email": "gc_user@xsolla.com"
    },
    "billing": {
      "notification_type": "payment",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "purchase": {
          "subscription": {
              "plan_id": "b5dac9c8",
              "subscription_id": "10",
              "product_id": "Demo Product",
              "date_create": "2014-09-22T19:25:25+04:00",
              "date_next_charge": "2014-10-22T19:25:25+04:00",
              "currency": "USD",
              "amount": 9.99
          },
          "total": {
              "currency": "USD",
              "amount": 200
          },
          "promotions": [{
              "technical_name": "Demo Promotion",
              "id": 853
          }],
          "coupon": {
              "coupon_code": "ICvj45S4FUOyy",
              "campaign_code": "1507"
          },
      "transaction": {
          "id": 1,
          "external_id": 1,
          "payment_date": "2014-09-24T20:38:16+04:00",
          "payment_method": 1,
          "payment_method_name": "PayPal",
          "payment_method_order_id": 1234567890123456789,
          "dry_run": 1,
          "agreement": 1
      },
      "payment_details": {
          "payment": {
              "currency": "USD",
              "amount": 230
          },
          "vat": {
              "currency": "USD",
              "amount": 0,
              "percent": 20
          },
          "sales_tax": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "direct_wht": {
              "currency": "USD",
              "amount": 0,
              "percent": 0
          },
          "payout_currency_rate": "1",
          "payout": {
              "currency": "USD",
              "amount": 200
          },
          "country_wht": {
              "currency": "USD",
              "amount": 2,
              "percent": 10
          },
          "user_acquisition_fee": {
              "currency": "USD",
              "amount": 2,
              "percent": 1
          },
          "xsolla_fee": {
              "currency": "USD",
              "amount": 10
          },
          "payment_method_fee": {
              "currency": "USD",
              "amount": 20
          },
          "repatriation_commission": {
              "currency": "USD",
              "amount": 10
          }
      },
      "custom_parameters": {
          "parameter1": "value1",
          "parameter2": "value2"
          }
      }
   }
}'
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.