{ "openapi": "3.1.0", "info": { "description": "# Overview\n\nWebhooks allow you to receive instant notifications of configured events that happen on Xsolla’s side. You can use webhooks to automate back-end and supplementary functions of your application.\n\nExamples of events that you can be notified about:\n\n- payments, including purchases of virtual currency and items\n- recurring payments and actions with subscriptions\n- refunds\n\nWhen a configured event occurs, Xsolla notifies your system about it via webhooks. For example, you can do the following after receiving a webhook:\n\n- add to a user’s balance\n- unlock new items for a user\n- start subscription service\n- block user after fraud detection\n\nBelow is an example of how a payment processing webhook works:\n\n![Payment processing webhook](https://cdn.xsolla.net/developers/current/images/api_docs/webhooks-general.svg)\n\n# Set up server side\n\nThe following settings have to be applied for webhooks to work correctly:\n\n- Listen to webhooks at the following IP addresses: `185.30.20.0/24`, `185.30.21.0/24`, `185.30.23.0/24`.\n- Application database must not contain two successful transactions with the same ID.\n\n
\n

Notice

\n

If your listener receives a webhook with an existing transaction ID, it must return the previous result for that transaction. It is not recommended to charge the user twice or create duplicate records in the database.

\n
\n\n- A created [signature](https://developers.xsolla.com/webhooks/overview/#section/Sign-requests) has to match the one passed in the HTTP header.\n- In case of an error, return [code 400](https://developers.xsolla.com/webhooks/overview/#section/Errors) (e.g., when a required parameter is missing or a recharge has failed). For temporary errors with your servers, use code 500.\n\n
\n

Note

\n

Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing.

\n
\n\nAs internet connections are not always 100% reliable, webhooks may be lost or delayed. To address this issue, Xsolla resends failed webhooks until your listener receives them. Webhook resends are sent within 12 hours after the previous one until your listener confirms receiving. The maximum number of retries is 12.\n\n
\n

Note

\n

Although connection problems may result in lost, delayed, or duplicate webhooks, the most common cause is incorrect logic on the listener side.

\n
\n\n# Sign requests\n\nDigital signatures enable secure data transmission. To generate a signature:\n\n1. Concatenate the request’s JSON body with your project’s secret key.\n2. Apply SHA-1 hashing to the resulting string.\n\n```\nPOST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 165\nauthorization: Signature 52eac2713985e212351610d008e7e14fae46f902\n{\n \"notification_type\":\"user_validation\",\n \"user\":{\n \"ip\":\"127.0.0.1\",\n \"phone\":\"18777976552\",\n \"email\":\"email@example.com\",\n \"id\":1234567,\n \"name\":\"Xsolla User\",\n \"country\":\"US\"\n }\n}\n```\n\n```\ncurl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \\\n-d '{\n \"notification_type\":\n \"user_validation\",\n \"user\":\n {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": 1234567,\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n }\n }'\n```\n\n# Errors\n\nError codes for HTTP code 400:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
CodeMessage
INVALID_USERInvalid user
INVALID_PARAMETERInvalid parameter
INVALID_SIGNATUREInvalid signature
INCORRECT_AMOUNTIncorrect amount
INCORRECT_INVOICEIncorrect invoice
\n\n```\nHTTP/1.1 400 Bad Request\n{\n \"error\":{\n \"code\":\"INVALID_USER\",\n \"message\":\"Invalid user\"\n }\n}\n```\n", "title": "Webhooks", "version": "1.0" }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "tags": [ { "name": "webhooks", "x-displayName": "Webhooks" } ], "webhooks": { "payment": { "post": { "summary": "Payment", "description": "Sent whenever a user completes a payment. Includes payment details.", "operationId": "legacy-payment", "requestBody": { "content": { "application/json": { "schema": { "required": [ "notification_type", "transaction", "payment_details" ], "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "ip": { "$ref": "#/components/schemas/user.ip" }, "phone": { "$ref": "#/components/schemas/user.phone" }, "email": { "$ref": "#/components/schemas/user.email" }, "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "country": { "$ref": "#/components/schemas/user.country" }, "zip": { "$ref": "#/components/schemas/user.zip" } } }, "purchase": { "type": "object", "description": "Purchase details (object).", "required": [ "total" ], "properties": { "virtual_currency": { "deprecated": true, "type": "object", "description": "Virtual currency to purchase (object).", "properties": { "name": { "deprecated": true, "type": "string", "description": "Virtual currency name." }, "sku": { "deprecated": true, "type": "string", "description": "Virtual currency package SKU (if set for the virtual currency package)." }, "quantity": { "deprecated": true, "type": "number", "format": "float", "description": "Quantity." }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } }, "checkout": { "type": "object", "description": "Checkout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Purchase amount." } } }, "subscription": { "type": "object", "description": "Subscription details (object).", "properties": { "plan_id": { "$ref": "#/components/schemas/subscription.plan_id" }, "subscription_id": { "$ref": "#/components/schemas/subscription.subscription_id" }, "product_id": { "type": "string", "description": "Product ID (if sent in the access token)." }, "tags": { "$ref": "#/components/schemas/subscription.tags" }, "date_create": { "$ref": "#/components/schemas/subscription.date_create" }, "date_next_charge": { "type": "string", "description": "Next billing date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "$ref": "#/components/schemas/amount-float" } } }, "virtual_items": { "deprecated": true, "type": "object", "description": "Virtual items in purchase (object).", "properties": { "items": { "deprecated": true, "type": "array", "items": { "type": "object", "deprecated": true, "properties": { "sku": { "deprecated": true, "type": "string", "description": "Item ID." }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Item quantity." } } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Purchase amount." } } }, "pin_codes": { "deprecated": true, "type": "object", "description": "Game keys (array).", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "drm": { "deprecated": true, "type": "string", "description": "DRM platform used to distribute the game. Make sure that you have configured the required DRM platforms in your Publisher Account.", "enum": [ "steam", "playstation", "xbox", "uplay", "origin", "drmfree", "gog", "epicgames", "nintendo_eshop", "discord_game_store", "oculus" ] }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Price." }, "upgrade": { "deprecated": true, "type": "object", "description": "Object with upgrade data.", "properties": { "digital_content_from": { "deprecated": true, "type": "object", "description": "Object with data on the package, from which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "digital_content_to": { "deprecated": true, "type": "object", "description": "Object with data on the package, to which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } } } }, "gift": { "type": "object", "description": "Gift details (object).", "properties": { "giver_id": { "type": "string", "description": "Giver ID." }, "receiver_id": { "type": "string", "description": "Gift recipient ID." }, "receiver_email": { "type": "string", "description": "Gift recipient email." }, "message": { "type": "string", "description": "Message from the giver." }, "hide_giver_from_receiver": { "type": "string", "description": "Whether to hide the giver identity from the recipient." } } }, "total": { "type": "object", "description": "Total price of purchase (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Total payment amount." } } }, "promotions": { "type": "array", "description": "Promotions applied to this transaction.", "items": { "type": "object", "properties": { "technical_name": { "type": "string", "description": "Technical name of the promotion." }, "id": { "type": "integer", "description": "Promotion ID." } } } }, "coupon": { "type": "object", "description": "Coupon details (object; if a coupon was used when creating the subscription).", "properties": { "coupon_code": { "type": "string", "description": "Coupon code." }, "campaign_code": { "type": "string", "description": "Campaign code." } } }, "order": { "type": "object", "description": "Object that contains information about an order. This information is not passed in the webhook by default. To enable this function, contact your Account Manager or email to am@xsolla.com.", "properties": { "id": { "type": "integer", "description": "Order ID." }, "lineitems": { "type": "object", "description": "Object that contains information about an item.", "properties": { "sku": { "type": "string", "description": "Item SKU." }, "quantity": { "type": "integer", "description": "Item quantity." }, "price": { "type": "object", "description": "Object that contains information about an item price.", "properties": { "currency": { "type": "string", "description": "Currency of the item price." }, "amount": { "type": "number", "format": "float", "description": "Total price of the item in the selected currency." } } } } } } } } }, "transaction": { "type": "object", "description": "Transaction details (object).", "properties": { "id": { "type": "integer", "description": "Transaction ID." }, "external_id": { "type": "string", "description": "Transaction external ID." }, "payment_date": { "type": "string", "description": "Date of payment." }, "payment_method": { "type": "integer", "description": "Payment method ID." }, "payment_method_name": { "type": "string", "description": "Payment method name." }, "payment_method_order_id": { "type": "string", "description": "Payment ID in the payment system." }, "dry_run": { "type": "integer", "description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real." }, "agreement": { "type": "integer", "description": "Agreement ID." } } }, "payment_details": { "type": "object", "description": "Payment details (object).", "properties": { "payment": { "type": "object", "description": "Amount paid by the user (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_sum": { "type": "object", "description": "Amount debited from the payment system.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "xsolla_balance_sum": { "type": "object", "description": "Amount debited from Xsolla balance.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payout": { "type": "object", "description": "Payout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "vat": { "type": "object", "description": "VAT details (object; EU only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "VAT rate." } } }, "payout_currency_rate": { "type": "string", "description": "Exchange rate between payment and payout currencies." }, "xsolla_fee": { "type": "object", "description": "Xsolla fee (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_fee": { "type": "object", "description": "Payment system fee.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "sales_tax": { "type": "object", "description": "Sales tax (object; USA and Canada only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Sales tax rate." } } }, "direct_wht": { "type": "object", "description": "Direct withholding tax.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Direct withholding tax rate." } } }, "repatriation_commission": { "type": "object", "description": "Object with data on repatriation costs, imposed on Xsolla by third parties.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } } } }, "custom_parameters": { "type": "object", "description": "Your custom parameters." } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400-payment" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"payment\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"sku\": \"com.xsolla.package1\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2014-10-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"promotions\": [{\n \"technical_name\": \"Demo Promotion\",\n \"id\": \"853\"\n }],\n \"coupon\": {\n \"coupon_code\": \"ICvj45S4FUOyy\",\n \"campaign_code\": \"1507\"\n },\n \"order\": {\n \"id\": 1234\n \"lineitems\": [\n {\n \"sku\": \"com.xsolla.item_1\",\n \"quantity\": 1,\n \"price\": {\n \"currency\": \"EUR\",\n \"amount\": 6.5\n }\n }\n ]\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"payment_date\": \"2014-09-24T20:38:16+04:00\",\n \"payment_method\": 1,\n \"payment_method_name\": \"PayPal\",\n \"payment_method_order_id\": 1234567890123456789,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"payment_details\": {\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": 230\n },\n \"vat\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 20\n },\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"payout_currency_rate\": 1,\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": 10\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": 20\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n },\n \"custom_parameters\": {\n \"parameter1\": \"value1\",\n \"parameter2\": \"value2\"\n }\n}'\n" }, { "lang": "PHP", "label": "PHP", "source": " 'payment',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'purchase' => array(\n 'virtual_currency' => array(\n 'name' => 'Coins',\n 'quantity' => 100,\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'total' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n )\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_date' => '2014-09-23T19:25:25+04:00',\n 'payment_method' => 1380,\n 'payment_method_name' => 'PayPal'\n 'payment_method_order_id' => 1234567890123456789,\n 'dry_run' => 1\n ),\n 'payment_details' => array(\n 'payment' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'vat' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'sales_tax' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'direct_wht' => array(\n 'currency' => 'USD',\n 'amount' => 70\n ),\n 'payout_currency_rate' => 1,\n 'payout' => array(\n 'currency' => 'USD',\n 'amount' => 9.49\n ),\n 'xsolla_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.19\n ),\n 'payment_method_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.31\n ),\n 'repatriation_commission' => array(\n 'currency' => 'USD',\n 'amount' => 0.2\n )\n )\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1721\nauthorization: Signature 34553d151e656110c656696c919f9a10e05de542\n\n{\n \"notification_type\": \"payment\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\":{\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"sku\": \"com.xsolla.package1\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"product_id\": \"Demo Product\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"date_next_charge\": \"2014-10-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"promotions\": [{\n \"technical_name\": \"Demo Promotion\",\n \"id\": \"853\"\n }],\n \"coupon\": {\n \"coupon_code\": \"ICvj45S4FUOyy\",\n \"campaign_code\": \"1507\"\n },\n \"order\": {\n \"id\": 1234\n \"lineitems\": [\n {\n \"sku\": \"com.xsolla.item_1\",\n \"quantity\": 1,\n \"price\": {\n \"currency\": \"EUR\",\n \"amount\": 6.5\n }\n }\n ]\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"payment_date\": \"2014-09-24T20:38:16+04:00\",\n \"payment_method\": 1,\n \"payment_method_name\": \"PayPal\"\n \"payment_method_order_id\": 1234567890123456789,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"payment_details\": {\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": 230\n },\n \"vat\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 20\n },\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0,\n \"percent\": 0\n },\n \"payout_currency_rate\": 1,\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": 200\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": 10\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": 20\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n },\n \"custom_parameters\": {\n \"parameter1\": \"value1\",\n \"parameter2\": \"value2\"\n }\n}\n" } ] } }, "refund": { "post": { "summary": "Refund", "description": "When a payment is canceled, Xsolla sends details of the canceled transaction in a webhook with the `refund` type to the webhook URL.\n\nThe webhook retry mechanism depends on who initiated the refund:\n* If the refund was initiated on your side, the webhook isn’t resent. The payment is refunded to the user regardless of the response to a webhook.\n* If the refund was initiated by a third party — e.g., a payment system or Xsolla Customer Support team — and in response to a webhook, a `5xx` status code was returned, the webhook is resent at increasing intervals. The maximum number of retries is 12 within 48 hours from the first attempt.\n\nFor detailed information about the refund process, refer to the [instructions](/doc/pay-station/features/refund/).\n\n
\n

Notice

\n

The payment will still be refunded to the user if all of the following conditions are met:

\n
\n\nWhen you save the webhook URL in Publisher Account, you can also set up receiving additional information in webhooks.\n\n
\n

Note

\n

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

\n
\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
ToggleDescription
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
\n\nRefund codes:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
CodeReasonDescription
1Cancellation by the user request / the game requestCancellation initiated from Publisher Account.
2ChargebackTransaction chargeback requested.
3Integration errorIssues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist.
4Potential fraudFraud suspected.
Recommendation: Add the user to blocklist.
5Test paymentTest transaction followed by cancellation.
Recommendation: Do not add the user to blocklist.
6User invoice expiredInvoice overdue (used for postpaid model).
7Fraud notification from PSPayment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist.
8Cancellation by the PS requestCancellation requested by payment system.
Recommendation: Do not add the user to blocklist.
9Cancellation by the user requestThe user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist.
10Cancellation by the game requestCancellation requested by the game.
Recommendation: Do not add the user to blocklist.
11Account holder called to report fraudThe account owner states that they didn’t make the transaction.
12Friendly fraudFriendly fraud reported.
13DuplicateDuplicate transaction for the same invoice.
\n", "operationId": "legacy-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "notification_type", "transaction", "payment_details" ], "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "ip": { "$ref": "#/components/schemas/user.ip" }, "phone": { "$ref": "#/components/schemas/user.phone" }, "email": { "$ref": "#/components/schemas/user.email" }, "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "country": { "$ref": "#/components/schemas/user.country" }, "zip": { "$ref": "#/components/schemas/user.zip" } } }, "purchase": { "type": "object", "description": "Purchase details (object).", "required": [ "total" ], "properties": { "virtual_currency": { "type": "object", "deprecated": true, "description": "Virtual currency to purchase (object).", "properties": { "name": { "deprecated": true, "type": "string", "description": "Virtual currency name." }, "quantity": { "deprecated": true, "type": "number", "format": "float", "description": "Quantity." }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } }, "checkout": { "type": "object", "description": "Checkout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Purchase amount." } } }, "subscription": { "type": "object", "description": "Subscription details (object).", "properties": { "plan_id": { "$ref": "#/components/schemas/subscription.plan_id" }, "subscription_id": { "$ref": "#/components/schemas/subscription.subscription_id" }, "tags": { "$ref": "#/components/schemas/subscription.tags" }, "date_create": { "$ref": "#/components/schemas/subscription.date_create" }, "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "$ref": "#/components/schemas/amount-float" } } }, "virtual_items": { "type": "object", "deprecated": true, "description": "Virtual items in purchase (object).", "properties": { "items": { "deprecated": true, "type": "array", "items": { "type": "object", "properties": { "sku": { "deprecated": true, "type": "string", "description": "Item ID." }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Item quantity." } } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Purchase amount." } } }, "pin_codes": { "type": "object", "deprecated": true, "description": "Game keys (array).", "properties": { "upgrade": { "type": "object", "description": "Object with upgrade data.", "properties": { "digital_content_from": { "type": "object", "deprecated": true, "description": "Object with data on the package, from which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "digital_content_to": { "type": "object", "deprecated": true, "description": "Object with data on the package, to which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } } } }, "total": { "type": "object", "description": "Total price of purchase (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Total payment amount." } } } } }, "transaction": { "type": "object", "description": "Transaction details (object).", "properties": { "id": { "type": "integer", "description": "Transaction ID." }, "external_id": { "type": "string", "description": "Transaction external ID." }, "payment_method_order_id": { "type": "string", "description": "Payment ID in the payment system." }, "dry_run": { "type": "integer", "description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real." }, "agreement": { "type": "integer", "description": "Agreement ID." } } }, "refund_details": { "type": "object", "description": "Refund details (object).", "properties": { "code": { "type": "integer", "description": "Code ID." }, "reason": { "type": "string", "description": "Refund reason." }, "author": { "type": "string", "description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Refund initiatorField value
Game (via API).API
Publisher Account user (automatic refund).User email
Publisher Account user (with assistance from Xsolla customer support).support@xsolla.com
Xsolla (with assistance from Xsolla customer support).support@xsolla.com
\n" } } }, "payment_details": { "type": "object", "description": "Payment details (object).", "properties": { "payment": { "type": "object", "description": "Amount paid by the user (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_sum": { "type": "object", "description": "Amount debited from the payment system.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "xsolla_balance_sum": { "type": "object", "description": "Amount debited from Xsolla balance.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payout": { "type": "object", "description": "Payout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "vat": { "type": "object", "description": "VAT details (object; EU only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "VAT rate." } } }, "payout_currency_rate": { "type": "string", "description": "Exchange rate between payment and payout currencies." }, "xsolla_fee": { "type": "object", "description": "Xsolla fee (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_fee": { "type": "object", "description": "Payment system fee.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "sales_tax": { "type": "object", "description": "Sales tax (object; USA and Canada only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Sales tax rate." } } }, "direct_wht": { "type": "object", "description": "Direct withholding tax.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Direct withholding tax rate." } } }, "repatriation_commission": { "type": "object", "description": "Object with data on repatriation costs, imposed on Xsolla by third parties.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } } } }, "custom_parameters": { "type": "object", "description": "Your custom parameters." } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\":{\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n}'\n" }, { "lang": "PHP", "label": "PHP", "source": " 'refund',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'purchase' => array(\n 'virtual_currency' => array(\n 'name' => 'Coins',\n 'quantity' => 100,\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'total' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n )\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_date' => '2014-09-23T19:25:25+04:00',\n 'payment_method' => 1380,\n 'dry_run' => 1\n ),\n 'refund_details' => array(\n 'code' => 4,\n 'reason' => 'Potential fraud'\n ),\n 'payment_details' => array(\n 'payment' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'vat' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'sales_tax' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'direct_wht' => array(\n 'currency' => 'USD',\n 'amount' => 70\n ),\n 'payout_currency_rate' => 1,\n 'payout' => array(\n 'currency' => 'USD',\n 'amount' => 9.49\n ),\n 'xsolla_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.19\n ),\n 'payment_method_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.31\n ),\n 'repatriation_commission' => array(\n 'currency' => 'USD',\n 'amount' => 0.2\n )\n )\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1220\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"subscription\": {\n \"plan_id\": \"b5dac9c8\",\n \"subscription_id\": \"10\",\n \"date_create\": \"2014-09-22T19:25:25+04:00\",\n \"currency\": \"USD\",\n \"amount\": 9.99\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1\n },\n \"refund_details\": {\n \"code\": 4,\n \"reason\": \"Potential fraud\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n}\n" } ] } }, "partial-refund": { "post": { "summary": "Partial refund", "description": "When a partial refund is made, Xsolla sends details of the canceled transaction in a webhook with the `partial_refund` type to the webhook URL. Learn more about the partial refund process in these [instructions](/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow).\n\nWhen you save the webhook URL in Publisher Account, you can give permissions to receive detailed information in webhooks. To do that, set the following toggle to active in Publisher Account in the Project settings > Webhooks > Advanced settings section.\n\n
\n

Note

\n

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.

\n
\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
ToggleDescription
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
\n\nRefund codes:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
CodeReasonDescription
1Cancellation by the user request / the game requestCancellation initiated from Publisher Account.
3Integration errorIssues in integration between Xsolla and the game.
Recommendation: Do not add the user to blocklist.
5Test paymentTest transaction followed by cancellation.
Recommendation: Do not add the user to blocklist.
7Fraud notification from PSPayment refused by payment system. Potential fraud detected by PS.
Recommendation: Add the user to blocklist.
9Cancellation by the user requestThe user was not satisfied with the game or the purchase for any reason.
Recommendation: Do not add the user to blocklist.
10Cancellation by the game requestCancellation requested by the game.
Recommendation: Do not add the user to blocklist.
\n", "operationId": "legacy-partial-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "notification_type", "transaction", "payment_details" ], "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "ip": { "$ref": "#/components/schemas/user.ip" }, "phone": { "$ref": "#/components/schemas/user.phone" }, "email": { "$ref": "#/components/schemas/user.email" }, "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "country": { "$ref": "#/components/schemas/user.country" }, "zip": { "$ref": "#/components/schemas/user.zip" } } }, "purchase": { "type": "object", "description": "Purchase details (object).", "required": [ "total" ], "properties": { "virtual_currency": { "type": "object", "deprecated": true, "description": "Virtual currency to purchase (object).", "properties": { "name": { "deprecated": true, "type": "string", "description": "Virtual currency name." }, "quantity": { "deprecated": true, "type": "number", "format": "float", "description": "Quantity." }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } }, "checkout": { "type": "object", "description": "Checkout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Purchase amount." } } }, "virtual_items": { "type": "object", "deprecated": true, "description": "Virtual items in purchase (object).", "properties": { "items": { "deprecated": true, "type": "array", "items": { "type": "object", "properties": { "sku": { "deprecated": true, "type": "string", "description": "Item ID." }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Item quantity." } } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "type": "number", "format": "float", "description": "Purchase amount." } } }, "pin_codes": { "type": "object", "deprecated": true, "description": "Game keys (array).", "properties": { "upgrade": { "type": "object", "description": "Object with upgrade data.", "properties": { "digital_content_from": { "type": "object", "deprecated": true, "description": "Object with data on the package, from which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "digital_content_to": { "type": "object", "deprecated": true, "description": "Object with data on the package, to which the user upgraded.", "properties": { "digital_content": { "deprecated": true, "type": "string", "description": "Game SKU set in Publisher Account." }, "DRM": { "deprecated": true, "type": "string", "description": "Game DRM platform." } } }, "currency": { "deprecated": true, "$ref": "#/components/schemas/currency" }, "amount": { "deprecated": true, "$ref": "#/components/schemas/amount-float" } } } } }, "total": { "type": "object", "description": "Total price of purchase (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Partial refund payment amount." } } } } }, "transaction": { "type": "object", "description": "Transaction details (object).", "properties": { "id": { "type": "integer", "description": "Transaction ID." }, "external_id": { "type": "string", "description": "Transaction external ID." }, "dry_run": { "type": "integer", "description": "Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real." }, "agreement": { "type": "integer", "description": "Agreement ID." }, "date": { "type": "string", "description": "Date of transaction." } } }, "refund_details": { "type": "object", "description": "Refund details (object).", "properties": { "code": { "type": "integer", "description": "Code ID." }, "reason": { "type": "string", "description": "Refund reason." }, "author": { "type": "string", "description": "Refund initiator. The field value is passed according to the table:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Refund initiatorField value
Game (via API).API
Publisher Account user (automatic refund).User email
Publisher Account user (with assistance from Xsolla customer support).support@xsolla.com
Xsolla (with assistance from Xsolla customer support).support@xsolla.com
\n" }, "date": { "type": "string", "description": "Date of refund." } } }, "payment_details": { "type": "object", "description": "Payment details (object).", "properties": { "payment": { "type": "object", "description": "Amount paid by the user (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_sum": { "type": "object", "description": "Amount debited from the payment system.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "xsolla_balance_sum": { "type": "object", "description": "Amount debited from Xsolla balance.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payout": { "type": "object", "description": "Payout details (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "vat": { "type": "object", "description": "VAT details (object; EU only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "VAT rate." } } }, "payout_currency_rate": { "type": "string", "description": "Exchange rate between payment and payout currencies." }, "xsolla_fee": { "type": "object", "description": "Xsolla fee (object).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "payment_method_fee": { "type": "object", "description": "Payment system fee.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } }, "sales_tax": { "type": "object", "description": "Sales tax (object; USA and Canada only).", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Sales tax rate." } } }, "direct_wht": { "type": "object", "description": "Direct withholding tax.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." }, "percent": { "type": "number", "format": "float", "description": "Direct withholding tax rate." } } }, "repatriation_commission": { "type": "object", "description": "Object with data on repatriation costs, imposed on Xsolla by third parties.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "amount": { "type": "number", "format": "float", "description": "Amount." } } } } }, "custom_parameters": { "type": "object", "description": "Your custom parameters." } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-d '{\n \"notification_type\": \"partial_refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\":{\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1,\n \"date\": \"2022-03-01 10:53:15\"\n },\n \"refund_details\": {\n \"author\": \"email@example.com\",\n \"date\": \"2022-03-01 10:56:48\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n }\n}'\n" }, { "lang": "PHP", "label": "PHP", "source": " 'partial_refund',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'purchase' => array(\n 'virtual_currency' => array(\n 'name' => 'Coins',\n 'quantity' => 100,\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'total' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n )\n ),\n 'user' => array(\n 'ip' => '127.0.0.1',\n 'phone' => '18777976552',\n 'email' => 'email@example.com',\n 'id' => '1234567',\n 'country' => 'US'\n ),\n 'transaction' => array(\n 'id' => 87654321,\n 'payment_date' => '2014-09-23T19:25:25+04:00',\n 'payment_method' => 1380,\n 'dry_run' => 1,\n 'date' => '2022-03-31 10:53:15'\n ),\n 'refund_details' => array(\n 'author' => 'email@example.com',\n 'date' => '2022-03-01 10:56:48'\n ),\n 'payment_details' => array(\n 'payment' => array(\n 'currency' => 'USD',\n 'amount' => 9.99\n ),\n 'vat' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'sales_tax' => array(\n 'currency' => 'USD',\n 'amount' => 0\n ),\n 'direct_wht' => array(\n 'currency' => 'USD',\n 'amount' => 70\n ),\n 'payout_currency_rate' => 1,\n 'payout' => array(\n 'currency' => 'USD',\n 'amount' => 9.49\n ),\n 'xsolla_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.19\n ),\n 'payment_method_fee' => array(\n 'currency' => 'USD',\n 'amount' => 0.31\n ),\n 'repatriation_commission' => array(\n 'currency' => 'USD',\n 'amount' => 0.2\n )\n )\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 1220\nauthorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7\n\n{\n \"notification_type\": \"partial_refund\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"purchase\": {\n \"virtual_currency\": {\n \"name\": \"Coins\",\n \"quantity\": 10,\n \"currency\": \"USD\",\n \"amount\": 100\n },\n \"checkout\": {\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"virtual_items\": {\n \"items\": [\n {\n \"sku\": \"com.xsolla.item1\",\n \"amount\": 1\n }\n ],\n \"currency\": \"USD\",\n \"amount\": 50\n },\n \"total\": {\n \"currency\": \"USD\",\n \"amount\": 200\n }\n },\n \"user\": {\n \"ip\": \"127.0.0.1\",\n \"phone\": \"18777976552\",\n \"email\": \"email@example.com\",\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\",\n \"country\": \"US\"\n },\n \"transaction\": {\n \"id\": 1,\n \"external_id\": 1,\n \"dry_run\": 1,\n \"agreement\": 1,\n \"date\": \"2022-03-31 10:53:15\"\n },\n \"refund_details\": {\n \"author\": \"email@example.com\",\n \"date\": \"2022-03-31 10:56:48\"\n },\n \"payment_details\": {\n \"sales_tax\": {\n \"currency\": \"USD\",\n \"amount\": 0\n },\n \"direct_wht\": {\n \"currency\": \"USD\",\n \"amount\": 0.70\n },\n \"xsolla_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"10\"\n },\n \"payout\": {\n \"currency\": \"USD\",\n \"amount\": \"200\"\n },\n \"payment_method_fee\": {\n \"currency\": \"USD\",\n \"amount\": \"20\"\n },\n \"payment\": {\n \"currency\": \"USD\",\n \"amount\": \"230\"\n },\n \"repatriation_commission\": {\n \"currency\": \"USD\",\n \"amount\": 10\n }\n }\n}\n" } ] } }, "get-game-keys": { "post": { "summary": "Get game keys", "description": "We will be making API calls to your server to obtain game activation codes after each successful payment.", "operationId": "get-game-keys", "requestBody": { "content": { "application/json": { "schema": { "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" } } }, "pin_code": { "type": "object", "description": "Game keys details (object).", "properties": { "digital_content": { "type": "string", "description": "Game SKU." }, "DRM": { "type": "string", "description": "DRM platform used to distribute the game." } } } } } } } }, "responses": { "200": { "description": "Return the game key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pin_code": { "type": "string" } } }, "example": { "pin_code": "AAA-BBB-CCC-DDD" } } } }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"get_pincode\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\"\n },\n \"pin_code\": {\n \"digital_content\": \"Game SKU\",\n \"DRM\": \"Steam\"\n }\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " 'get_pincode',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'user' =>\n array (\n 'id' => '1234567',\n 'name' => 'Xsolla User',\n ),\n 'pin_code' =>\n array (\n 'digital_content' => 'Game SKU',\n 'DRM' => 'Steam',\n ),\n );\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"notification_type\": \"get_pincode\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"user\": {\n \"id\": \"1234567\",\n \"name\": \"Xsolla User\"\n },\n \"pin_code\": {\n \"digital_content\": \"Game SKU\",\n \"DRM\": \"Steam\"\n }\n}\n" } ] } }, "activate-key": { "post": { "summary": "Activate key", "description": "When a user activates a key, Xsolla sends a notification to your webhook URL.", "operationId": "activate-key", "requestBody": { "content": { "application/json": { "schema": { "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "key": { "type": "string", "description": "Activation key." }, "sku": { "type": "string", "description": "Unique key package ID." }, "user_id": { "$ref": "#/components/schemas/user.id" }, "activation_date": { "type": "string", "format": "datetime", "description": "Key activation date in the **YYYYMMDDHHMMSS** format per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "user_country": { "$ref": "#/components/schemas/user.country" }, "restriction": { "type": "object", "description": "Object with regional restriction cluster settings. The cluster includes a restriction type and a list of countries, servers and locales for which the game is available.", "properties": { "sku": { "type": "string", "description": "Unique cluster ID." }, "name": { "type": "string", "description": "Cluster name." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Array of restriction types." }, "countries": { "type": "array", "items": { "type": "string" }, "description": "Array of countries in the cluster." }, "servers": { "type": "array", "items": { "type": "string" }, "description": "Array of game servers." }, "locales": { "type": "array", "items": { "type": "string" }, "description": "Array of locales." } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"notification_type\": \"redeem_key\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"key\": \"wqdqwwddq9099022\",\n \"sku\": \"com.xsolla.key_123\",\n \"user_id\": \"sample_user\",\n \"activation_date\": \"2018-11-20T08:38:51+03:00\",\n \"user_country\": \"EN\",\n \"restriction\": {\n \"name\": \"cls_1\",\n \"types\": [\n \"activation\"\n ],\n \"countries\": [\n \"RU\"\n ]\n }\n}'\n" }, { "lang": "PHP", "label": "PHP", "source": " 'redeem_key',\n 'settings' => array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'key' => ‘wqdqwwddq9099022’,\n 'sku' => com.xsolla.key_123,\n 'user_id' => ‘sample_user’,\n 'activation_date' => ‘2018-11-20T08:38:51+03:00’,\n 'user_country' => ‘EN’,\n 'restriction' =>\n array(\n 'name' => ‘cls_1’,\n 'types' =>\n array(\n ‘activation’\n ),\n 'countries' =>\n array(\n ‘RU’\n ),\n ),\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your_uri HTTP/1.1\nhost: your.host\naccept: application/json\ncontent-type: application/json\ncontent-length: 165\nauthorization: Signature 52eac2713985e212351610d008e7e14fae46f902\n\n{\n \"notification_type\": \"redeem_key\",\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"key\": \"wqdqwwddq9099022\",\n \"sku\": \"com.xsolla.key_123\",\n \"user_id\": \"sample_user\",\n \"activation_date\": \"2018-11-20T08:38:51+03:00\",\n \"user_country\": \"EN\",\n \"restriction\": {\n \"name\": \"cls_1\",\n \"types\": [\n \"activation\"\n ],\n \"countries\": [\n \"RU\"\n ]\n }\n}\n" } ] } }, "user-balance-payment": { "post": { "summary": "User balance: Payment", "description": "Sent whenever a user makes a payment.", "operationId": "user-balance-payment", "requestBody": { "content": { "application/json": { "schema": { "required": [ "transaction" ], "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "operation_type": { "type": "string", "description": "Type of operation." }, "id_operation": { "type": "integer", "description": "Operation ID in Xsolla database." }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "email": { "$ref": "#/components/schemas/user.email" } } }, "virtual_currency_balance": { "type": "object", "description": "User balance data (object).", "properties": { "old_value": { "type": "string", "description": "Balance before transaction." }, "new_value": { "type": "string", "description": "Balance after transaction." }, "diff": { "type": "string", "description": "Quantity of virtual currency in the purchase." } } }, "transaction": { "type": "object", "description": "Transaction details (object).", "properties": { "id": { "type": "integer", "description": "Transaction ID." }, "date": { "type": "string", "description": "Date of transaction." } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"200\",\n \"diff\": \"200\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"transaction\": {\n \"id\": \"123456789\",\n \"date\": \"2015-05-19T15:54:40+03:00\"\n },\n \"operation_type\": \"payment\",\n \"notification_type\": \"user_balance_operation\",\n \"id_operation\": \"66989\"\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'virtual_currency_balance' => array(\n 'old_value' => '0',\n 'new_value' => '200',\n 'diff' => '200'\n ),\n 'user' => array(\n 'name' => 'Xsolla User',\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'transaction' => array(\n 'id' => '123456789',\n 'date' => '2015-05-19T15:54:40+03:00'\n ),\n 'operation_type' => 'payment',\n 'notification_type' => 'user_balance_operation',\n 'id_operation' => '66989'\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"200\",\n \"diff\": \"200\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"transaction\": {\n \"id\": \"123456789\",\n \"date\": \"2015-05-19T15:54:40+03:00\"\n },\n \"operation_type\": \"payment\",\n \"notification_type\": \"user_balance_operation\",\n \"id_operation\": \"66989\"\n}\n" } ] } }, "user-balance-purchase": { "post": { "summary": "User balance: Purchase", "description": "Sent when a user purchases something inside the game. Specifies the change in the user’s balance.", "operationId": "user-balance-purchase", "requestBody": { "content": { "application/json": { "schema": { "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "operation_type": { "type": "string", "description": "Type of operation." }, "id_operation": { "type": "integer", "description": "Operation ID in Xsolla database." }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "email": { "$ref": "#/components/schemas/user.email" } } }, "virtual_currency_balance": { "type": "object", "description": "User balance data (object).", "properties": { "old_value": { "type": "string", "description": "Balance before transaction." }, "new_value": { "type": "string", "description": "Balance after transaction." }, "diff": { "type": "string", "description": "Quantity of virtual currency in the purchase." } } }, "items_operation_type": { "type": "string", "description": "Type of operation made with virtual items." }, "items": { "type": "array", "description": "Virtual items within the purchase.", "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "Item ID." }, "amount": { "type": "integer", "description": "Item quantity." } } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"200\",\n \"diff\": \"200\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"inGamePurchase\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"add\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\"\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'virtual_currency_balance' => array(\n 'old_value' => '0',\n 'new_value' => '200',\n 'diff' => '200'\n ),\n 'user' => array(\n 'name' => 'Xsolla User',\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'operation_type' => 'inGamePurchase',\n 'notification_type' => 'user_balance_operation',\n 'items_operation_type' => 'add',\n 'items' => array(\n 'sku' => 'com.xsolla.item_1468',\n 'amount' => '2'\n ),\n 'id_operation' => '66989'\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"200\",\n \"diff\": \"200\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"inGamePurchase\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"add\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\"\n}\n" } ] } }, "user-balance-redeem-coupon": { "post": { "summary": "User balance: Redeem coupon", "description": "Sent when a user redeems a coupon to receive virtual items or virtual currency.", "operationId": "user-balance-redeem-coupon", "requestBody": { "content": { "application/json": { "schema": { "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "operation_type": { "type": "string", "description": "Type of operation." }, "id_operation": { "type": "integer", "description": "Operation ID in Xsolla database." }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "email": { "$ref": "#/components/schemas/user.email" } } }, "virtual_currency_balance": { "type": "object", "description": "User balance data (object).", "properties": { "old_value": { "type": "string", "description": "Balance before transaction." }, "new_value": { "type": "string", "description": "Balance after transaction." }, "diff": { "type": "string", "description": "Quantity of virtual currency in the purchase." } } }, "items_operation_type": { "type": "string", "description": "Type of operation made with virtual items." }, "items": { "type": "array", "description": "Virtual items within the purchase.", "items": { "type": "object" }, "properties": { "sku": { "type": "string", "description": "Item ID." }, "amount": { "type": "integer", "description": "Item quantity." } } }, "coupon": { "type": "object", "description": "Coupon details (object).", "properties": { "coupon_code": { "type": "string", "description": "Coupon code." }, "campaign_code": { "type": "string", "description": "Campaign code." } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"0\",\n \"diff\": \"0\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"coupon\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"add\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\",\n \"coupon\": {\n \"coupon_code\": \"test123\",\n \"campaign_code\": \"Xsolla Campaign\"\n }\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'virtual_currency_balance' => array(\n 'old_value' => '0',\n 'new_value' => '0',\n 'diff' => '0'\n ),\n 'user' => array(\n 'name' => 'Xsolla User',\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'operation_type' => 'coupon',\n 'notification_type' => 'user_balance_operation',\n 'items_operation_type' => 'add',\n 'items' => array(\n 'sku' => 'com.xsolla.item_1468',\n 'amount' => '2'\n ),\n 'id_operation' => '66989',\n 'coupon' => array(\n 'coupon_code' => 'test123',\n 'campaign_code' => 'Xsolla Campaign'\n )\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"0\",\n \"diff\": \"0\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"coupon\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"add\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\",\n \"coupon\": {\n \"coupon_code\": \"test123\",\n \"campaign_code\": \"Xsolla Campaign\"\n }\n}\n" } ] } }, "user-balance-manual-update": { "post": { "summary": "User balance: Manual update", "description": "Sent when a user’s balance is changed manually.", "operationId": "user-balance-manual-update", "requestBody": { "content": { "application/json": { "schema": { "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "operation_type": { "type": "string", "description": "Type of operation." }, "id_operation": { "type": "integer", "description": "Operation ID in Xsolla database." }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "email": { "$ref": "#/components/schemas/user.email" } } }, "virtual_currency_balance": { "type": "object", "description": "User balance data (object).", "properties": { "old_value": { "type": "string", "description": "Balance before transaction." }, "new_value": { "type": "string", "description": "Balance after transaction." }, "diff": { "type": "string", "description": "Quantity of virtual currency in the purchase." } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"100\",\n \"diff\": \"100\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"internal\",\n \"notification_type\": \"user_balance_operation\",\n \"id_operation\": \"67002\"\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'virtual_currency_balance' => array(\n 'old_value' => '0',\n 'new_value' => '100',\n 'diff' => '100'\n ),\n 'user' => array(\n 'name' => 'Xsolla User',\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'operation_type' => 'internal',\n 'notification_type' => 'user_balance_operation',\n 'id_operation' => '67002'\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"100\",\n \"diff\": \"100\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"operation_type\": \"internal\",\n \"notification_type\": \"user_balance_operation\",\n \"id_operation\": \"67002\"\n}\n" } ] } }, "user-balance-refund": { "post": { "summary": "User balance: Refund", "description": "Sent when a user cancels a payment. Specifies the change in the user’s balance.", "operationId": "user-balance-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "transaction" ], "properties": { "notification_type": { "$ref": "#/components/schemas/notification_type" }, "settings": { "type": "object", "description": "Custom project settings (object).", "properties": { "project_id": { "$ref": "#/components/schemas/settings.project_id" }, "merchant_id": { "$ref": "#/components/schemas/settings.merchant_id" } } }, "operation_type": { "type": "string", "description": "Type of operation." }, "id_operation": { "type": "integer", "description": "Operation ID in Xsolla database." }, "user": { "type": "object", "description": "User details (object).", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/user.id" }, "name": { "$ref": "#/components/schemas/user.name" }, "email": { "$ref": "#/components/schemas/user.email" } } }, "virtual_currency_balance": { "type": "object", "description": "User balance data (object).", "properties": { "old_value": { "type": "string", "description": "Balance before transaction." }, "new_value": { "type": "string", "description": "Balance after transaction." }, "diff": { "type": "string", "description": "Quantity of virtual currency in the purchase." } } }, "transaction": { "type": "object", "description": "Transaction details (object).", "properties": { "id": { "type": "integer", "description": "Transaction ID." }, "date": { "type": "string", "description": "Date of transaction." } } }, "items_operation_type": { "type": "string", "description": "Type of operation made with virtual items." }, "items": { "type": "array", "description": "Virtual items within the purchase.", "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "Item ID." }, "amount": { "type": "integer", "description": "Item quantity." } } } } } } } } }, "responses": { "204": { "$ref": "#/components/responses/204" }, "400": { "$ref": "#/components/responses/400" }, "500": { "$ref": "#/components/responses/500" } }, "x-codeSamples": [ { "lang": "cURL", "label": "CURL", "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'accept: application/json' \\\n-H 'content-type: application/json' \\\n-H 'authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"0\",\n \"diff\": \"0\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"transaction\": {\n \"id\": \"123456789\",\n \"date\": \"2015-05-19T15:54:40+03:00\"\n },\n \"operation_type\": \"cancellation\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"remove\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\"\n }'\n" }, { "lang": "PHP", "label": "PHP", "source": " array(\n 'project_id' => 18404,\n 'merchant_id' => 2340\n ),\n 'virtual_currency_balance' => array(\n 'old_value' => '0',\n 'new_value' => '0',\n 'diff' => '0'\n ),\n 'user' => array(\n 'name' => 'Xsolla User',\n 'id' => '1234567',\n 'email' => 'email@example.com'\n ),\n 'transaction' => array(\n 'id' => '123456789',\n 'date' => '2015-05-19T15:54:40+03:00'\n ),\n 'operation_type' => 'cancellation',\n 'notification_type' => 'user_balance_operation',\n 'items_operation_type' => 'remove',\n 'items' => array(\n 'sku' => 'com.xsolla.item_1468',\n 'amount' => '2'\n ),\n 'id_operation' => '66989'\n);\n" }, { "lang": "HTTP", "label": "HTTP", "source": "POST /your/uri HTTP/1.1\nhost: your.hostname\naccept: application/json\ncontent-type: application/json\ncontent-length: 240\nauthorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f\n\n{\n \"settings\": {\n \"project_id\": 18404,\n \"merchant_id\": 2340\n },\n \"virtual_currency_balance\": {\n \"old_value\": \"0\",\n \"new_value\": \"0\",\n \"diff\": \"0\"\n },\n \"user\": {\n \"name\": \"Xsolla User\",\n \"id\": \"1234567\",\n \"email\": \"email@example.com\"\n },\n \"transaction\": {\n \"id\": \"123456789\",\n \"date\": \"2015-05-19T15:54:40+03:00\"\n },\n \"operation_type\": \"cancellation\",\n \"notification_type\": \"user_balance_operation\",\n \"items_operation_type\": \"remove\",\n \"items\": [{\n \"sku\": \"com.xsolla.item_1468\",\n \"amount\": \"2\"\n }],\n \"id_operation\": \"66989\"\n}\n" } ] } } }, "components": { "schemas": { "notification_type": { "type": "string", "description": "Notification type." }, "settings.project_id": { "type": "integer", "description": "Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/) next to the name of the project." }, "settings.merchant_id": { "type": "integer", "description": "Merchant ID." }, "user.ip": { "type": "string", "description": "User IP." }, "user.phone": { "type": "string", "description": "User phone." }, "user.email": { "type": "string", "description": "User email." }, "user.id": { "type": "string", "description": "User ID." }, "user.name": { "type": "string", "description": "Username." }, "user.country": { "type": "string", "description": "User’s country. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code." }, "user.zip": { "type": "string", "description": "User’s ZIP or postal code." }, "currency": { "type": "string", "description": "Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)." }, "amount-float": { "type": "number", "format": "float", "description": "Price in real currency." }, "subscription.plan_id": { "type": "string", "description": "Plan ID (external if the plan was created via API)." }, "subscription.subscription_id": { "type": "integer", "description": "Subscription ID in Xsolla database." }, "subscription.tags": { "type": "array", "items": { "type": "string" }, "description": "Plan tags." }, "subscription.date_create": { "type": "string", "description": "Subscription creation date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." } }, "responses": { "204": { "description": "Return to indicate successful processing." }, "400": { "description": "Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "x-examples": { "application/json": { "INVALID_USER": { "summary": "Invalid user", "value": { "error": { "code": "INVALID_USER", "message": "Invalid user" } } }, "INVALID_PARAMETER": { "summary": "Invalid parameter", "value": { "error": { "code": "INVALID_PARAMETER", "message": "Invalid parameter" } } }, "INVALID_SIGNATURE": { "summary": "Invalid signature", "value": { "error": { "code": "INVALID_SIGNATURE", "message": "Invalid signature" } } }, "INCORRECT_AMOUNT": { "summary": "Incorrect amount", "value": { "error": { "code": "INCORRECT_AMOUNT", "message": "Incorrect amount" } } }, "INCORRECT_INVOICE": { "summary": "Incorrect invoice", "value": { "error": { "code": "INCORRECT_INVOICE", "message": "Incorrect invoice" } } } } } }, "500": { "description": "Return to indicate temporary errors with your servers." }, "400-payment": { "description": "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "x-examples": { "application/json": { "INVALID_USER": { "summary": "Invalid user", "value": { "error": { "code": "INVALID_USER", "message": "Invalid user" } } }, "INVALID_PARAMETER": { "summary": "Invalid parameter", "value": { "error": { "code": "INVALID_PARAMETER", "message": "Invalid parameter" } } }, "INVALID_SIGNATURE": { "summary": "Invalid signature", "value": { "error": { "code": "INVALID_SIGNATURE", "message": "Invalid signature" } } }, "INCORRECT_AMOUNT": { "summary": "Incorrect amount", "value": { "error": { "code": "INCORRECT_AMOUNT", "message": "Incorrect amount" } } }, "INCORRECT_INVOICE": { "summary": "Incorrect invoice", "value": { "error": { "code": "INCORRECT_INVOICE", "message": "Incorrect invoice" } } } } } } } } }