跳转到内容
/
查找交易（快速搜索）

Pay Station API (2.0)

概览

  • **版本：**2.0.0
  • 服务器：
    • https://api.xsolla.com/api

支付中心通过向用户提供在游戏商店中进行游戏内购买支付时的便捷UI，让合作伙伴实现其游戏变现。要设置支付UI的打开，请参阅这些说明。

Pay Station API提供以下调用组：

  • 令牌 — 包含使用任意用户参数生成令牌以便通过支付UI进行后续支付处理的API调用。
  • 令牌化 — 包含用于在不打开支付UI或无需用户介入的情况下安全处理支付的API调用。
  • 报告— 包含返回用户交易数据、生成报告及获取按货币分类的提现细目。
  • 退款 — 包含请求完全或部分退款的API调用。
  • 测试 — 包含测试拒付过程的API调用。

关于配置支付UI的详细信息，请参阅付款解决方案集成指南。

注：

还可参阅Postman合集下的Xsolla Base API部分来测试用于集成的API调用。

下载 OpenAPI 描述
index.json
index.yaml
语言
服务器
https://api.xsolla.com/merchant/v2/
Mock server
https://xsolla.redocly.app/_mock/zh/api/pay-station/

令牌

操作

令牌化

操作

报告

操作

列示所有报告

请求

获取指定数据范围的财务报告列表。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

查询
datetime_fromstring(datetime)必需

开始日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：

  • transfer_id
  • report_id

示例: datetime_from=2023-02-08
datetime_tostring(datetime)必需

结束日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：

  • transfer_id
  • report_id
datetime_from和datetime_to之间的间隔不得超过92天。

示例: 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'

响应

OK.

正文application/json
响应
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
  }
]

列示所有操作

请求

返回指定时间段内成功和取消的交易的详细信息列表。您可以在响应中获得付款信息，包括费用、税以及订单和用户的数据。您可以获得JSON或CSV格式的列表。您可以使用此 API调用进行财务对账。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

formatstring必需

数据格式。

枚举"json""csv""xls"
查询
datetime_fromstring(datetime)必需

开始日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：

  • transfer_id
  • report_id

示例: datetime_from=2023-02-08
datetime_tostring(datetime)必需

结束日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：

  • transfer_id
  • report_id
datetime_from和datetime_to之间的间隔不得超过92天。

示例: datetime_to=2023-03-08
in_transfer_currencyinteger必需

将所有财务数据转换为支付出账货币（默认使用支付入账货币）。如传入了以下任一参数，则此参数非必需：

  • transfer_id
  • report_id

show_totalboolean

是否在报告中包含交易总额。仅适用于CSV格式导出，默认值为true。

merchant_of_recordsstring or null

在册商户。可以是xsolla、merchant或不指定。如果为merchant，则返回通过合作伙伴直接帐户进行的交易。如果为xsolla，则返回非通过合作伙伴直接帐户进行的交易。如未指定，则返回所有交易。

枚举 值描述
merchant

返回通过合作伙伴直接帐户进行的交易。

xsolla

返回非通过合作伙伴直接帐户进行交易。

project_idinteger

项目ID。

show_dry_runboolean

是否包括测试交易。

transfer_idinteger

交易传输 ID。

report_idinteger

财务报告 ID。

offsetinteger

元素编号，从该元素开始生成列表（从0开始数）。

limitinteger

页面上显示的交易数限制。如传入了此参数，则不必传入datetime_from和datetime_to参数。

statusstring

交易状态。

枚举"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'

响应

交易列表已成功返回。

正文application/jsonArray [
payment_detailsobject

支付详细信息。

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.​direct_whtobject
payment_details.​direct_wht.​amountnumber(float)
payment_details.​direct_wht.​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.​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
purchaseobject

购买详细信息。

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
transactionobject

交易数据。

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
枚举"created""processing""done""canceled""error""refunded""partiallyRefunded""awaitingRefund""disputeFee"
transaction.​transfer_datestring(datetime)
userobject

带用户相关数据的对象。

user.​countrystring

使用ISO 3166-1 alpha-2标准规定的2字母组合表示国家/地区。

user.​customstring or null
user.​emailstring

用户电子邮件。

user.​idstring

用户ID。

user.​ipstring
user.​marketplacestring
user.​namestring

用户昵称。

user.​phonestring or null

电话号码。

user_balanceobject

用户余额。

user_balance.​payment_currencyobject

首选支付货币。

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)
]
响应
application/json
[
  {
    "payment_details": { … },
    "purchase": { … },
    "transaction": { … },
    "user": { … },
    "user_balance": { … }
  }
]

查找交易

请求

根据具体搜索参数返回交易列表。您将在响应中获得游戏中所有付款的数据，包括未成功完成的付款。您不仅可以指定交易时间段，还可以指定其他参数，例如搜索某个用户进行的交 易或处于某个付款状态下的交易。您可以获取JSON或CSV格式的列表。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

formatstring必需

数据格式。

枚举"json""csv""xls"
查询
datetime_fromstring(datetime)

日期范围的开始时间。

datetime_tostring(datetime)

日期范围的结束时间。

project_idinteger

项目ID。

transaction_idinteger

交易ID。

typestring

在搜索结果中显示的交易类型：

枚举 值描述
all

所有交易。

canceled

取消的交易（测试交易除外）。

test

测试交易。

transferred

成功的交易（测试交易除外）。

phonestring

用户电话号码（采用国际格式）。

user_idstring

存储在己侧的游戏内唯一用户ID。请确保传入现有用户ID。如遇到错误，请参阅常见问题回答。

user_namestring

用户名。

user_customstring

用户标识的自定义参数。

emailstring<= 100 characters

用户电子邮件。

external_idstring

游戏中的交易ID。值对于每个用户付款必须唯一。

order_idinteger

订单ID。您可以使用它调用获取订单 API方法。

示例: order_id=1234
offsetinteger

元素编号，从该元素开始生成列表（从0开始数）。

limitinteger

页面上元素数量的限制。

statusstring(status.enum)

交易状态。

枚举 值描述
awaitingRefund

交易正在等待退款决定。用户申请退款后，艾克索拉客户支持将手动处理该申请并作出决定。

canceled

有两种可能场景：

  • 交易被支付系统侧取消。例如用户帐户中资金不足。
  • 已对用户退款。
created

用户发起了交易但交易尚未被处理。

done

交易已成功处理。

error

处理交易时发生了错误。此类支付可通过联系艾克索拉客户支持进行退款。

partiallyRefunded

用户收到了部分退款。

processing

交易正在处理中。

refunded

退款已退回用户的艾克索拉余额。

review

交易处理被反欺诈系统暂停，当前正对交易进行额外验核。

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'

响应

OK.

正文application/json
响应
application/json
[
  {
    "payment_details": { … },
    "payment_system": { … },
    "purchase": { … },
    "transaction": { … },
    "user": { … }
  }
]

查找交易（快速搜索）

请求

在几秒钟内基于特定搜索参数获取交易列表。此为以JSON、CSV或XLS格式返回该数据的查找交易API调用的另一选择。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

查询
transaction_idinteger

交易ID。必须提供此参数或external_id，但不要同时提供两者。

external_idstring

游戏中的交易ID。对每个付款唯一。必须提供此参数或transaction_id，但不要同时提供两者。

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'

响应

交易列表已成功返回。

正文application/jsonArray [
payment_detailsobject

支付详细信息。

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

付款金额。

payment_details.​payment.​currencystring

支付币种。参照ISO 4217标准的三字母货币代码。

transactionobject

交易详细信息。

transaction.​external_idstring

游戏中的交易ID。值对于每个用户付款唯一。

transaction.​idinteger

交易ID。

transaction.​payment_datestring

YY-MM-DD（年-月-日）格式的支付日期。

transaction.​projectobject
transaction.​project.​idinteger

游戏的艾克索拉ID。可以在发布商帐户中找到该ID。

transaction.​project.​namestring

项目名。

transaction.​refund_reasonstring

退款原因。

transaction.​statusstring(status.enum)

交易状态。

枚举 值描述
awaitingRefund

交易正在等待退款决定。用户申请退款后，艾克索拉客户支持将手动处理该申请并作出决定。

canceled

有两种可能场景：

  • 交易被支付系统侧取消。例如用户帐户中资金不足。
  • 已对用户退款。
created

用户发起了交易但交易尚未被处理。

done

交易已成功处理。

error

处理交易时发生了错误。此类支付可通过联系艾克索拉客户支持进行退款。

partiallyRefunded

用户收到了部分退款。

processing

交易正在处理中。

refunded

退款已退回用户的艾克索拉余额。

review

交易处理被反欺诈系统暂停，当前正对交易进行额外验核。

userobject

带用户相关数据的对象。

user.​countrystring

使用ISO 3166-1 alpha-2标准规定的2字母组合表示国家/地区。

user.​emailstring

用户电子邮件。

user.​idstring

用户ID。

user.​namestring

用户名。

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

按货币获取出款细目

请求

按货币获取出款细目。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

查询
datetime_fromstring(datetime)

日期范围的开始时间。

datetime_tostring(datetime)

日期范围的结束时间。

legal_entity_idinteger

开发者法律实体ID。

statusstring

交易状态。

枚举"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'

响应

OK.

正文application/json
响应
application/json
[
  {
    "DirectTaxesOfPayments": 0.46,
    "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.14,
    "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.07,
    "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
  }
]

获取交易

请求

按ID获取完整交易信息。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

transaction_idinteger必需

交易ID。

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

响应

成功返回交易信息。

正文application/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.​direct_whtobject
finance_details.​direct_wht.​amountnumber(float)
finance_details.​direct_wht.​currencystring
finance_details.​dispute_feeobject
finance_details.​dispute_fee.​amountnumber(float)

以付款币种表示的争议费用金额。

finance_details.​dispute_fee.​currencystring

支付币种。参照ISO 4217标准的三字母货币代码。

finance_details.​dispute_fee.​datestring

提出争议的日期。

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.​sales_taxobject
finance_details.​sales_tax.​amountnumber(float)
finance_details.​sales_tax.​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
]
响应
application/json
[
  {
    "customer_details": { … },
    "finance_details": { … },
    "payment_details": { … },
    "subscription_details": { … },
    "transaction_details": { … }
  }
]

列示所有汇款

请求

列示某个时间段内的所有出款。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

查询
datetime_fromstring(datetime)

日期范围的开始时间。

datetime_tostring(datetime)

日期范围的结束时间。

legal_entity_idinteger

开发者法律实体ID。

statusstring

出款状态。

枚举 值描述
hold

正在等待请求处理。

paid

出款完成。

ready

出款进行中。

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'

响应

OK.

正文application/json
响应
application/json
[
  {
    "canceled": 0,
    "payout": { … },
    "rate": 1,
    "transfer": { … }
  }
]

退款

操作

测试

操作