{ "openapi": "3.0.0", "info": { "description": "# Overview\n\n* **Version:** 2.0.0\n* **Servers**:\n * `https://api.xsolla.com/api`\n\nPay Station allows partners to monetize their products by providing users with a convenient UI to pay for in-game purchases in the game store. To set up opening the payment UI, refer to these [instructions](/doc/pay-station/how-to/how-to-open-payment-ui/).\n\nThe Pay Station API provides the following groups of calls:\n- Token — includes the API call to generate a token with arbitrary user parameters for further payment processing via the payment UI.\n- [Tokenization](/doc/pay-station/features/tokenization/) — includes API calls to securely process payments without opening the payment UI or involving the user.\n- Reports — includes API calls to return data on user transactions, generate reports, and get payouts breakdown by currency.\n- Refund — includes API calls to request full and partial refunds.\n- Testing — includes the API call to test the chargeback process.\n\nYou can find detailed information about configuring the payment UI in the [Payments solution integration guide](/solutions/payments/integration-guide/integration-flow/).\n\n
\n

Note

You can also refer to the Xsolla Base API section in the Postman collection to test API calls used for integration.

\n
\n", "title": "Pay Station API", "version": "2.0" }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "tags": [ { "name": "token", "x-displayName": "Token" }, { "name": "tokenization", "x-displayName": "Tokenization" }, { "name": "reports", "x-displayName": "Reports" }, { "name": "refund", "x-displayName": "Refund" }, { "name": "testing", "x-displayName": "Testing" } ], "paths": { "/merchants/{merchant_id}/token": { "post": { "summary": "Create token", "description": "You can create a token with arbitrary user parameters. You send these\nparameters when obtaining the token and receive them back after a successful\npayment. A token can only contain parameters either described in this\ndocument or predefined by you.\n\nIf any parameter is sent in the wrong format or has the wrong type, no token\nwill be issued. You will receive a 422 HTTP code with the error description\nin the JSON body. In `extended_message` you will receive an information what\nexact parameters have been sent incorrectly.\n\nBy default, the token lifetime is 24 hours. If you want to change this value, contact your Customer Success Manager or send an email to csm@xsolla.com. The new value will be enabled for all your company’s projects created in Publisher Account.\n\n
\n

Notice

The token you obtain after calling this API method can be used only for authorizing other requests. You can use this token to open the payment UI only if you integrated the Subscriptions product.

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation4/?token={token}, where {token} is the received token.

For testing purposes, use this URL: https://sandbox-secure.xsolla.com/paystation4/?token={token}.

\n
\n\n

\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "token" ], "operationId": "create-token", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/token" } } } }, "responses": { "200": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } }, "example": { "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT" } } } }, "422": { "description": "Unprocessable Entity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "extended_message": { "type": "object", "properties": { "global_errors": { "type": "array", "items": { "type": "string" } }, "property_errors": { "type": "object", "description": "Object contains parameter names with error descriptions." } } }, "request_id": { "type": "string" } } }, "example": { "http_status_code": 422, "message": "JSON is not valid against json schema, please check documentation https://developers.xsolla.com/api/v2/getting-started/#api_token_ui", "extended_message": { "global_errors": [], "property_errors": { "purchase.checkout.amount": [ "String value found, but a number is required" ] } }, "request_id": "cd72633" } } } } } } }, "/projects/{project_id}/users/{user_id}/payment_accounts": { "get": { "summary": "Get saved accounts", "description": "Lists saved payment accounts of a given user.\n\n
\n

Note

In sandbox mode, this API call works only with test cards that have no 3-D Secure function.

\n
\n", "tags": [ "tokenization" ], "operationId": "get-saved-accounts", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/mode" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "id": 4612345, "name": "PP_saved_account", "payment_system": { "id": 24, "name": "PayPal" }, "type": "paypal" } ] } } } } } }, "/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}": { "post": { "summary": "Charge with saved account", "description": "Charges a user via a saved payment account.\n\n
\n

Note

In sandbox mode, this API call works only with test cards that have no 3-D Secure function.

\n
\n\n

\n\n
\n

Notice

For the API call to work correctly, configure a timeout of 2 minutes.

\n
\n", "tags": [ "tokenization" ], "operationId": "charge-with-saved-account", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/type-path-param" }, { "$ref": "#/components/parameters/account-id-path-param" } ], "requestBody": { "$ref": "#/components/requestBodies/charge-with-saved-account" }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "integer" } } }, "example": { "transaction_id": 123458390 } } } }, "422": { "description": "Unprocessable Entity." } } } }, "/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}": { "delete": { "summary": "Delete saved account", "description": "Deletes a saved payment account.\n\n
\n

Note

In sandbox mode, this API call works only with test cards that have no 3-D Secure function.

\n
\n\n

\n\n
\n

Note

You can call this API method in sandbox mode. To do this, pass the test payment account data in the request. Refer to the instruction for more information about sandbox mode access and testing scenarios.

\n
\n", "tags": [ "tokenization" ], "operationId": "delete-saved-account", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/type-path-param" }, { "$ref": "#/components/parameters/account-id-path-param" } ], "responses": { "204": { "description": "No Content." } } } }, "/merchants/{merchant_id}/reports/transactions/search.{format}": { "get": { "summary": "Find transactions", "description": "Returns a list of transactions based on specific search parameters. In response, you get data about all payments made in your game, even if they were not completed successfully. You can specify not only the transaction period, but also other parameters, e.g., to search for transactions made by a particular user or in a particular payment status. You can get the list in JSON or CSV format.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "find-transactions", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/datetime-from" }, { "$ref": "#/components/parameters/datetime-to" }, { "$ref": "#/components/parameters/project-id-query-param" }, { "$ref": "#/components/parameters/transaction-id" }, { "$ref": "#/components/parameters/type" }, { "$ref": "#/components/parameters/phone" }, { "$ref": "#/components/parameters/user-id-query-param" }, { "$ref": "#/components/parameters/user-name" }, { "$ref": "#/components/parameters/user-custom" }, { "$ref": "#/components/parameters/email" }, { "$ref": "#/components/parameters/external-id" }, { "$ref": "#/components/parameters/order-id" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/status" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "transaction": { "project": { "id": 123456, "name": "Example" }, "payment_method": { "id": 1, "name": "PayPal" }, "transfer_date": "2021-10-20", "id": 123456789, "refund_reason": null, "status": "done", "external_id": "example-external-id", "order_id": 1234, "create_date": "2021-10-20", "dry_run": 0, "is_refund_allowed": 0 }, "user": { "id": "example-id", "name": "Example", "custom": null, "email": "email@example.com", "phone": null, "country": "RU" }, "payment_details": { "payment": { "currency": "RUB", "amount": 7.96, "amount_from_ps": 7.96 }, "sales_tax": { "percent": 0, "amount": 0 } }, "purchase": { "virtual_currency": { "amount": 0, "name": null }, "virtual_items": null, "simple_checkout": { "amount": 7.96, "currency": "RUB" }, "pin_codes": { "amount": null, "currency": null, "content": null }, "subscription": { "name": null } }, "payment_system": { "decline_reason": null } } ] } } } } } }, "/merchants/{merchant_id}/reports/transactions/simple_search": { "get": { "summary": "Find transactions (fast search)", "description": "Gets a list of transactions based on specific search parameters within a few seconds. This is an alternative to the [Find transactions](/api/pay-station/operation/find-transactions/) API call that returns data in JSON, CSV, or XLS format.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "find-transactions-fast", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "name": "transaction_id", "in": "query", "description": "Transaction ID. Either this or `external_id` must be provided, but not both.", "schema": { "type": "integer" } }, { "name": "external_id", "in": "query", "description": "Transaction ID in the game. It is unique for each payment. Either this or `transaction_id` must be provided, but not both.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The list of transactions was successfully returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "description": "User details.", "properties": { "id": { "type": "string", "description": "User ID." }, "name": { "type": "string", "description": "User name." }, "email": { "type": "string", "description": "User email." }, "country": { "type": "string", "description": "Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." } } }, "transaction": { "type": "object", "description": "Transaction details.", "properties": { "project": { "type": "object", "properties": { "id": { "type": "integer", "description": "Project ID. Can be found in Publisher Account." }, "name": { "type": "string", "description": "Project name." } } }, "id": { "type": "integer", "description": "Transaction ID." }, "external_id": { "type": "string", "description": "Transaction ID in the game. It is unique for each user payment." }, "status": { "$ref": "#/components/schemas/status.enum" }, "payment_date": { "type": "string", "description": "Date of the payment in YY-MM-DD format." }, "refund_reason": { "type": "string", "description": "Refund reason." } } }, "payment_details": { "type": "object", "description": "Payment details.", "properties": { "payment": { "type": "object", "properties": { "amount": { "description": "Payment amount.", "type": "number", "format": "float" }, "currency": { "type": "string", "description": "Payment currency. Three-letter currency code per [ISO 4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/)." } } } } } } } }, "example": [ { "transaction": { "id": 123456, "project": { "id": 123456, "name": "Test" }, "payment_date": "2023-02-11 15:32:46", "external_id": "example_external_id_123", "status": "done" }, "user": { "id": "123456", "name": "John Smith", "email": "email@example.com", "country": "BR" }, "payment_details": { "payment": { "currency": "BRL", "amount": 7.96 } } } ] } } }, "403": { "description": "Access Denied." }, "404": { "description": "Transaction Not Found." }, "422": { "description": "Unprocessable Entity (You must pass either `transaction_id` or `external_id`)." } } } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/details": { "get": { "summary": "Get transaction", "description": "Gets full transaction info by ID.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "get-transaction", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "responses": { "200": { "description": "The transaction information was successfully returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "customer_details": { "type": "object", "properties": { "billing_address": { "type": "string" }, "bin": { "type": "string" }, "browser_language": { "type": "string" }, "country": { "type": "string" }, "ip": { "type": "string" }, "paystation_country": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "user_id": { "type": "string" }, "user_name": { "type": "string" } } }, "finance_details": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "payment_method_fee": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "payment_method_sum": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "payout": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "payout_currency_rate": { "type": "number", "format": "float" }, "repatriation_commission": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "dispute_fee": { "type": "object", "properties": { "currency": { "type": "string", "description": "Payment currency. Three-letter currency code per [ISO 4217](/doc/pay-station/references/supported-currencies/)." }, "amount": { "type": "number", "format": "float", "description": "The dispute fee amount in the payment currency." }, "date": { "type": "string", "description": "Date of the dispute opening." } } }, "sales_tax": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "direct_wht": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "vat": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "xsolla_balance_sum": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "xsolla_fee": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } } } }, "payment_details": { "type": "object", "properties": { "card_holdername": { "type": "string", "nullable": true }, "card_issuer": { "type": "string" }, "card_month": { "type": "integer" }, "card_number": { "type": "integer" }, "card_scheme": { "type": "string" }, "card_year": { "type": "integer" }, "customer_firstname": { "type": "string" }, "customer_lastname": { "type": "string" }, "enrollment": { "type": "boolean" }, "ps_account": { "type": "string" }, "zip_code": { "type": "string" } } }, "subscription_details": { "type": "object", "properties": { "is_payment_from_subscription": { "type": "boolean" }, "is_subscription_created": { "type": "boolean" } } }, "transaction_details": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "cancellation_date": { "type": "string", "nullable": true }, "country": { "type": "string" }, "currency": { "type": "string" }, "custom_parameters": { "type": "string", "nullable": true }, "foreign_invoice": { "type": "string", "nullable": true }, "gift_recipient_email": { "type": "string", "nullable": true }, "gift_recipient_id": { "type": "string", "nullable": true }, "payment_date": { "type": "string" }, "payment_method": { "type": "string" }, "payment_method_name": { "type": "string" }, "project": { "type": "integer" }, "project_name": { "type": "string" }, "purchase": { "type": "object", "properties": { "checkout": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "pin_codes": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "content": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true } } }, "total": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "virtual_currency": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "string" } } }, "virtual_items": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "content": { "type": "string" }, "currency": { "type": "string" } }, "nullable": true } } }, "refund_comment": { "type": "string", "nullable": true }, "refund_reason": { "type": "string", "nullable": true }, "status": { "type": "string" }, "user_id": { "type": "string" } } } } } }, "example": [ { "customer_details": { "billing_address": "", "bin": "", "browser_language": "", "country": "US", "ip": "209.11.22.33", "paystation_country": "", "phone": null, "timezone": "", "user_id": "user1", "user_name": "John Smith" }, "finance_details": { "payment": { "amount": 0.04, "currency": "USD" }, "payment_method_fee": { "amount": 0.01, "currency": "USD" }, "payment_method_sum": { "amount": 0.04, "currency": "USD" }, "payout": { "amount": 1.25, "currency": "RUB" }, "payout_currency_rate": 62, "repatriation_commission": { "amount": 0, "currency": "USD" }, "dispute_fee": { "currency": "USD", "amount": 70, "date": "2019-04-20 16:15:37" }, "sales_tax": { "amount": 0, "currency": "USD" }, "direct_wht": { "amount": 0, "currency": "USD" }, "vat": { "amount": 0.01, "currency": "USD" }, "xsolla_balance_sum": { "amount": 0, "currency": "USD" }, "xsolla_fee": { "amount": 0, "currency": "USD" } }, "payment_details": { "card_holdername": null, "card_issuer": "TEST BANK", "card_month": 1, "card_number": 1234123412341234, "card_scheme": "MASTERCARD", "card_year": 2020, "customer_firstname": "", "customer_lastname": "", "enrollment": false, "ps_account": "1234test4321", "zip_code": "" }, "subscription_details": { "is_payment_from_subscription": false, "is_subscription_created": true }, "transaction_details": { "amount": 0.04, "cancellation_date": null, "country": "US", "currency": "USD", "custom_parameters": null, "foreign_invoice": null, "gift_recipient_email": null, "gift_recipient_id": null, "payment_date": "2019-03-21 16:15:37", "payment_method": "1380", "payment_method_name": "Credit/Debit Cards", "project": 21092, "project_name": "Test Project", "purchase": { "checkout": { "amount": 0, "currency": "USD" }, "pin_codes": { "amount": 0, "content": null, "currency": null }, "total": { "amount": 0.03, "currency": "USD" }, "virtual_currency": { "amount": 0.03, "currency": "USD", "name": "Gold coins", "quantity": "2" }, "virtual_items": null }, "refund_comment": null, "refund_reason": null, "status": "done", "user_id": "user1" } } ] } } } } } }, "/merchants/{merchant_id}/reports/transactions/registry.{format}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v3" } ], "get": { "summary": "Get transactions", "description": "Returns the list of detailed information about successful and canceled transactions for a specified period. In response, you get information about payments, including data on fees, taxes, as well as order and user. You can get the list in JSON or CSV format. You can use this API call to perform financial reconciliation.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "get-transactions", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/datetime-from-req" }, { "$ref": "#/components/parameters/datetime-to-req" }, { "$ref": "#/components/parameters/in-transfer-currency" }, { "$ref": "#/components/parameters/show-total" }, { "$ref": "#/components/parameters/merchant-of-records" }, { "$ref": "#/components/parameters/project-id-query-param" }, { "$ref": "#/components/parameters/show-dry-run" }, { "$ref": "#/components/parameters/transfer-id" }, { "$ref": "#/components/parameters/report-id" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/limit-req" }, { "$ref": "#/components/parameters/transaction-status" } ], "responses": { "200": { "description": "The list of transactions was successfully returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "description": "User details.", "properties": { "id": { "type": "string", "description": "User ID." }, "email": { "type": "string", "description": "User email." }, "name": { "type": "string", "description": "User screen name." }, "phone": { "type": "string", "description": "User phone number.", "nullable": true }, "country": { "type": "string", "description": "Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "custom": { "type": "string", "nullable": true }, "marketplace": { "type": "string" }, "ip": { "type": "string" } } }, "user_balance": { "type": "object", "description": "User balance.", "properties": { "payment_currency": { "type": "object", "description": "Preferred payment currency.", "properties": { "deduction_amount": { "type": "number", "format": "float" }, "payout_amount_from_balance": { "type": "number", "format": "float" }, "purchase_amount_from_balance": { "type": "number", "format": "float" } } } } }, "transaction": { "type": "object", "description": "Transaction data.", "properties": { "custom_parameters": { "type": "object", "nullable": true }, "direct_account": { "type": "integer" }, "dry_run": { "type": "integer" }, "external_id": { "type": "string", "nullable": true }, "id": { "type": "integer" }, "payment_method": { "type": "object", "properties": { "class": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "project": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "refund_reason": { "type": "string", "nullable": true }, "refund_reason_comment": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "created", "processing", "done", "canceled", "error", "refunded", "partiallyRefunded", "awaitingRefund", "disputeFee" ] }, "transfer_date": { "type": "string", "format": "datetime" } } }, "purchase": { "type": "object", "description": "Purchase details.", "properties": { "friend": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "user_id": { "type": "string", "nullable": true } } }, "items_amount": { "type": "integer" }, "pin_codes": { "type": "object", "properties": { "amount": { "type": "number", "format": "float", "nullable": true }, "content": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true } } }, "purchase_amount": { "type": "number", "format": "float" }, "simple_checkout": { "type": "object", "properties": { "amount": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true } } }, "subscription": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "plan_id": { "type": "integer", "nullable": true }, "product_id": { "type": "string", "nullable": true }, "product_name": { "type": "string", "nullable": true }, "subscription_id": { "type": "integer", "nullable": true } } }, "virtual_currency": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "currency": { "type": "string" } } }, "virtual_currency_amount": { "type": "integer" }, "virtual_items": { "type": "object", "properties": { "amount": { "type": "number", "format": "float", "nullable": true }, "content": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true } } } } }, "payment_details": { "type": "object", "description": "Payment details.", "properties": { "chargebackPenalty": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" } } }, "commission_agent": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "commission_agent_fixed": { "type": "integer" }, "commission_ps": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "fixed_amount": { "type": "integer" }, "percent": { "type": "number", "format": "float" } } }, "commission_ps_from_vat": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" } } }, "commission_user": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "commission_xsolla": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "fixed_amount": { "type": "integer" }, "percent": { "type": "number", "format": "float" } } }, "cpa_network_commission": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "payment": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "amount_from_ps": { "type": "integer" }, "currency": { "type": "string" } } }, "payout": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "amount_from_ps": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "fx_rate": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "direct_wht": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "refundPenalty": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" } } }, "repatriation_costs": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "sales_tax": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" } } }, "vat": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "percent": { "type": "number", "format": "float" }, "user_amount": { "type": "integer" }, "user_percent": { "type": "integer" } } } } } } } }, "example": [ { "payment_details": { "chargebackPenalty": { "amount": 0 }, "commission_agent": { "amount": 0, "percent": 0 }, "commission_agent_fixed": 0, "commission_ps": { "amount": 0, "fixed_amount": 0, "percent": 0 }, "commission_ps_from_vat": { "amount": 0 }, "commission_user": { "amount": 0.01, "percent": 33.33 }, "commission_xsolla": { "amount": 0, "fixed_amount": 0, "percent": 5 }, "cpa_network_commission": { "amount": 0, "percent": 0 }, "payment": { "amount": 0.03, "amount_from_ps": 0, "currency": "USD" }, "payout": { "amount": 0.02, "amount_from_ps": 0, "currency": "RUB", "fx_rate": 64.1386407767, "percent": 100 }, "direct_wht": { "amount": 0, "percent": 0 }, "refundPenalty": { "amount": 0 }, "repatriation_costs": { "amount": 0, "percent": 0 }, "sales_tax": { "amount": 0, "percent": 0 }, "vat": { "amount": 0, "percent": 0, "user_amount": 0, "user_percent": 0 } }, "purchase": { "friend": { "email": null, "user_id": null }, "items_amount": 1, "pin_codes": { "amount": null, "content": null, "currency": null }, "purchase_amount": 0.02, "simple_checkout": { "amount": null, "currency": null }, "subscription": { "name": null, "plan_id": null, "product_id": null, "product_name": null, "subscription_id": null }, "virtual_currency": { "amount": 0.02, "currency": "USD" }, "virtual_currency_amount": 1, "virtual_items": { "amount": null, "content": null, "currency": null } }, "transaction": { "custom_parameters": null, "direct_account": 0, "dry_run": 0, "external_id": null, "id": 418756634, "payment_method": { "class": "Digital Payment Methods", "id": 2760, "name": "Your Balance" }, "project": { "id": 21092, "name": "Smith" }, "refund_reason": null, "refund_reason_comment": null, "status": "done", "transfer_date": "2019-02-11T13:32:00+03:00" }, "user": { "country": "US", "custom": null, "email": "email@example.com", "id": "smith123", "marketplace": "Pay Station", "name": "Tom", "phone": null, "ip": "209.11.22.33" }, "user_balance": { "payment_currency": { "deduction_amount": 0, "payout_amount_from_balance": 0.02, "purchase_amount_from_balance": 0.02 } } } ] } } } } } }, "/merchants/{merchant_id}/reports/transfers": { "get": { "summary": "Get payouts", "description": "Lists all payouts for a period.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "get-payouts", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/datetime-from" }, { "$ref": "#/components/parameters/datetime-to" }, { "$ref": "#/components/parameters/legal-entity-id" }, { "$ref": "#/components/parameters/payout-status" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "payout": { "id": 1, "date": "2014-01-03T00:00:00+04:00", "note": "12/05/2013 - 01/04/2014", "currency": "USD" }, "transfer": { "date": "2014-01-05T00:00:00+04:00", "note": "004357", "currency": "USD" }, "rate": 1, "canceled": 0 } ] } } } } } }, "/merchants/{merchant_id}/reports/transactions/summary/transfer": { "get": { "summary": "Get payouts breakdown in currency", "description": "Gets payouts breakdown in currency.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "get-payouts-breakdown", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/datetime-from" }, { "$ref": "#/components/parameters/datetime-to" }, { "$ref": "#/components/parameters/legal-entity-id" }, { "$ref": "#/components/parameters/transaction-status" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "IsoCurrency": "RUB", "PaymentsAmount": 223679.84, "SumCommissionAgent": 11329.58, "SumCommissionUserTaxes": 153.67, "SumItems": 571325.13, "SumNominalSum": 214792.98, "SumOutProject": 551096.13, "SumPayoutSum": 193316.71, "TaxesOfPayments": 171.56, "DirectTaxesOfPayments": 0.46 }, { "IsoCurrency": "USD", "PaymentsAmount": 482.58, "SumCommissionAgent": 77.51, "SumCommissionUserTaxes": 0.07, "SumItems": 243777.62, "SumNominalSum": 493.09, "SumOutProject": 241787.62, "SumPayoutSum": 462.62, "TaxesOfPayments": 0.14, "DirectTaxesOfPayments": 0.14 }, { "IsoCurrency": "EUR", "PaymentsAmount": 608.2, "SumCommissionAgent": 55.71, "SumCommissionUserTaxes": 90.94, "SumItems": 156238.62, "SumNominalSum": 607.26, "SumOutProject": 156158.62, "SumPayoutSum": 460.8, "TaxesOfPayments": 90.94, "DirectTaxesOfPayments": 0.07 } ] } } } } } }, "/merchants/{merchant_id}/reports": { "get": { "summary": "Get reports", "description": "Gets the list of financial reports over a specified period.\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "reports" ], "operationId": "get-reports", "x-server": true, "x-admin": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/datetime-from-req" }, { "$ref": "#/components/parameters/datetime-to-req" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "example": [ { "agreement_document_id": "Organization Inc_RUB", "currency": "RUB", "is_direct_payout": false, "is_draft_by_agreement": true, "month": "January", "report_id": 57613, "year": 2019 }, { "agreement_document_id": "Organization Inc_EUR", "currency": "USD", "is_direct_payout": false, "is_draft_by_agreement": true, "month": "January", "report_id": 57619, "year": 2019 } ] } } } } } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/refund": { "put": { "summary": "Request refund", "description": "Sends a refund request to return a payment to a user. Read about the [Refund\nfeature](https://developers.xsolla.com/doc/pay-station/features/refund/) to\nlearn more about the process.\n\n
\n

Note

You can call this API method in sandbox mode. To do this, pass the test payment data in the request. Refer to the instruction for more information about sandbox mode access and testing scenarios.

\n
\n\n

\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "refund" ], "operationId": "request-refund", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "maxLength": 4000, "description": "Reason for a refund." }, "email": { "type": "string", "maxLength": 100, "description": "User email." } } }, "example": { "description": "test refund request" } } } }, "responses": { "200": { "description": "OK (No error).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Can return one of the following messages:\n- No content.\n- The request for a refund has been accepted. Xsolla CS will manually complete the refund. It may take up to two business days.\n- The request for a refund has been accepted. Xsolla CS will automatically send the customer an email with alternative refund options as the user's method does not support direct refunds.\n" } } }, "example": { "message": "The request for a refund has been accepted. Xsolla CS will automatically send the customer an email with alternative refund options as the user's method does not support direct refunds." } } } }, "204": { "description": "Refund request accepted." }, "401": { "description": "Unauthorized (Access denied)." }, "404": { "description": "Transaction Not Found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Transaction ID not valid. Please check payment credentials. Otherwise, contact Xsolla support at support@xsolla.com." } } }, "example": { "message": "Transaction ID not valid. Please check payment credentials. Otherwise, contact Xsolla support at support@xsolla.com." } } } }, "422": { "description": "Unprocessable Entity (Invalid request parameters).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Can return one of the following messages:\n- We are processing the refund request. This may take up to two business days.\n- We are reaching the user for the information required for the refund. For details, contact Xsolla Support.\n- Incorrect payment status. Refund is possible only for payments with \"completed\" or \"error\" status.\n- To process this request, the customer's email address field must be filled. Please specify the customer's email address and try again.\n- Full refund is unavailable because there are successful partial refunds for this transaction.\n- Refund failed. Please contact Xsolla Support to process it manually.\n- Dispute for this invoice is already opened. Can’t make a refund yet.\n" } } }, "example": { "message": "We are processing the refund request. This may take up to two business days." } } } } } } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/partial_refund": { "put": { "summary": "Request partial refund", "description": "Sends a request for a partial refund to a user. Refer to our [documentation](https://developers.xsolla.com/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow) for detailed information about the refund process and payment methods that support partial refunds.\n\n
\n

Note

You can call this API method in sandbox mode. To do this, pass the test payment data in the request. Refer to the instruction for more information about sandbox mode access and testing scenarios.

\n
\n\n

\n\n
\n

Notice

This API call does not contain the project_id path parameter, so you need to use the API key that is valid in all the company’s projects to set up authorization.

\n
\n", "tags": [ "refund" ], "operationId": "request-partial-refund", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description", "refund_amount" ], "properties": { "description": { "type": "string", "maxLength": 4000, "description": "Reason for a refund." }, "refund_amount": { "type": "number", "format": "float", "description": "The refund amount in a purchase currency." } } }, "example": { "refund_amount": 1.5, "description": "test refund request" } } } }, "responses": { "204": { "description": "Refund request accepted" }, "403": { "description": "Do not have necessary permission" }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Transaction with specified ID does not exist. Please check payment credentials. Otherwise, contact Xsolla support at support@xsolla.com." } } }, "example": { "message": "Transaction with specified ID does not exist." } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "**Refund is not acceptable**\n\nReturns one of the following messages:\n- Partial refund is unavailable for operations with user balance.\n- Requested transaction is partial refund and cannot be canceled.\n- Partial refund is unavailable for subscription payments.\n- Refund cannot be completed due to a payment system error. Please try again later.\n- Requested partial refund amount exceeds payment amount.\n- Requested partial refund amount is less than minimum amount specified by payment system.\n- Payment amount after partial refund will be less than allowable amount specified by payment system.\n- Dispute for this invoice is already opened. Can’t make a refund yet.\n\n**Current payment method does not support partial refunds**\n\nReturns one of the following messages:\n- Current payment method does not support partial refunds.\n- Current transaction status does not allow refunds.\n- Deadline for refund is exceeded.\n- Partial refund is unavailable because discount was applied during payment creation.\n\n**Cannot execute partial refund because of wrong precision**\n\nReturns the following message:\n- Partial refund is unavailable because requested amount is specified with incorrect precision for purchase currency.\n" } } }, "example": { "message": "Partial refund is unavailable for subscription payments." } } } } } } }, "/merchants/{merchant_id}/projects/{project_id}/payments/{transaction_id}/chargeback": { "post": { "summary": "Request chargeback", "description": "Requests chargeback in the sandbox mode:\n\n- To access the sandbox mode, pass `\"mode\":\"sandbox\"` when you [get the token](https://developers.xsolla.com/api/pay-station/operation/create-token/).\n\n- Test payment has to be made in the sandbox mode in the same project that you use for testing.\n\n- Transaction status has to be **other than** `refunded`, `cancelled`.\n\n- Your role in Publisher Account has to be at least **Financial manager**. (You can find it in the **Company settings > Users** section.)\n\n- Refer to the instruction for more information about this testing scenario.\n\n
\n

Note

Refer to the documentation for more information about other testing scenarios.

\n
\n", "tags": [ "testing" ], "operationId": "request-chargeback", "x-server": true, "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/empty-body" } } } }, "responses": { "204": { "description": "No Content (No error)." }, "404": { "description": "Transaction Not Found." }, "422": { "description": "Unprocessable Entity (Invalid request parameters).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Can return one of the following messages:\n- Error processing chargeback. Try again or use another payment.\n- Payment not found. Check payment ID.\n- Payment does not belong to this project.\n- Not test payment. Chargeback is possible only for payments made in sandbox mode.\n- Incorrect payment status. Chargeback is possible only for payments with “Completed” status.\n" } } }, "example": { "message": "Not test payment. Chargeback is possible only for payments made in sandbox mode." } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "description": "Xsolla API uses basic access authentication. All requests to API must contain the `Authorization: Basic ` header, where `` is the `merchant_id:api_key` pair encoded according to the Base64 standard.\n\n Go to [Publisher Account](https://publisher.xsolla.com/) to find these parameters:
\n For more information about working with API keys, see the [API reference](https://developers.xsolla.com/api/getting-started/#api_keys_overview).", "scheme": "basic" } }, "parameters": { "merchant-id-path-param": { "name": "merchant_id", "in": "path", "required": true, "description": "Merchant ID.", "schema": { "type": "integer" } }, "project-id-path-param": { "name": "project_id", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "integer" } }, "user-id-path-param": { "name": "user_id", "in": "path", "required": true, "description": "Unique user ID in the game stored on your side. Make sure you pass the existing user ID. In case an error occurs, refer to the [answers to the FAQs](/doc/pay-station/references/faq/#faq_validation).", "schema": { "type": "string" } }, "mode": { "name": "mode", "in": "query", "required": false, "description": "Set to `sandbox` to test the payment process. Remove the parameter to make real payments.", "schema": { "type": "string" } }, "type-path-param": { "name": "type", "in": "path", "required": true, "description": "Type of payment account.\n", "schema": { "type": "string", "enum": [ "card", "amazon", "skrill", "paypal", "toss", "alipayplus_cn", "alipayplus_hk", "alipayplus_gcash", "alipayplus_dana", "alipayplus_rabbitlinepay", "alipayplus_tng", "alipayplus_boost", "alipayplus_truemoney", "alipayplus_maya", "alipayplus_kplus", "softbank_paypay", "softbank_docomo", "softbank_softbank2", "softbank_au", "softbank_ymobile", "paysafecard_eu", "paysafecard_us", "paidy", "klarna", "mercadopago", "nupay" ], "x-enumDescriptions": { "card": "Bank cards.", "amazon": "Amazon Pay.", "skrill": "Skrill Digital Wallet.", "paypal": "PayPal.", "toss": "Toss Wallet.", "alipayplus_cn": "Alipay.", "alipayplus_hk": "Alipay (Hong Kong).", "alipayplus_gcash": "GCash.", "alipayplus_dana": "DANA.", "alipayplus_rabbitlinepay": "Rabbit LINE pay.", "alipayplus_tng": "Touch 'n Go.", "alipayplus_boost": "Boost.", "alipayplus_truemoney": "TrueMoney Wallet.", "alipayplus_maya": "Maya.", "alipayplus_kplus": "K PLUS.", "softbank_paypay": "PayPay.", "softbank_docomo": "Docomo.", "softbank_softbank2": "SoftBank.", "softbank_au": "au Easy Payment.", "softbank_ymobile": "Y!mobile.", "paysafecard_eu": "Paysafecard (EU).", "paysafecard_us": "Paysafecard (US).", "paidy": "Paidy.", "klarna": "Klarna. Payment account saving is available only for US, UK, Sweden, Germany, Austria, Norway, Finland, Denmark, Netherlands.", "mercadopago": "Mercado Pago (including Mercado Pago Connect).", "nupay": "NuPay." } } }, "account-id-path-param": { "name": "account_id", "in": "path", "required": true, "description": "ID of the saved account in Xsolla database.", "schema": { "type": "integer" } }, "format": { "name": "format", "in": "path", "required": true, "description": "Data format.\n", "schema": { "type": "string", "enum": [ "json", "csv", "xls" ] } }, "datetime-from": { "name": "datetime_from", "in": "query", "required": false, "description": "Period start.", "schema": { "type": "string", "format": "datetime" } }, "datetime-to": { "name": "datetime_to", "in": "query", "required": false, "description": "Period end.", "schema": { "type": "string", "format": "datetime" } }, "project-id-query-param": { "name": "project_id", "in": "query", "required": false, "description": "Project ID.", "schema": { "type": "integer" } }, "transaction-id": { "name": "transaction_id", "in": "query", "required": false, "description": "Transaction ID.", "schema": { "type": "integer" } }, "type": { "name": "type", "in": "query", "required": false, "description": "Type of transactions shown in the search results:\n", "schema": { "type": "string", "enum": [ "all", "transferred", "canceled", "test" ], "x-enumDescriptions": { "all": "All transactions.", "transferred": "Successful transactions excluding test transactions.", "canceled": "Canceled transactions excluding test transactions.", "test": "Test transactions." } } }, "phone": { "name": "phone", "in": "query", "required": false, "description": "Phone number in international format.", "schema": { "type": "string" } }, "user-id-query-param": { "name": "user_id", "in": "query", "required": false, "description": "Unique user ID in the game stored on your side. Make sure you pass the existing user ID. In case an error occurs, refer to the [answers to the FAQs](/doc/pay-station/references/faq/#faq_validation).", "schema": { "type": "string" } }, "user-name": { "name": "user_name", "in": "query", "required": false, "description": "Username.", "schema": { "type": "string" } }, "user-custom": { "name": "user_custom", "in": "query", "required": false, "description": "Custom parameter for user identification.", "schema": { "type": "string" } }, "email": { "name": "email", "in": "query", "required": false, "description": "User email.", "schema": { "type": "string", "maxLength": 100 } }, "external-id": { "name": "external_id", "in": "query", "required": false, "description": "Transaction ID in the game. Has to be unique for each user payment.", "schema": { "type": "string" } }, "order-id": { "name": "order_id", "in": "query", "required": false, "description": "Order ID. You can use it to call the [Get order](/api/shop-builder/operation/get-order/) API method.", "schema": { "type": "integer" }, "example": 1234 }, "offset": { "name": "offset", "in": "query", "required": false, "description": "Number of the element from which the list is generated (the count starts from 0).", "schema": { "type": "integer" } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "Limit for the number of elements on the page.", "schema": { "type": "integer" } }, "status": { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/status.enum" } }, "transaction-id-path-param": { "name": "transaction_id", "in": "path", "required": true, "description": "Transaction ID.", "schema": { "type": "integer" } }, "datetime-from-req": { "name": "datetime_from", "in": "query", "required": true, "description": "Period start in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed:", "schema": { "type": "string", "format": "datetime" }, "example": "2023-02-08" }, "datetime-to-req": { "name": "datetime_to", "in": "query", "required": true, "description": "Period end in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed: The difference between `datetime_from` and `datetime_to` cannot be more than 92 days.", "schema": { "type": "string", "format": "datetime" }, "example": "2023-03-08" }, "in-transfer-currency": { "name": "in_transfer_currency", "in": "query", "required": true, "description": "Converts all financial data to the payout currency (the pay-in currency is used by default). Not required if at least one of the following parameters is passed:", "schema": { "type": "integer" } }, "show-total": { "name": "show_total", "in": "query", "description": "Whether to include the total transactions amount in the report. Available for export in CSV format only. `true` by default.", "schema": { "type": "boolean" } }, "merchant-of-records": { "name": "merchant_of_records", "in": "query", "required": false, "description": "Merchant of Record. Can be `xsolla`, `merchant`, or not specified. If `merchant`, returns transactions made via the partner’s gateways. If `xsolla`, returns transactions made not via the partner’s gateways. If not specified, returns all transactions.", "schema": { "type": "string", "nullable": true, "enum": [ "xsolla", "merchant" ], "x-enumDescriptions": { "merchant": "Returns transactions made via the partner’s gateways.", "xsolla": "Returns transactions made not via the partner’s gateways." } } }, "show-dry-run": { "name": "show_dry_run", "in": "query", "required": false, "description": "Whether to include test transactions.", "schema": { "type": "boolean" } }, "transfer-id": { "name": "transfer_id", "in": "query", "required": false, "description": "Payout ID.", "schema": { "type": "integer" } }, "report-id": { "name": "report_id", "in": "query", "required": false, "description": "Financial report ID.", "schema": { "type": "integer" } }, "limit-req": { "name": "limit", "in": "query", "required": false, "description": "Limit for the number of displayed transactions on the page. If this parameter is passed, you don’t need to pass the `datetime_from` and `datetime_to` parameters.", "schema": { "type": "integer" } }, "transaction-status": { "name": "status", "in": "query", "required": false, "description": "Transaction status.", "schema": { "type": "string", "enum": [ "done", "canceled", "error", "refunded" ] } }, "legal-entity-id": { "name": "legal_entity_id", "in": "query", "required": false, "description": "ID of the developer's legal entity.", "schema": { "type": "integer" } }, "payout-status": { "name": "status", "in": "query", "required": false, "description": "Payout status.\n", "schema": { "type": "string", "enum": [ "hold", "ready", "paid" ], "x-enumDescriptions": { "hold": "Waiting for a request to proceed.", "ready": "Payout in progress.", "paid": "Payout completed." } } } }, "schemas": { "id.user": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Unique user ID in the game stored on your side. Make sure you pass the existing user ID. In case an error occurs, refer to the [answers to the FAQs](/doc/pay-station/references/faq/#faq_validation)." } } }, "email.user": { "type": "object", "description": "The `user.email` object is an integral part of building anti-fraud models and helps increase acceptance rates. It is both Xsolla and payment systems requirement. If the parameter is not passed, the required field for entering email appears on the payment page. A user receives a purchase receipt to the email passed in the parameter or entered on the payment page.\n", "required": [ "value" ], "properties": { "value": { "type": "string", "maxLength": 100, "description": "User email. Must be valid according to the [RFC 822](https://www.w3.org/Protocols/rfc822/#z8) protocol." }, "allow_modify": { "type": "boolean", "description": "Whether a user can enter their email in the payment UI. If the `user.email.value` parameter is passed in the token, the value is `false` by default." } } }, "name.user": { "type": "object", "properties": { "value": { "type": "string", "description": "User screen name." }, "allow_modify": { "type": "boolean", "description": "Whether a user can enter their name in the payment UI. If the `user.name.value` parameter is passed in the token, the value is `false` by default." } } }, "age.user": { "type": "integer", "description": "User age." }, "phone.user": { "type": "object", "properties": { "value": { "type": "string", "description": "User phone number." } }, "nullable": true }, "country.user": { "type": "object", "properties": { "value": { "type": "string", "description": "Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)." }, "allow_modify": { "type": "boolean", "description": "Whether a user can change the country on payment UI. If `country.value` is passed in the token, the value is `false` by default." } } }, "attributes.user": { "type": "object", "description": "User attributes for filtering the item list, represented as a valid JSON set of key-value pairs." }, "steam_id.user": { "type": "object", "properties": { "value": { "type": "string", "description": "Steam ID." } } }, "tracking_id.user": { "type": "object", "properties": { "value": { "type": "string", "minLength": 32, "maxLength": 32, "description": "Unique user ID — used in marketing campaigns. Can contain digits and Latin characters." } } }, "public_id.user": { "type": "object", "properties": { "value": { "type": "string", "description": "Parameter that uniquely identifies the user and is known to the user (email, screen name, etc). Allows the user to make purchases outside the game store (e.g., via cash kiosks)." } } }, "utm.user": { "type": "object", "description": "Traffic attributes.", "properties": { "utm_source": { "type": "string", "description": "Traffic source." }, "utm_medium": { "type": "string", "description": "Traffic channel (contextual ads, media ads, email lists, etc.)." }, "utm_campaign": { "type": "string", "description": "Campaign title, transliterated or translated to English." }, "utm_term": { "type": "string", "description": "Campaign keyword. If set, statistics will be based on the keywords used for ad targeting rather than on specific search queries. In Google Analytics, the specified `utm_term` is part of the general search terms report." }, "utm_content": { "type": "string", "description": "Campaign content." } } }, "is_legal.user": { "type": "boolean", "description": "Whether the user is a legal entity." }, "legal": { "type": "object", "description": "Object with legal entity details.", "properties": { "name": { "type": "string", "description": "Full legal name." }, "address": { "type": "string", "description": "Full legal address." }, "vat_id": { "type": "string", "description": "Individual taxpayer identifier." }, "country": { "type": "string", "description": "Country of incorporation. Two-letter uppercase country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) is used." } } }, "legal.user": { "allOf": [ { "description": "Object with legal entity details. Object and all its parameters are required if `user.is_legal` is `true`." }, { "$ref": "#/components/schemas/legal" } ] }, "user": { "type": "object", "description": "User details.", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/id.user" }, "email": { "$ref": "#/components/schemas/email.user" }, "name": { "$ref": "#/components/schemas/name.user" }, "age": { "$ref": "#/components/schemas/age.user" }, "phone": { "$ref": "#/components/schemas/phone.user" }, "country": { "$ref": "#/components/schemas/country.user" }, "attributes": { "$ref": "#/components/schemas/attributes.user" }, "steam_id": { "$ref": "#/components/schemas/steam_id.user" }, "tracking_id": { "$ref": "#/components/schemas/tracking_id.user" }, "public_id": { "$ref": "#/components/schemas/public_id.user" }, "utm": { "$ref": "#/components/schemas/utm.user" }, "is_legal": { "$ref": "#/components/schemas/is_legal.user" }, "legal": { "$ref": "#/components/schemas/legal.user" } } }, "project_id": { "type": "integer", "description": "Game’s Xsolla ID. Can be found in Publisher Account." }, "external_id": { "type": "string", "description": "Transaction ID in the game. Has to be unique for each user payment. Refer to documentation for detailed information." }, "language": { "type": "string", "description": "Interface language. Two-letter lowercase [language code](https://developers.xsolla.com/doc/pay-station/features/localization/)." }, "return_url": { "type": "string", "description": "URL of the page where a user is redirected to after the payment. Refer to documentation for detailed information about configuring redirects." }, "cancel_url": { "type": "string", "description": "URL of the page the user is redirected to when they close the payment UI before completing the payment. Works only if you use the `settings.​ui.​desktop.​header` or `settings.​ui.​mobile` objects to configure the button for closing the payment UI. If the button is configured but the URL is not passed in this parameter, the URL passed in the `settings.return_url` parameter is used." }, "redirect_policy": { "type": "object", "description": "Redirect policy settings.", "properties": { "redirect_conditions": { "type": "string", "description": "Payment status for which a user is redirected to the return URL. Can be `none`, `successful`, `successful_or_canсeled`, or `any`.", "enum": [ "none", "successful", "successful_or_canceled", "any" ] }, "delay": { "type": "integer", "description": "Delay (in seconds) after which a user is automatically redirected to the return URL." }, "status_for_manual_redirection": { "type": "string", "description": "Payment status for which a button redirecting a user to the return URL is displayed. Can be `none`, `successful`, `successful_or_canсeled`, or `any`.", "enum": [ "none", "successful", "successful_or_canceled", "any" ] }, "manual_redirection_action": { "type": "string", "description": "Pay Station behavior triggered by the user clicking the close button or the **Back to the Game** button. Can be `redirect` (by default) and `postmessage`. If set to `redirect`, a user is redirected to the URL passed in the token or specified in Publisher Account. If set to `postmessage`, a user is not redirected to other pages. Clicking the close icon initiates sending the `close` event, and clicking the **Back to the Game** button — the `return` event.", "enum": [ "redirect", "postmessage" ] }, "redirect_button_caption": { "type": "string", "description": "Text on the button for manual redirection." }, "show_redirect_countdown": { "type": "boolean", "description": "Whether to display a redirect countdown timer on the payment status page. The countdown duration is determined by the value passed in the `settings.redirect_policy.delay` parameter.", "default": false } } }, "currency": { "type": "string", "description": "Preferred payment currency. Three-letter currency code per [ISO 4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/)." }, "mode.settings": { "type": "string", "description": "Set to `sandbox` to test out the payment process. In this case, use *https://sandbox-secure.xsolla.com* to access the test payment UI." }, "payment_method": { "type": "integer", "description": "Payment method ID." }, "payment_widget": { "type": "string", "description": "Payment widget. Can be `paybycash` or `giftcard`. If the parameter is set, the user is redirected to the Pay by Cash or Gift Cards widget, respectively.", "enum": [ "paybycash", "giftcard" ] }, "theme.ui": { "type": "string", "description": "Payment UI theme. Can be `63295a9a2e47fab76f7708e1` for the light theme (default) or `63295aab2e47fab76f7708e3` for the dark theme. You can also [create a custom theme](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_in_token) and pass its ID in this parameter.", "enum": [ "63295a9a2e47fab76f7708e1", "63295aab2e47fab76f7708e3" ] }, "close_button_icon": { "type": "string", "description": "The icon of the **Close** button in the payment UI.", "enum": [ "arrow", "cross" ], "x-enumDescriptions": { "arrow": "The **←** icon on the left side of the payment UI header.", "cross": "The **×** icon on the right side of the payment UI header." } }, "header.desktop": { "type": "object", "description": "Header settings.", "properties": { "is_visible": { "type": "boolean", "description": "Whether to show the header in the payment UI." }, "visible_logo": { "type": "boolean", "description": "If `true`, the logo is displayed in the header. To upload the image, open your project in [Publisher Account](https://publisher.xsolla.com/) and go to the **Pay Station > Settings** section." }, "visible_name": { "type": "boolean", "description": "Whether to show the project name in the header." }, "visible_purchase": { "type": "boolean", "description": "Whether to show the purchase description (`purchase.description.value`) in the header. `true` by default." }, "type": { "type": "string", "description": "How to show the header. Can be `compact` (hides project name and user ID) or `normal` (default).", "enum": [ "compact", "normal" ] }, "close_button": { "type": "boolean", "description": "Whether to show the payment UI close button. When the user clicks it, the payment UI is closed and the user is redirected to the URL passed in the `settings.cancel_url` parameter. If the URL is not passed in this parameter, the URL passed in the `settings.return_url` parameter is used instead.", "default": false }, "close_button_icon": { "$ref": "#/components/schemas/close_button_icon" } } }, "subscription_list.desktop": { "type": "object", "description": "Settings for the list of subscription plans.", "properties": { "description": { "type": "string", "description": "Any text to show above the list of available subscription plans in the payment UI." }, "display_local_price": { "type": "boolean", "description": "If `true`, and if the user’s local currency is different from the one set for the subscription plan, the user will be able to see both prices: one in the local and one in the basic currency.\n" } } }, "desktop.ui": { "type": "object", "description": "Interface settings for the desktop version.", "properties": { "header": { "$ref": "#/components/schemas/header.desktop" }, "subscription_list": { "$ref": "#/components/schemas/subscription_list.desktop" } } }, "header.ui": { "type": "object", "properties": { "visible_virtual_currency_balance": { "type": "boolean", "description": "Whether or not this element can be hidden on Payment UI. `true` by default." } } }, "mobile.ui": { "type": "object", "properties": { "header": { "type": "object", "properties": { "close_button": { "type": "boolean", "description": "Whether to show the payment UI close button in the mobile version. When the user clicks it, the payment UI is closed and the user is redirected to the URL passed in the `settings.cancel_url` parameter. If the URL is not passed in this parameter, the URL passed in the `settings.return_url` parameter is used instead.", "default": false }, "close_button_icon": { "$ref": "#/components/schemas/close_button_icon" } } } } }, "components": { "type": "object", "description": "Menu settings.", "properties": { "virtual_items": { "type": "object", "description": "Virtual items submenu settings.", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." }, "selected_group": { "type": "string", "description": "Group to show after opening the virtual items tab." }, "selected_item": { "type": "string", "description": "Item to show after opening the virtual items tab (item SKU)." } } }, "virtual_currency": { "type": "object", "description": "Virtual currency submenu settings.", "properties": { "custom_amount": { "type": "boolean", "description": "Whether the user can enter an arbitrary quantity of the virtual currency in the payment UI." }, "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." } } }, "subscriptions": { "type": "object", "description": "Subscription plans submenu settings.", "properties": { "order": { "type": "integer", "description": "Position of the submenu in the menu." }, "hidden": { "type": "boolean", "description": "Whether to show the submenu." } } } } }, "mode.ui": { "type": "string", "description": "Display mode of the payment UI for managing saved payment methods. Can be set to `user_account` or omitted. In this mode, the user can only change the language, add new payment methods, and remove existing ones.\n\n
\n

Note

When this parameter is passed, the redirect button is not displayed. To redirect a user after saving a payment method, configure automatic redirects.

\n
\n" }, "is_prevent_external_link_open": { "type": "boolean", "description": "Whether or not redirecting links to an external resource is disabled. `false` by default. When clicking an external link, the `external-link-open` event is sent via the `postMessage` mechanism. The address for the redirected link is passed in the `url` parameter." }, "is_payment_methods_list_mode": { "type": "boolean", "description": "Whether the list of payment methods available in the user’s country is displayed when opening the payment UI. If `false` (default), the payment method passed in the `settings.payment_method` parameter or the method selected by the [PayRank algorithm](https://developers.xsolla.com/solutions/payments/payment-ui-management/top-payment-methods-management/) is displayed." }, "is_independent_windows": { "type": "boolean", "description": "Whether to redirect users from the embedded launcher’s browser (WebView) to their default browser to make a purchase. `false` by default." }, "payment_accounts_enable": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "Specifies whether to display the pencil icon in the payment UI that goes to the payment method editing page. `true` by default." }, "order": { "type": "integer", "description": "Position of the section in the drop-down list in the payment UI. Required if `settings.ui.user_account.payment_accounts.enable` is passed.", "minimum": 1 } } }, "user_account": { "type": "object", "description": "User account details.", "properties": { "payment_accounts": { "allOf": [ { "description": "**Saved methods** section." }, { "$ref": "#/components/schemas/payment_accounts_enable" } ] } } }, "currency_format": { "type": "string", "description": "Set to `code` to display a three-letter [ISO 4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/) currency code in the payment UI. The currency symbol is displayed instead of the three-letter currency code by default." }, "is_show_close_widget_warning": { "type": "boolean", "description": "Whether to show a warning about processing the transaction when hovering over the **×** icon before closing the payment page. If `false` is passed, or the parameter is not passed, the warning is not displayed. `true` by default." }, "layout": { "type": "string", "description": "Location of the main elements of the payment UI. You can open the payment UI inside your game and/or swap the columns with information about an order and payment methods. Refer to the [customization instructions](https://developers.xsolla.com/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_layout) for detailed information.", "enum": [ "embed", "column_reverse", "embed_column_reverse" ] }, "is_three_ds_independent_windows": { "type": "boolean", "description": "Whether the 3-D Secure verification opens in a new browser window. If your setup enforces a Content Security Policy (CSP), set to `true`.", "default": false }, "is_cart_open_by_default": { "type": "boolean", "description": "The display of the list of cart items and financial details in the payment UI. If `true`, information is displayed in an extended view. If `false` (default) or the parameter is not passed, information is displayed in a collapsed view." }, "gp_quick_payment_button": { "type": "boolean", "description": "The way the Google Pay payment method is displayed. If `true`, the button for quick payment via Google Pay is displayed at the top of the payment UI, regardless of the user’s device and browser. If `false`, Google Pay is displayed in the list of payment methods according to the [PayRank](/doc/pay-station/how-to/how-to-manage-top-payment-methods/) algorithm. If the parameter is not passed, Google Pay is displayed at the top of the payment UI on any user’s devices and browsers, except Safari — on Safari, it is displayed in the list of payment methods." }, "ap_quick_payment_button": { "type": "boolean", "description": "Whether to display the button for quick payment via Apple Pay at the top of the payment UI on supported devices. `true` by default. If `false`, Apple Pay is displayed in the list of payment methods according to the [PayRank](/doc/pay-station/how-to/how-to-manage-top-payment-methods/) algorithm.\n\n
\n

Note

On Android devices and any other devices that don’t support payment with Apple Pay, this payment method will be hidden from the list of available ones regardless of the parameter value.

\n
\n" }, "is_search_field_hidden": { "type": "boolean", "description": "Whether to show a payment method search bar in the payment UI. If `true`, the search bar is hidden. `false` by default." }, "is_language_selector_hidden": { "type": "boolean", "description": "Whether the language selector is hidden on the payment page. If `false` (by default), the selector is displayed." }, "alternative_first_screen": { "type": "string", "description": "Alternative view of the payment UI screen when opened. For example, it can display prioritized payment methods.\n\nWhen set to `apple-pay`, the user sees the Apple Pay button as the primary payment option along with a link to the list of other payment methods. This logic doesn’t apply to Android devices.\n", "enum": [ "apple-pay" ] }, "ui": { "type": "object", "description": "Interface settings.", "properties": { "theme": { "$ref": "#/components/schemas/theme.ui" }, "desktop": { "$ref": "#/components/schemas/desktop.ui" }, "header": { "$ref": "#/components/schemas/header.ui" }, "mobile": { "$ref": "#/components/schemas/mobile.ui" }, "components": { "$ref": "#/components/schemas/components" }, "mode": { "$ref": "#/components/schemas/mode.ui" }, "is_prevent_external_link_open": { "$ref": "#/components/schemas/is_prevent_external_link_open" }, "is_payment_methods_list_mode": { "$ref": "#/components/schemas/is_payment_methods_list_mode" }, "is_independent_windows": { "$ref": "#/components/schemas/is_independent_windows" }, "user_account": { "$ref": "#/components/schemas/user_account" }, "currency_format": { "$ref": "#/components/schemas/currency_format" }, "is_show_close_widget_warning": { "$ref": "#/components/schemas/is_show_close_widget_warning" }, "layout": { "$ref": "#/components/schemas/layout" }, "is_three_ds_independent_windows": { "$ref": "#/components/schemas/is_three_ds_independent_windows" }, "is_cart_open_by_default": { "$ref": "#/components/schemas/is_cart_open_by_default" }, "gp_quick_payment_button": { "$ref": "#/components/schemas/gp_quick_payment_button" }, "apple_pay_quick_payment_button": { "$ref": "#/components/schemas/ap_quick_payment_button" }, "is_search_field_hidden": { "$ref": "#/components/schemas/is_search_field_hidden" }, "is_language_selector_hidden": { "$ref": "#/components/schemas/is_language_selector_hidden" }, "alternative_first_screen": { "$ref": "#/components/schemas/alternative_first_screen" } } }, "settings": { "type": "object", "description": "Settings for configuring payment process and the payment UI for a user.", "required": [ "project_id" ], "properties": { "project_id": { "$ref": "#/components/schemas/project_id" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "language": { "$ref": "#/components/schemas/language" }, "return_url": { "$ref": "#/components/schemas/return_url" }, "cancel_url": { "$ref": "#/components/schemas/cancel_url" }, "redirect_policy": { "$ref": "#/components/schemas/redirect_policy" }, "currency": { "$ref": "#/components/schemas/currency" }, "mode": { "$ref": "#/components/schemas/mode.settings" }, "payment_method": { "$ref": "#/components/schemas/payment_method" }, "payment_widget": { "$ref": "#/components/schemas/payment_widget" }, "ui": { "$ref": "#/components/schemas/ui" } } }, "subscription": { "type": "object", "description": "Subscription data.", "properties": { "plan_id": { "type": "string", "description": "External ID of the subscription plan. Can be found in the **Subscriptions > Subscription plans** section of Publisher Account." }, "operation": { "type": "string", "description": "The type of operation applied to the user’s subscription plan. To change the subscription plan, pass the `change_plan` value. You need to specify the new plan ID in the `purchase.subscription.plan_id` parameter." }, "product_id": { "type": "string", "description": "Product ID." }, "currency": { "type": "string", "description": "Currency of the subscription plan to use in all calculations." }, "available_plans": { "type": "array", "items": { "type": "string" }, "description": "Subscription plans to show in the payment UI." }, "trial_days": { "type": "integer", "description": "Trial period in days." } } }, "is_lootbox": { "type": "boolean", "description": "Whether the item is a loot box.", "default": false }, "purchase": { "type": "object", "description": "Object containing purchase details.", "properties": { "subscription": { "$ref": "#/components/schemas/subscription" }, "is_lootbox": { "$ref": "#/components/schemas/is_lootbox" } } }, "custom_parameters": { "type": "object", "description": "This object contains parameters to configure anti-fraud filters. The list of parameters is shown below. To add custom parameters, contact your Customer Success Manager or email at [csm@xsolla.com](mailto:csm@xsolla.com).\n", "properties": { "registration_date": { "type": "string", "description": "Account creation date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "total_hours": { "type": "integer", "description": "Total number of in-game hours." }, "total_characters": { "type": "integer", "description": "Number of in-game characters." }, "social_networks_added": { "type": "boolean", "description": "Whether the player has connected social media profiles." }, "profile_image_added": { "type": "boolean", "description": "Whether the player has uploaded a profile image." }, "active_date": { "type": "string", "description": "Last seen date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "total_friends": { "type": "integer", "description": "Number of friends." }, "additional_verification": { "type": "boolean", "description": "Whether the player uses account verification procedures." }, "win_rate": { "type": "integer", "description": "Win rate." }, "last_change_password_date": { "type": "string", "description": "Last password change date per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." }, "chat_activity": { "type": "boolean", "description": "Whether the player uses the chat function." }, "forum_activity": { "type": "boolean", "description": "Whether the player uses the forum function." }, "total_bans": { "type": "integer", "description": "Number of times the player was banned in the chat/forum." }, "profile_completed": { "type": "boolean", "description": "Whether the player added additional information to their profile." }, "notifications_enabled": { "type": "boolean", "description": "Whether the player enabled notifications." }, "user_level": { "type": "integer", "description": "Player’s level, reputation, or rank." }, "karma_points": { "type": "integer", "description": "Player’s karma." }, "total_sum": { "type": "number", "format": "float", "description": "Total amount of payments." }, "non_premium_currency": { "type": "number", "format": "float", "description": "Amount of non-premium currency." }, "total_game_events": { "type": "integer", "description": "Number of in-game events the player took part in." }, "total_gifts": { "type": "integer", "description": "Number of in-game gifts the player has sent/received." }, "tutorial_completed": { "type": "boolean", "description": "Whether the player has completed the game’s tutorial." }, "completed_tasks": { "type": "integer", "description": "Number of tasks/objectives completed." }, "items_used": { "type": "boolean", "description": "Whether the player uses purchased in-game items." }, "pvp_activity": { "type": "boolean", "description": "Whether the player takes part in PvP (Player(s) versus player(s)) battles." }, "total_clans": { "type": "integer", "description": "Number of clans the player is a member of." }, "unlocked_achievements": { "type": "integer", "description": "Number of achievements unlocked." }, "total_inventory_value": { "type": "number", "format": "float", "description": "Total inventory value (in-game currency)." }, "character_customized": { "type": "boolean", "description": "Whether the player has customized their character." }, "session_time": { "type": "string", "description": "Average session time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)." } } }, "token": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/user" }, "settings": { "$ref": "#/components/schemas/settings" }, "purchase": { "$ref": "#/components/schemas/purchase" }, "custom_parameters": { "$ref": "#/components/schemas/custom_parameters" } }, "example": { "settings": { "currency": "USD", "language": "en", "project_id": 16184, "ui": { "size": "medium" } }, "user": { "email": { "value": "email@example.com" }, "id": { "value": "user_2" }, "name": { "value": "John Smith" } } } }, "mock_code": { "type": "integer", "description": "An error code that you want to reproduce when testing the payment process via PayPal in sandbox mode. It works correctly only if you pass the `\"mode\":\"sandbox\"` parameter.", "enum": [ 1002, 1015, 1039, 1046, 1057, 1089, 1201, 1203, 1801, 1803, 2031, 3006, 3031, 5004 ] }, "status.enum": { "type": "string", "description": "Transaction status.", "enum": [ "created", "processing", "review", "error", "done", "awaitingRefund", "refunded", "canceled", "partiallyRefunded" ], "x-enumDescriptions": { "created": "The user initiated the transaction but it has not been processed yet.", "processing": "The transaction is being processed.", "review": "Transaction processing has been suspended by the anti-fraud system, and the transaction is currently under additional verification.", "error": "An error occurred while processing the transaction. Such payments can be refunded by contacting Xsolla customer support.", "done": "The transaction was successfully processed.", "awaitingRefund": "The transaction is awaiting a decision on refund. After the user requested a refund, Xsolla customer support manually processes the request and makes a decision on the refund.", "refunded": "A refund was made to the user’s Xsolla balance.", "canceled": "There are two possible scenarios:\n - The transaction has been canceled on the payment system’s side. For example, there were insufficient funds in user account.\n - The payment was refunded to the user.", "partiallyRefunded": "The user received a partial refund." } }, "empty-body": { "type": "object", "nullable": true, "description": "For the API call to work correctly, the request body must be empty." } }, "requestBodies": { "charge-with-saved-account": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "description": "User details.", "required": [ "ip" ], "properties": { "ip": { "type": "string", "description": "User IP address." }, "name": { "type": "string", "description": "Username." }, "legal": { "$ref": "#/components/schemas/legal" } } }, "settings": { "type": "object", "description": "Object containing purchase settings.", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "mode": { "type": "string", "description": "Set to `sandbox` to test out the payment process. Remove the parameter for real payments." }, "mock_code": { "$ref": "#/components/schemas/mock_code" } } }, "purchase": { "type": "object", "description": "Object containing purchase details.", "properties": { "description": { "type": "object", "properties": { "value": { "type": "string", "maxLength": 4000 } } }, "virtual_currency": { "type": "object", "description": "Object containing virtual currency details.", "properties": { "quantity": { "type": "number", "format": "float", "description": "Purchase amount in the virtual currency." } } }, "checkout": { "type": "object", "description": "Object containing checkout details.", "properties": { "currency": { "type": "string", "description": "Currency of the purchase. Three-letter currency code per [ISO 4217](https://developers.xsolla.com/doc/pay-station/references/supported-currencies/)." }, "amount": { "type": "number", "format": "float", "description": "Purchase amount." } } } } }, "custom_parameters": { "$ref": "#/components/schemas/custom_parameters" } } }, "example": { "purchase": { "description": { "value": "currency purchase" }, "virtual_currency": { "quantity": 100 } }, "settings": { "currency": "USD", "external_id": "ext123", "mode": "sandbox" }, "user": { "ip": "111.11.11.11", "name": "John Smith", "legal": { "name": "My Awesome Company", "address": "17 Crown Street London SW2 0JW United Kingdom", "vat_id": "GB111111111", "country": "GB" } } } } } } } } }