Payment

Xsolla Developers

PaymentWebhook POST

When a user completes a payment, Xsolla sends payment details in a webhook with the payment type to the webhook URL.

If a response with a 5xx code is received, Xsolla resends a webhook with an increased time interval until your listener confirms receiving. The maximum number of retries is 12.

When you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the necessary toggles to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.

Note

If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in the Project settings > Webhooks > Testing > Payments > Advanced settings section.

Toggle	Description
Show info about the saved payment account	Information about the saved payment method is passed in the `payment_account` custom object.
Show info about transactions via saved payment methods	Information is passed in the following custom parameters of the webhook: `saved_payment_method`: `0` — the saved payment method was not used `1` — the payment method was saved when making the current payment `2` — the previously saved payment method is used `payment_type`: `1` — one-time payment `2` — recurring payment
Add order object to webhook	Information about the order is passed in the `order` object of the Payment webhook.
Send only necessary user parameters without sensitive data	Only the following information about the user is passed in the webhook: ID country
Show card BIN and suffix	The following information about the bank card number is passed in the webhook: the first 6 digits in the `card_bin` parameter the last 4 digits in the `card_suffix`
Show card brand	The brand of the card used for making the payment. For example, Mastercard or Visa.

Notice

The set of fields sent in a webhook depends on:

the advanced settings configured in Publisher Account
the custom settings configured on the Xsolla side

If you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.

Request

Request Body schema: application/json

notification_type

required

string

Notification type.

required

object

Transaction details (object).

id	integer Transaction ID.
external_id	string Transaction external ID. Refer to the FAQs for detailed information.
payment_date	string Date of payment.
payment_method	integer Payment method ID.
payment_method_name	string Payment method name.
payment_method_order_id	string Payment ID in the payment system.
dry_run	integer Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
agreement	integer Agreement ID.

required

object

Payment details (object).

object

Amount paid by the user (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Amount debited from the payment system.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Amount debited from Xsolla balance.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Payout details (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

VAT details (object; EU only).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.
percent	number <float> VAT rate.

payout_currency_rate

string

Exchange rate between payment and payout currencies.

object

Withholding tax applied in specific countries due to cross-border transactions (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.
percent	number <float> Country withholding tax rate, %.

object

Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.
percent	number <float> User acquisition fee rate, %.

object

Xsolla fee (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Payment system fee.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Sales tax (object; USA and Canada only).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.
percent	number <float> Sales tax rate.

object

Direct withholding tax.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.
percent	number <float> Direct withholding tax rate.

object

Object with data on repatriation costs, imposed on Xsolla by third parties.

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Amount.

object

Custom project settings (object).

project_id	integer Project ID. You can find this parameter in your Publisher Account next to the name of the project.
merchant_id	integer Merchant ID.

object

User details (object).

id required	string User ID.
ip	string User IP.
phone	string User phone.
email	string User email.
name	string Username.
country	string User’s country. Two-letter uppercase ISO 3166-1 alpha-2 country code.
zip	string User’s ZIP or postal code.

object

Purchase details (object).

required

object

Total price of purchase (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Total payment amount.

object

Checkout details (object).

currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Purchase amount.

object

Subscription details (object).

plan_id	string Plan ID (external if the plan was created via API).
subscription_id	integer Subscription ID in Xsolla database.
product_id	string Product ID (if sent in the access token).
tags	Array of strings Plan tags.
date_create	string Subscription creation date. Date and time per ISO 8601.
date_next_charge	string Next billing date. Date and time per ISO 8601.
currency	string Currency. Three-letter currency code per ISO 4217.
amount	number <float> Price in real currency.

object

Gift details (object).

giver_id	string Giver ID.
receiver_id	string Gift recipient ID.
receiver_email	string Gift recipient email.
message	string Message from the giver.
hide_giver_from_receiver	string Whether to hide the giver identity from the recipient.

Array of objects

Promotions applied to this transaction.

Array

technical_name	string Technical name of the promotion.
id	integer Promotion ID.

object

Coupon details (object; if a coupon was used when creating the subscription).

coupon_code	string Coupon code.
campaign_code	string Campaign code.

object

Object that contains information about an order. To receive this information, set the Add order object to webhook toggle to On in Publisher Account in the Project settings > Webhooks > Advanced settings section.

integer

Order ID.

object

Object that contains information about an item.

sku

string

Item SKU.

quantity

integer

Item quantity.

object

Object that contains information about an item price.

currency	string Currency of the item price.
amount	number <float> Total price of the item in the selected currency.

custom_parameters

object

Your custom parameters.

Responses

204

Return to indicate successful processing.

400

Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.). In this case, the user’s money is debited, but the purchase fails. To make a refund, contact Xsolla customer support at support@xsolla.com.

500

Return to indicate temporary errors with your servers.

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": "INVALID_USER",
"message": "Invalid user"
}
}