Skip to content
/
Get transaction

Pay Station API (2.0)

Overview

  • Version: 2.0.0
  • Servers:
    • https://api.xsolla.com/api

Pay 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.

The Pay Station API provides the following groups of calls:

  • Token — includes the API call to generate a token with arbitrary user parameters for further payment processing via the payment UI.
  • Tokenization — includes API calls to securely process payments without opening the payment UI or involving the user.
  • Reports — includes API calls to return data on user transactions, generate reports, and get payouts breakdown by currency.
  • Refund — includes API calls to request full and partial refunds.
  • Testing — includes the API call to test the chargeback process.

You can find detailed information about configuring the payment UI in the Payments solution integration guide.

Note

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

Download OpenAPI description
index.json
index.yaml
Languages
Servers
https://api.xsolla.com/merchant/v2/
Mock server
https://xsolla.redocly.app/_mock/api/pay-station/

Token

Operations

Tokenization

Operations

Reports

Operations

Find transactions

Request

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.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

formatstringrequired

Data format.

Enum"json""csv""xls"
Query
datetime_fromstring(datetime)

Period start.

datetime_tostring(datetime)

Period end.

project_idinteger

Project ID.

transaction_idinteger

Transaction ID.

typestring

Type of transactions shown in the search results:

Enum ValueDescription
all

All transactions.

transferred

Successful transactions excluding test transactions.

canceled

Canceled transactions excluding test transactions.

test

Test transactions.

phonestring

Phone number in international format.

user_idstring

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.

user_namestring

Username.

user_customstring

Custom parameter for user identification.

emailstring<= 100 characters

User email.

external_idstring

Transaction ID in the game. Has to be unique for each user payment.

order_idinteger

Order ID. You can use it to call the Get order API method.

Example: order_id=1234
offsetinteger

Number of the element from which the list is generated (the count starts from 0).

limitinteger

Limit for the number of elements on the page.

statusstring(status.enum)

Transaction status.

Enum ValueDescription
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:

  • The transaction has been canceled on the payment system’s side. For example, there were insufficient funds in user account.
  • The payment was refunded to the user.
partiallyRefunded

The user received a partial refund.

curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/search.{format}?datetime_from=string&datetime_to=string&project_id=0&transaction_id=0&type=all&phone=string&user_id=string&user_name=string&user_custom=string&email=string&external_id=string&order_id=1234&offset=0&limit=0&status=created'

Responses

OK.

Bodyapplication/json
Response
application/json
[
  {
    "transaction": { … },
    "user": { … },
    "payment_details": { … },
    "purchase": { … },
    "payment_system": { … }
  }
]

Find transactions (fast search)

Request

Gets a list of transactions based on specific search parameters within a few seconds. This is an alternative to the Find transactions API call that returns data in JSON, CSV, or XLS format.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

Query
transaction_idinteger

Transaction ID. Either this or external_id must be provided, but not both.

external_idstring

Transaction ID in the game. It is unique for each payment. Either this or transaction_id must be provided, but not both.

curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/simple_search?transaction_id=0&external_id=string'

Responses

The list of transactions was successfully returned.

Bodyapplication/jsonArray [
userobject

User details.

user.​idstring

User ID.

user.​namestring

User name.

user.​emailstring

User email.

user.​countrystring

Two-letter uppercase country code per ISO 3166-1 alpha-2.

transactionobject

Transaction details.

transaction.​projectobject
transaction.​project.​idinteger

Project ID. Can be found in Publisher Account.

transaction.​project.​namestring

Project name.

transaction.​idinteger

Transaction ID.

transaction.​external_idstring

Transaction ID in the game. It is unique for each user payment.

transaction.​statusstring(status.enum)

Transaction status.

Enum ValueDescription
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:

  • The transaction has been canceled on the payment system’s side. For example, there were insufficient funds in user account.
  • The payment was refunded to the user.
partiallyRefunded

The user received a partial refund.

transaction.​payment_datestring

Date of the payment in YY-MM-DD format.

transaction.​refund_reasonstring

Refund reason.

payment_detailsobject

Payment details.

payment_details.​paymentobject
payment_details.​payment.​amountnumber(float)

Payment amount.

payment_details.​payment.​currencystring

Payment currency. Three-letter currency code per ISO 4217.

]
Response
application/json
[
  {
    "transaction": { … },
    "user": { … },
    "payment_details": { … }
  }
]

Get transaction

Request

Gets full transaction info by ID.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

transaction_idintegerrequired

Transaction ID.

curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/{transaction_id}/details'

Responses

The transaction information was successfully returned.

Bodyapplication/jsonArray [
customer_detailsobject
customer_details.​billing_addressstring
customer_details.​binstring
customer_details.​browser_languagestring
customer_details.​countrystring
customer_details.​ipstring
customer_details.​paystation_countrystring
customer_details.​phonestring or null
customer_details.​timezonestring
customer_details.​user_idstring
customer_details.​user_namestring
finance_detailsobject
finance_details.​paymentobject
finance_details.​payment.​amountnumber(float)
finance_details.​payment.​currencystring
finance_details.​payment_method_feeobject
finance_details.​payment_method_fee.​amountnumber(float)
finance_details.​payment_method_fee.​currencystring
finance_details.​payment_method_sumobject
finance_details.​payment_method_sum.​amountnumber(float)
finance_details.​payment_method_sum.​currencystring
finance_details.​payoutobject
finance_details.​payout.​amountnumber(float)
finance_details.​payout.​currencystring
finance_details.​payout_currency_ratenumber(float)
finance_details.​repatriation_commissionobject
finance_details.​repatriation_commission.​amountnumber(float)
finance_details.​repatriation_commission.​currencystring
finance_details.​dispute_feeobject
finance_details.​dispute_fee.​currencystring

Payment currency. Three-letter currency code per ISO 4217.

finance_details.​dispute_fee.​amountnumber(float)

The dispute fee amount in the payment currency.

finance_details.​dispute_fee.​datestring

Date of the dispute opening.

finance_details.​sales_taxobject
finance_details.​sales_tax.​amountnumber(float)
finance_details.​sales_tax.​currencystring
finance_details.​direct_whtobject
finance_details.​direct_wht.​amountnumber(float)
finance_details.​direct_wht.​currencystring
finance_details.​vatobject
finance_details.​vat.​amountnumber(float)
finance_details.​vat.​currencystring
finance_details.​xsolla_balance_sumobject
finance_details.​xsolla_balance_sum.​amountnumber(float)
finance_details.​xsolla_balance_sum.​currencystring
finance_details.​xsolla_feeobject
finance_details.​xsolla_fee.​amountnumber(float)
finance_details.​xsolla_fee.​currencystring
payment_detailsobject
payment_details.​card_holdernamestring or null
payment_details.​card_issuerstring
payment_details.​card_monthinteger
payment_details.​card_numberinteger
payment_details.​card_schemestring
payment_details.​card_yearinteger
payment_details.​customer_firstnamestring
payment_details.​customer_lastnamestring
payment_details.​enrollmentboolean
payment_details.​ps_accountstring
payment_details.​zip_codestring
subscription_detailsobject
subscription_details.​is_payment_from_subscriptionboolean
subscription_details.​is_subscription_createdboolean
transaction_detailsobject
transaction_details.​amountnumber(float)
transaction_details.​cancellation_datestring or null
transaction_details.​countrystring
transaction_details.​currencystring
transaction_details.​custom_parametersstring or null
transaction_details.​foreign_invoicestring or null
transaction_details.​gift_recipient_emailstring or null
transaction_details.​gift_recipient_idstring or null
transaction_details.​payment_datestring
transaction_details.​payment_methodstring
transaction_details.​payment_method_namestring
transaction_details.​projectinteger
transaction_details.​project_namestring
transaction_details.​purchaseobject
transaction_details.​purchase.​checkoutobject
transaction_details.​purchase.​checkout.​amountnumber(float)
transaction_details.​purchase.​checkout.​currencystring
transaction_details.​purchase.​pin_codesobject
transaction_details.​purchase.​pin_codes.​amountnumber(float)
transaction_details.​purchase.​pin_codes.​contentstring or null
transaction_details.​purchase.​pin_codes.​currencystring or null
transaction_details.​purchase.​totalobject
transaction_details.​purchase.​total.​amountnumber(float)
transaction_details.​purchase.​total.​currencystring
transaction_details.​purchase.​virtual_currencyobject
transaction_details.​purchase.​virtual_currency.​amountnumber(float)
transaction_details.​purchase.​virtual_currency.​currencystring
transaction_details.​purchase.​virtual_currency.​namestring
transaction_details.​purchase.​virtual_currency.​quantitystring
transaction_details.​purchase.​virtual_itemsobject or null
transaction_details.​purchase.​virtual_items.​amountnumber(float)
transaction_details.​purchase.​virtual_items.​contentstring
transaction_details.​purchase.​virtual_items.​currencystring
transaction_details.​refund_commentstring or null
transaction_details.​refund_reasonstring or null
transaction_details.​statusstring
transaction_details.​user_idstring
]
Response
application/json
[
  {
    "customer_details": { … },
    "finance_details": { … },
    "payment_details": { … },
    "subscription_details": { … },
    "transaction_details": { … }
  }
]

Get transactions

Request

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.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

formatstringrequired

Data format.

Enum"json""csv""xls"
Query
datetime_fromstring(datetime)required

Period start in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed:

  • transfer_id
  • report_id

Example: datetime_from=2023-02-08
datetime_tostring(datetime)required

Period end in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed:

  • transfer_id
  • report_id
The difference between datetime_from and datetime_to cannot be more than 92 days.

Example: datetime_to=2023-03-08
in_transfer_currencyintegerrequired

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:

  • transfer_id
  • report_id

show_totalboolean

Whether to include the total transactions amount in the report. Available for export in CSV format only. true by default.

merchant_of_recordsstring or null

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.

Enum ValueDescription
merchant

Returns transactions made via the partner’s gateways.

xsolla

Returns transactions made not via the partner’s gateways.

project_idinteger

Project ID.

show_dry_runboolean

Whether to include test transactions.

transfer_idinteger

Payout ID.

report_idinteger

Financial report ID.

offsetinteger

Number of the element from which the list is generated (the count starts from 0).

limitinteger

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.

statusstring

Transaction status.

Enum"done""canceled""error""refunded"
curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v3/merchants/{merchant_id}/reports/transactions/registry.{format}?datetime_from=2023-02-08&datetime_to=2023-03-08&in_transfer_currency=0&show_total=true&merchant_of_records=xsolla&project_id=0&show_dry_run=true&transfer_id=0&report_id=0&offset=0&limit=0&status=done'

Responses

The list of transactions was successfully returned.

Bodyapplication/jsonArray [
userobject

User details.

user.​idstring

User ID.

user.​emailstring

User email.

user.​namestring

User screen name.

user.​phonestring or null

User phone number.

user.​countrystring

Two-letter uppercase country code per ISO 3166-1 alpha-2.

user.​customstring or null
user.​marketplacestring
user.​ipstring
user_balanceobject

User balance.

user_balance.​payment_currencyobject

Preferred payment currency.

user_balance.​payment_currency.​deduction_amountnumber(float)
user_balance.​payment_currency.​payout_amount_from_balancenumber(float)
user_balance.​payment_currency.​purchase_amount_from_balancenumber(float)
transactionobject

Transaction data.

transaction.​custom_parametersobject or null
transaction.​direct_accountinteger
transaction.​dry_runinteger
transaction.​external_idstring or null
transaction.​idinteger
transaction.​payment_methodobject
transaction.​payment_method.​classstring
transaction.​payment_method.​idinteger
transaction.​payment_method.​namestring
transaction.​projectobject
transaction.​project.​idinteger
transaction.​project.​namestring
transaction.​refund_reasonstring or null
transaction.​refund_reason_commentstring or null
transaction.​statusstring
Enum"created""processing""done""canceled""error""refunded""partiallyRefunded""awaitingRefund""disputeFee"
transaction.​transfer_datestring(datetime)
purchaseobject

Purchase details.

purchase.​friendobject
purchase.​friend.​emailstring or null
purchase.​friend.​user_idstring or null
purchase.​items_amountinteger
purchase.​pin_codesobject
purchase.​pin_codes.​amountnumber or null(float)
purchase.​pin_codes.​contentstring or null
purchase.​pin_codes.​currencystring or null
purchase.​purchase_amountnumber(float)
purchase.​simple_checkoutobject
purchase.​simple_checkout.​amountnumber or null(float)
purchase.​simple_checkout.​currencystring or null
purchase.​subscriptionobject
purchase.​subscription.​namestring or null
purchase.​subscription.​plan_idinteger or null
purchase.​subscription.​product_idstring or null
purchase.​subscription.​product_namestring or null
purchase.​subscription.​subscription_idinteger or null
purchase.​virtual_currencyobject
purchase.​virtual_currency.​amountnumber(float)
purchase.​virtual_currency.​currencystring
purchase.​virtual_currency_amountinteger
purchase.​virtual_itemsobject
purchase.​virtual_items.​amountnumber or null(float)
purchase.​virtual_items.​contentstring or null
purchase.​virtual_items.​currencystring or null
payment_detailsobject

Payment details.

payment_details.​chargebackPenaltyobject
payment_details.​chargebackPenalty.​amountnumber(float)
payment_details.​commission_agentobject
payment_details.​commission_agent.​amountnumber(float)
payment_details.​commission_agent.​percentnumber(float)
payment_details.​commission_agent_fixedinteger
payment_details.​commission_psobject
payment_details.​commission_ps.​amountnumber(float)
payment_details.​commission_ps.​fixed_amountinteger
payment_details.​commission_ps.​percentnumber(float)
payment_details.​commission_ps_from_vatobject
payment_details.​commission_ps_from_vat.​amountnumber(float)
payment_details.​commission_userobject
payment_details.​commission_user.​amountnumber(float)
payment_details.​commission_user.​percentnumber(float)
payment_details.​commission_xsollaobject
payment_details.​commission_xsolla.​amountnumber(float)
payment_details.​commission_xsolla.​fixed_amountinteger
payment_details.​commission_xsolla.​percentnumber(float)
payment_details.​cpa_network_commissionobject
payment_details.​cpa_network_commission.​amountnumber(float)
payment_details.​cpa_network_commission.​percentnumber(float)
payment_details.​paymentobject
payment_details.​payment.​amountnumber(float)
payment_details.​payment.​amount_from_psinteger
payment_details.​payment.​currencystring
payment_details.​payoutobject
payment_details.​payout.​amountnumber(float)
payment_details.​payout.​amount_from_psnumber(float)
payment_details.​payout.​currencystring
payment_details.​payout.​fx_ratenumber(float)
payment_details.​payout.​percentnumber(float)
payment_details.​direct_whtobject
payment_details.​direct_wht.​amountnumber(float)
payment_details.​direct_wht.​percentnumber(float)
payment_details.​refundPenaltyobject
payment_details.​refundPenalty.​amountnumber(float)
payment_details.​repatriation_costsobject
payment_details.​repatriation_costs.​amountnumber(float)
payment_details.​repatriation_costs.​percentnumber(float)
payment_details.​sales_taxobject
payment_details.​sales_tax.​amountnumber(float)
payment_details.​sales_tax.​percentnumber(float)
payment_details.​vatobject
payment_details.​vat.​amountnumber(float)
payment_details.​vat.​percentnumber(float)
payment_details.​vat.​user_amountinteger
payment_details.​vat.​user_percentinteger
]
Response
application/json
[
  {
    "payment_details": { … },
    "purchase": { … },
    "transaction": { … },
    "user": { … },
    "user_balance": { … }
  }
]

Get payouts

Request

Lists all payouts for a period.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

Query
datetime_fromstring(datetime)

Period start.

datetime_tostring(datetime)

Period end.

legal_entity_idinteger

ID of the developer's legal entity.

statusstring

Payout status.

Enum ValueDescription
hold

Waiting for a request to proceed.

ready

Payout in progress.

paid

Payout completed.

curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transfers?datetime_from=string&datetime_to=string&legal_entity_id=0&status=hold'

Responses

OK.

Bodyapplication/json
Response
application/json
[
  {
    "payout": { … },
    "transfer": { … },
    "rate": 1,
    "canceled": 0
  }
]

Get payouts breakdown in currency

Request

Gets payouts breakdown in currency.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

Query
datetime_fromstring(datetime)

Period start.

datetime_tostring(datetime)

Period end.

legal_entity_idinteger

ID of the developer's legal entity.

statusstring

Transaction status.

Enum"done""canceled""error""refunded"
curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/summary/transfer?datetime_from=string&datetime_to=string&legal_entity_id=0&status=done'

Responses

OK.

Bodyapplication/json
Response
application/json
[
  {
    "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
  }
]

Get reports

Request

Gets the list of financial reports over a specified period.

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.

Security
basicAuth
Path
merchant_idintegerrequired

Merchant ID.

Query
datetime_fromstring(datetime)required

Period start in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed:

  • transfer_id
  • report_id

Example: datetime_from=2023-02-08
datetime_tostring(datetime)required

Period end in the YYYY-MM-DD format. Not required if at least one of the following parameters is passed:

  • transfer_id
  • report_id
The difference between datetime_from and datetime_to cannot be more than 92 days.

Example: datetime_to=2023-03-08
curl -i -X GET \
  -u <username>:<password> \
  'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports?datetime_from=2023-02-08&datetime_to=2023-03-08'

Responses

OK.

Bodyapplication/json
Response
application/json
[
  {
    "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
  }
]

Refund

Operations

Testing

Operations