Pago

Xsolla Developers

PagoWebhook POST

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.

Si se recibe una respuesta con un código 5xx, Xsolla vuelve a enviar un webhook con un intervalo incrementado hasta que su agente de escucha confirme la recepción. El número máximo de reintentos es 12.

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 > Webhooks > Advanced settings.

Nota

Si se registró en Cuenta del editor el 22 de enero de 2025 o antes, encontrará las opciones en Project settings > Webhooks > Testing > Payments > 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 guardado `1`: el método de pago se guardó al realizar el pago actual `2`: se utiliza el método de pago guardado previamente `payment_type`: `1`: pago único `2`: 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: ID paí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_bin` los 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.

Aviso

Los campos que se envían en un webhook dependen de:

los parámetros establecidos en la configuración avanzada de Cuenta del editor
la configuración personalizada establecida en el lado de Xsolla

Si tiene alguna pregunta, contacte con su gestor del éxito del cliente o envíe un correo electrónico a csm@xsolla.com.

Request

Request Body schema: application/json

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.

custom_parameters

object

Sus parámetros personalizados.

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

Datos del proceso de pago (objeto).

amount	number <float> Importe de la compra.
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.

object

Objeto que contiene información sobre un pedido. Para recibir esta información, ponga el conmutador Añadir objeto de pedido a webhook en la posición On en Cuenta del editor en la sección Project settings > Webhooks > Advanced settings.

integer

ID de pedido.

object

Objeto que contiene información sobre un artículo.

object

Objeto que contiene información sobre el precio de un artículo.

amount	number <float> Precio total del artículo en la moneda seleccionada.
currency	string Moneda del precio del artículo.

quantity

integer

Cantidad del artículo.

sku

string

Código (SKU) del artículo.

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.

object

Datos del usuario (objeto).

id required	string ID de usuario.
country	string Código de país. Dos letras mayúsculas de conformidad con la norma ISO 3166-1 alpha-2.
email	string Correo electrónico del usuario.
ip	string IP del usuario.
name	string Nombre de usuario.
phone	string Teléfono del usuario.
zip	string Código postal o ZIP del usuario.

Responses

204

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.). En este caso, se carga el importe en la cuenta del usuario, pero hay un fallo en la compra. Para hacer un reembolso, contacte con el servicio de atención al cliente de Xsolla escribiendo a support@xsolla.com.

500

Devuelve para indicar errores temporales en sus servidores.

Request samples

CURL
PHP
HTTP

curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "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
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "com.xsolla.item_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US"
    },
    "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"
    }
}'

Response samples

application/json

{"error": {"code": "INCORRECT_AMOUNT",
"message": "Incorrect amount"
}
}