Xsolla-logo

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.

You can give permissions to receive detailed information in webhooks. To do that, you can set the following toggles to On in Publisher Account in the Project settings > Webhooks > 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.
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.

id
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 -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": "test_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": {
    }
}
System statusAll services operational

Privacy Settings

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