{ "openapi": "3.0.0", "info": { "description": "# 概览\n\n* **版本：**2.0.0\n* **服务器**：\n * `https://api.xsolla.com/api`\n\n支付中心通过向用户提供在游戏商店中进行游戏内购买支付时的便捷UI，让合作伙伴实现其游戏变现。要设置支付UI的打开，请参阅这些[说明](/zh/doc/pay-station/how-to/how-to-open-payment-ui/)。\n\nPay Station API提供以下调用组：\n- 令牌 — 包含使用任意用户参数生成令牌以便通过支付UI进行后续支付处理的API调用。\n- [令牌化](/zh/doc/pay-station/features/tokenization/) — \n 包含用于在不打开支付UI或无需用户介入的情况下安全处理支付的API调用。\n- 报告— 包含返回用户交易数据、生成报告及获取按货币分类的提现细目。\n- 退款 — 包含请求完全或部分退款的API调用。\n- 测试 — 包含测试拒付过程的API调用。\n\n关于配置支付UI的详细信息，请参阅[付款解决方案集成指南](/zh/solutions/payments/integration-guide/integration-flow/)。\n\n
\n

注：

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

\n
\n", "title": "Pay Station API", "version": "2.0" }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ], "tags": [ { "name": "token", "x-displayName": "令牌" }, { "name": "tokenization", "x-displayName": "令牌化" }, { "name": "reports", "x-displayName": "报告" }, { "name": "refund", "x-displayName": "退款" }, { "name": "testing", "x-displayName": "测试" } ], "paths": { "/merchants/{merchant_id}/projects/{project_id}/payments/{transaction_id}/chargeback": { "post": { "description": "在沙盒模式下请求拒付：\n\n- 要访问沙盒模式，请在[获取令牌](https://developers.xsolla.com/zh/api/pay-station/operation/create-token/)时传入`\"mode\":\"sandbox\"`。\n\n- 需在用于测试的同一个项目中以沙盒模式进行测试支付。\n\n- 交易状态必须**不能**为`refunded`、`cancelled`。\n\n- 您在发布商帐户中的角色必须至少为**财务经理**。（可在**公司设置 > 用户**部分找到。）\n\n- 请参阅说明了解此测试场景的更多信息。\n\n
\n

注：

请参阅文档了解其他测试场景的更多信息。

\n
\n", "operationId": "request-chargeback", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/empty-body" } } }, "required": true }, "responses": { "204": { "description": "No Content (无错误)." }, "404": { "description": "Transaction Not Found." }, "422": { "content": { "application/json": { "example": { "message": "Not test payment. Chargeback is possible only for payments made in sandbox mode." }, "schema": { "properties": { "message": { "description": "可能返回以下消息之一：\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.", "type": "string" } }, "type": "object" } } }, "description": "Unprocessable Entity (请求参数无效) 。" } }, "security": [ { "basicAuth": [] } ], "summary": "请求拒付", "tags": [ "testing" ], "x-server": true } }, "/merchants/{merchant_id}/reports": { "get": { "description": "获取指定数据范围的财务报告列表。\n\n
\n

注意

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

\n
\n", "operationId": "get-reports", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/datetime-from-req" }, { "$ref": "#/components/parameters/datetime-to-req" } ], "responses": { "200": { "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 } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有报告", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/registry.{format}": { "servers": [ { "url": "https://api.xsolla.com/merchant/v3" } ], "get": { "description": "返回指定时间段内成功和取消的交易的详细信息列表。您可以在响应中获得付款信息，包括费用、税以及订单和用户的数据。您可以获得JSON或CSV格式的列表。您可以使用此\nAPI调用进行财务对账。\n\n
\n

注意

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

\n
\n", "operationId": "get-transactions", "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": { "content": { "application/json": { "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 }, "direct_wht": { "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 }, "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", "ip": "209.11.22.33", "marketplace": "Pay Station", "name": "Tom", "phone": null }, "user_balance": { "payment_currency": { "deduction_amount": 0, "payout_amount_from_balance": 0.02, "purchase_amount_from_balance": 0.02 } } } ], "schema": { "items": { "properties": { "payment_details": { "description": "支付详细信息。", "properties": { "chargebackPenalty": { "properties": { "amount": { "format": "float", "type": "number" } }, "type": "object" }, "commission_agent": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "commission_agent_fixed": { "type": "integer" }, "commission_ps": { "properties": { "amount": { "format": "float", "type": "number" }, "fixed_amount": { "type": "integer" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "commission_ps_from_vat": { "properties": { "amount": { "format": "float", "type": "number" } }, "type": "object" }, "commission_user": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "commission_xsolla": { "properties": { "amount": { "format": "float", "type": "number" }, "fixed_amount": { "type": "integer" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "cpa_network_commission": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "direct_wht": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "payment": { "properties": { "amount": { "format": "float", "type": "number" }, "amount_from_ps": { "type": "integer" }, "currency": { "type": "string" } }, "type": "object" }, "payout": { "properties": { "amount": { "format": "float", "type": "number" }, "amount_from_ps": { "format": "float", "type": "number" }, "currency": { "type": "string" }, "fx_rate": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "refundPenalty": { "properties": { "amount": { "format": "float", "type": "number" } }, "type": "object" }, "repatriation_costs": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "sales_tax": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" } }, "type": "object" }, "vat": { "properties": { "amount": { "format": "float", "type": "number" }, "percent": { "format": "float", "type": "number" }, "user_amount": { "type": "integer" }, "user_percent": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "purchase": { "description": "购买详细信息。", "properties": { "friend": { "properties": { "email": { "nullable": true, "type": "string" }, "user_id": { "nullable": true, "type": "string" } }, "type": "object" }, "items_amount": { "type": "integer" }, "pin_codes": { "properties": { "amount": { "format": "float", "nullable": true, "type": "number" }, "content": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" } }, "type": "object" }, "purchase_amount": { "format": "float", "type": "number" }, "simple_checkout": { "properties": { "amount": { "format": "float", "nullable": true, "type": "number" }, "currency": { "nullable": true, "type": "string" } }, "type": "object" }, "subscription": { "properties": { "name": { "nullable": true, "type": "string" }, "plan_id": { "nullable": true, "type": "integer" }, "product_id": { "nullable": true, "type": "string" }, "product_name": { "nullable": true, "type": "string" }, "subscription_id": { "nullable": true, "type": "integer" } }, "type": "object" }, "virtual_currency": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "virtual_currency_amount": { "type": "integer" }, "virtual_items": { "properties": { "amount": { "format": "float", "nullable": true, "type": "number" }, "content": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" }, "transaction": { "description": "交易数据。", "properties": { "custom_parameters": { "nullable": true, "type": "object" }, "direct_account": { "type": "integer" }, "dry_run": { "type": "integer" }, "external_id": { "nullable": true, "type": "string" }, "id": { "type": "integer" }, "payment_method": { "properties": { "class": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "project": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "refund_reason": { "nullable": true, "type": "string" }, "refund_reason_comment": { "nullable": true, "type": "string" }, "status": { "enum": [ "created", "processing", "done", "canceled", "error", "refunded", "partiallyRefunded", "awaitingRefund", "disputeFee" ], "type": "string" }, "transfer_date": { "format": "datetime", "type": "string" } }, "type": "object" }, "user": { "description": "带用户相关数据的对象。", "properties": { "country": { "description": "使用[ISO 3166-1 alpha-2标准](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)规定的2字母组合表示国家/地区。", "type": "string" }, "custom": { "nullable": true, "type": "string" }, "email": { "description": "用户电子邮件。", "type": "string" }, "id": { "description": "用户ID。", "type": "string" }, "ip": { "type": "string" }, "marketplace": { "type": "string" }, "name": { "description": "用户昵称。", "type": "string" }, "phone": { "description": "电话号码。", "nullable": true, "type": "string" } }, "type": "object" }, "user_balance": { "description": "用户余额。", "properties": { "payment_currency": { "description": "首选支付货币。", "properties": { "deduction_amount": { "format": "float", "type": "number" }, "payout_amount_from_balance": { "format": "float", "type": "number" }, "purchase_amount_from_balance": { "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "type": "array" } } }, "description": "交易列表已成功返回。" } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有操作", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/search.{format}": { "get": { "description": "根据具体搜索参数返回交易列表。您将在响应中获得游戏中所有付款的数据，包括未成功完成的付款。您不仅可以指定交易时间段，还可以指定其他参数，例如搜索某个用户进行的交\n易或处于某个付款状态下的交易。您可以获取JSON或CSV格式的列表。\n\n
\n

注意

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

\n
\n", "operationId": "find-transactions", "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": { "content": { "application/json": { "example": [ { "payment_details": { "payment": { "amount": 7.96, "amount_from_ps": 7.96, "currency": "RUB" }, "sales_tax": { "amount": 0, "percent": 0 } }, "payment_system": { "decline_reason": null }, "purchase": { "pin_codes": { "amount": null, "content": null, "currency": null }, "simple_checkout": { "amount": 7.96, "currency": "RUB" }, "subscription": { "name": null }, "virtual_currency": { "amount": 0, "name": null }, "virtual_items": null }, "transaction": { "create_date": "2021-10-20", "dry_run": 0, "external_id": "example-external-id", "id": 123456789, "is_refund_allowed": 0, "order_id": 1234, "payment_method": { "id": 1, "name": "PayPal" }, "project": { "id": 123456, "name": "Example" }, "refund_reason": null, "status": "done", "transfer_date": "2021-10-20" }, "user": { "country": "RU", "custom": null, "email": "email@example.com", "id": "example-id", "name": "Example", "phone": null } } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "查找交易", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/simple_search": { "get": { "description": "在几秒钟内基于特定搜索参数获取交易列表。此为以JSON、CSV或XLS格式返回该数据的[查找交易](/zh/api/pay-station/operation/find-transactions/)API调用的另一选择。\n\n
\n

注意

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

\n
\n", "operationId": "find-transactions-fast", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "description": "交易ID。必须提供此参数或`external_id`，但不要同时提供两者。", "in": "query", "name": "transaction_id", "schema": { "type": "integer" } }, { "description": "游戏中的交易ID。对每个付款唯一。必须提供此参数或`transaction_id`，但不要同时提供两者。", "in": "query", "name": "external_id", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": [ { "payment_details": { "payment": { "amount": 7.96, "currency": "BRL" } }, "transaction": { "external_id": "example_external_id_123", "id": 123456, "payment_date": "2023-02-11 15:32:46", "project": { "id": 123456, "name": "Test" }, "status": "done" }, "user": { "country": "BR", "email": "email@example.com", "id": "123456", "name": "John Smith" } } ], "schema": { "items": { "properties": { "payment_details": { "description": "支付详细信息。", "properties": { "payment": { "properties": { "amount": { "description": "付款金额。", "format": "float", "type": "number" }, "currency": { "description": "支付币种。参照[ISO 4217](https://developers.xsolla.com/zh/doc/pay-station/references/supported-currencies/)标准的三字母货币代码。", "type": "string" } }, "type": "object" } }, "type": "object" }, "transaction": { "description": "交易详细信息。", "properties": { "external_id": { "description": "游戏中的交易ID。值对于每个用户付款唯一。", "type": "string" }, "id": { "description": "交易ID。", "type": "integer" }, "payment_date": { "description": "YY-MM-DD（年-月-日）格式的支付日期。", "type": "string" }, "project": { "properties": { "id": { "description": "游戏的艾克索拉ID。可以在发布商帐户中找到该ID。", "type": "integer" }, "name": { "description": "项目名。", "type": "string" } }, "type": "object" }, "refund_reason": { "description": "退款原因。", "type": "string" }, "status": { "$ref": "#/components/schemas/status.enum" } }, "type": "object" }, "user": { "description": "带用户相关数据的对象。", "properties": { "country": { "description": "使用[ISO 3166-1 alpha-2标准](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)规定的2字母组合表示国家/地区。", "type": "string" }, "email": { "description": "用户电子邮件。", "type": "string" }, "id": { "description": "用户ID。", "type": "string" }, "name": { "description": "用户名。", "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" } } }, "description": "交易列表已成功返回。" }, "403": { "description": "访问被拒绝。" }, "404": { "description": "未找到交易。" }, "422": { "description": "无法处理的实体（必须传入`transaction_id`或`external_id`）。" } }, "security": [ { "basicAuth": [] } ], "summary": "查找交易（快速搜索）", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/summary/transfer": { "get": { "description": "按货币获取出款细目。\n\n
\n

注意

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

\n
\n", "operationId": "get-payouts-breakdown", "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": { "content": { "application/json": { "example": [ { "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 } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "按货币获取出款细目", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/details": { "get": { "description": "按ID获取完整交易信息。\n\n
\n

注意

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

\n
\n", "operationId": "get-transaction", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "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": { "direct_wht": { "amount": 0, "currency": "USD" }, "dispute_fee": { "amount": 70, "currency": "USD", "date": "2019-04-20 16:15:37" }, "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" }, "sales_tax": { "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" } } ], "schema": { "items": { "properties": { "customer_details": { "properties": { "billing_address": { "type": "string" }, "bin": { "type": "string" }, "browser_language": { "type": "string" }, "country": { "type": "string" }, "ip": { "type": "string" }, "paystation_country": { "type": "string" }, "phone": { "nullable": true, "type": "string" }, "timezone": { "type": "string" }, "user_id": { "type": "string" }, "user_name": { "type": "string" } }, "type": "object" }, "finance_details": { "properties": { "direct_wht": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "dispute_fee": { "properties": { "amount": { "description": "以付款币种表示的争议费用金额。", "format": "float", "type": "number" }, "currency": { "description": "支付币种。参照[ISO 4217](/zh/doc/pay-station/references/supported-currencies/)标准的三字母货币代码。", "type": "string" }, "date": { "description": "提出争议的日期。", "type": "string" } }, "type": "object" }, "payment": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "payment_method_fee": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "payment_method_sum": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "payout": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "payout_currency_rate": { "format": "float", "type": "number" }, "repatriation_commission": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "sales_tax": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "vat": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "xsolla_balance_sum": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "xsolla_fee": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" } }, "type": "object" }, "payment_details": { "properties": { "card_holdername": { "nullable": true, "type": "string" }, "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" } }, "type": "object" }, "subscription_details": { "properties": { "is_payment_from_subscription": { "type": "boolean" }, "is_subscription_created": { "type": "boolean" } }, "type": "object" }, "transaction_details": { "properties": { "amount": { "format": "float", "type": "number" }, "cancellation_date": { "nullable": true, "type": "string" }, "country": { "type": "string" }, "currency": { "type": "string" }, "custom_parameters": { "nullable": true, "type": "string" }, "foreign_invoice": { "nullable": true, "type": "string" }, "gift_recipient_email": { "nullable": true, "type": "string" }, "gift_recipient_id": { "nullable": true, "type": "string" }, "payment_date": { "type": "string" }, "payment_method": { "type": "string" }, "payment_method_name": { "type": "string" }, "project": { "type": "integer" }, "project_name": { "type": "string" }, "purchase": { "properties": { "checkout": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "pin_codes": { "properties": { "amount": { "format": "float", "type": "number" }, "content": { "nullable": true, "type": "string" }, "currency": { "nullable": true, "type": "string" } }, "type": "object" }, "total": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" } }, "type": "object" }, "virtual_currency": { "properties": { "amount": { "format": "float", "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "string" } }, "type": "object" }, "virtual_items": { "nullable": true, "properties": { "amount": { "format": "float", "type": "number" }, "content": { "type": "string" }, "currency": { "type": "string" } }, "type": "object" } }, "type": "object" }, "refund_comment": { "nullable": true, "type": "string" }, "refund_reason": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" } } }, "description": "成功返回交易信息。" } }, "security": [ { "basicAuth": [] } ], "summary": "获取交易", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/partial_refund": { "put": { "description": "向用户发送部分退款请求。关于退款流程和支持部分退款的支付方式的详细信息，请参阅我们的[文档](https://developers.xsolla.com/zh/doc/pay-station/features/refund/#pay_station_features_refund_how_it_works_partial_refund_flow)。\n\n
\n

注：

您可以在沙盒模式下调用此API方法，方法是在请求中传入测试支付的数据。关于沙盒模式访问和测试场景的详细信息，请参阅说明。

\n
\n\n

\n\n
\n

注意

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

\n
\n", "operationId": "request-partial-refund", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": "test refund request", "refund_amount": 1.5 }, "schema": { "properties": { "description": { "description": "退款原因。", "maxLength": 4000, "type": "string" }, "refund_amount": { "description": "以购买货币表示的退款金额。", "format": "float", "type": "number" } }, "required": [ "description", "refund_amount" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "已接受退款请求" }, "403": { "description": "没有必要权限" }, "404": { "content": { "application/json": { "example": { "message": "Transaction with specified ID does not exist." }, "schema": { "properties": { "message": { "description": "不存在所指定ID的交易。请检查支付凭据。否则请发送邮件至support@xsolla.com与艾克索拉支持人员联系。", "type": "string" } }, "type": "object" } } }, "description": "未找到交易" }, "422": { "content": { "application/json": { "example": { "message": "Partial refund is unavailable for subscription payments." }, "schema": { "properties": { "message": { "description": "**无法接受退款**\n\n返回以下消息之一：\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 \n later.\n- Requested partial refund amount exceeds payment amount.\n- Requested partial refund amount is less than minimum amount specified by \n payment system.\n- Payment amount after partial refund will be less than allowable amount \n specified by payment system.\n- Dispute for this invoice is already opened. Can’t make a refund yet.\n\n**当前支付方式不支持部分退款**\n\n返回以下消息之一：\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 \n creation.\n\n**由于精确度位数错误无法执行部分退款**\n\n返回以下消息：\n- Partial refund is unavailable because requested amount is specified with \n incorrect precision for purchase currency.\n", "type": "string" } }, "type": "object" } } }, "description": "无法处理的实体" } }, "security": [ { "basicAuth": [] } ], "summary": "请求部分退款", "tags": [ "refund" ], "x-server": true } }, "/merchants/{merchant_id}/reports/transactions/{transaction_id}/refund": { "put": { "description": "发送退款请求以向用户退款。详细过程请参阅[退款功能](https://developers.xsolla.com/zh/doc/pay-station/features/refund/)。\n\n
\n

注：

您可以在沙盒模式下调用此API方法，方法是在请求中传入测试支付的数据。关于沙盒模式访问和测试场景的详细信息，请参阅说明。

\n
\n\n

\n\n
\n

注意

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

\n
\n", "operationId": "request-refund", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/transaction-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": "test refund request" }, "schema": { "properties": { "description": { "description": "退款原因。", "maxLength": 4000, "type": "string" }, "email": { "description": "用户电子邮件。", "maxLength": 100, "type": "string" } }, "required": [ "description" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "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." }, "schema": { "properties": { "message": { "description": "可能返回以下消息之一：\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.", "type": "string" } }, "type": "object" } } }, "description": "OK." }, "204": { "description": "已接受退款请求。" }, "401": { "description": "Unauthorized." }, "404": { "content": { "application/json": { "example": { "message": "Transaction ID not valid. Please check payment credentials. Otherwise, contact Xsolla support at support@xsolla.com." }, "schema": { "properties": { "message": { "description": "交易ID无效。请检查支付凭据。否则请发送邮件至support@xsolla.com与艾克索拉支持人员联系。", "type": "string" } }, "type": "object" } } }, "description": "未找到交易。" }, "422": { "content": { "application/json": { "example": { "message": "We are processing the refund request. This may take up to two business days." }, "schema": { "properties": { "message": { "description": "可能返回以下消息之一：\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.", "type": "string" } }, "type": "object" } } }, "description": "Unprocessable Entity (请求参数无效) 。" } }, "security": [ { "basicAuth": [] } ], "summary": "请求退款", "tags": [ "refund" ], "x-server": true } }, "/merchants/{merchant_id}/reports/transfers": { "get": { "description": "列示某个时间段内的所有出款。\n\n
\n

注意

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

\n
\n", "operationId": "get-payouts", "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": { "content": { "application/json": { "example": [ { "canceled": 0, "payout": { "currency": "USD", "date": "2014-01-03T00:00:00+04:00", "id": 1, "note": "12/05/2013 - 01/04/2014" }, "rate": 1, "transfer": { "currency": "USD", "date": "2014-01-05T00:00:00+04:00", "note": "004357" } } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有汇款", "tags": [ "reports" ], "x-admin": true, "x-server": true } }, "/merchants/{merchant_id}/token": { "post": { "description": "您可以通过任意用户参数创建令牌。您在获取令牌时发送这些参数并在成功支付后会收到发回的参数。令牌只能包含本文档中描述的参数或您预定义的参数。\n\n如果任何参数以不正确的格式或类型发送，将不会获得令牌。作为响应，您将收到422 \nHTTP代码，JSON正文中有相应的错误描述。在`extended_message`中，您将收到具体错误参数的相关信息。\n\n默认情况下，令牌有效期是24小时。如要更改该值，请联系您的客户成功经理或发送邮件至csm@xsolla.com。新值将对您公司在发布商帐户中创建的所有项目启用。\n\n
\n

注意

调用此API方法后获得的令牌只能用于授权其他请求。只有在集成了订阅产品的情况下才能使用此令牌打开支付UI。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token} ，其中{token}是收到的令牌。

如要进行测试，请使用以下URL： https://sandbox-secure.xsolla.com/paystation4/?token={token}。

\n
\n\n

\n\n
\n

注意

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

\n
\n", "operationId": "create-token", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/token" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT" }, "schema": { "properties": { "token": { "type": "string" } }, "type": "object" } } }, "description": "Created." }, "422": { "content": { "application/json": { "example": { "extended_message": { "global_errors": [], "property_errors": { "purchase.checkout.amount": [ "String value found, but a number is required" ] } }, "http_status_code": 422, "message": "JSON is not valid against json schema, please check documentation https://developers.xsolla.com/zh/api/v2/getting-started/#api_token_ui", "request_id": "cd72633" }, "schema": { "properties": { "extended_message": { "properties": { "global_errors": { "items": { "type": "string" }, "type": "array" }, "property_errors": { "description": "对象包含参数名称和错误描述。", "type": "object" } }, "type": "object" }, "http_status_code": { "type": "integer" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" } } }, "description": "Unprocessable Entity." } }, "security": [ { "basicAuth": [] } ], "summary": "创建令牌", "tags": [ "token" ], "x-server": true } }, "/projects/{project_id}/users/{user_id}/payment_accounts": { "get": { "description": "列示已保存的用户支付帐户。\n\n
\n

注：

在沙盒模式下，此API调用只适用于没有3-D Secure功能的测试银行卡。

\n
\n", "operationId": "get-saved-accounts", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/mode" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "id": 4612345, "name": "PP_saved_account", "payment_system": { "id": 24, "name": "PayPal" }, "type": "paypal" } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示已保存的支付帐户", "tags": [ "tokenization" ], "x-server": true } }, "/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}": { "delete": { "description": "删除已保存的支付帐户。\n\n
\n

注：

在沙盒模式下，此API调用只适用于没有3-D Secure功能的测试银行卡。

\n
\n\n

\n\n
\n

注：

您可以在沙盒模式下调用此API方法，方法是在请求中传入测试支付帐户的数据。关于沙盒模式访问和测试场景的详细信息，请参阅说明。

\n
\n", "operationId": "delete-saved-account", "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." } }, "security": [ { "basicAuth": [] } ], "summary": "删除已保存的支付帐户", "tags": [ "tokenization" ], "x-server": true } }, "/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}": { "post": { "description": "使用已保存的支付帐户收费。\n\n
\n

注：

在沙盒模式下，此API调用只适用于没有3-D Secure功能的测试银行卡。

\n
\n\n

\n\n
\n

注意

为使API调用正常工作，请配置一个2分钟的超时时间。

\n
\n", "operationId": "charge-with-saved-account", "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": { "content": { "application/json": { "example": { "transaction_id": 123458390 }, "schema": { "properties": { "transaction_id": { "type": "integer" } }, "type": "object" } } }, "description": "Created." }, "422": { "description": "Unprocessable Entity." } }, "security": [ { "basicAuth": [] } ], "summary": "通过已保存的帐户收费", "tags": [ "tokenization" ], "x-server": true } } }, "components": { "securitySchemes": { "basicAuth": { "description": "艾克索拉API使用基本认证。所有发送到API的请求必须包含`Authorization: Basic `头，其中``是按照Base64标准加密的`merchant_id:api_key`对。\n\n请前往[发布商帐户](https://publisher.xsolla.com/)找到这些参数：
\n关于使用API密钥的详细信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。", "scheme": "basic", "type": "http" } }, "parameters": { "merchant-id-path-param": { "description": "商户ID。", "in": "path", "name": "merchant_id", "required": true, "schema": { "type": "integer" } }, "project-id-path-param": { "description": "项目ID。", "in": "path", "name": "project_id", "required": true, "schema": { "type": "integer" } }, "transaction-id-path-param": { "description": "交易ID。", "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "integer" } }, "datetime-from-req": { "description": "开始日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：", "example": "2023-02-08", "in": "query", "name": "datetime_from", "required": true, "schema": { "format": "datetime", "type": "string" } }, "datetime-to-req": { "description": "结束日期，使用YYYY-MM-DD格式。如传入了以下任一参数，则此参数非必需：`datetime_from`和`datetime_to`之间的间隔不得超过92天。", "example": "2023-03-08", "in": "query", "name": "datetime_to", "required": true, "schema": { "format": "datetime", "type": "string" } }, "format": { "description": "数据格式。", "in": "path", "name": "format", "required": true, "schema": { "enum": [ "json", "csv", "xls" ], "type": "string" } }, "in-transfer-currency": { "description": "将所有财务数据转换为支付出账货币（默认使用支付入账货币）。如传入了以下任一参数，则此参数非必需：", "in": "query", "name": "in_transfer_currency", "required": true, "schema": { "type": "integer" } }, "show-total": { "description": "是否在报告中包含交易总额。仅适用于CSV格式导出，默认值为`true`。", "in": "query", "name": "show_total", "schema": { "type": "boolean" } }, "merchant-of-records": { "description": "在册商户。可以是`xsolla`、`merchant`或不指定。如果为`merchant`，则返回通过合作伙伴直接帐户进行的交易。如果为`xsolla`，则返回非通过合作伙伴直接帐户进行的交易。如未指定，则返回所有交易。", "in": "query", "name": "merchant_of_records", "required": false, "schema": { "enum": [ "xsolla", "merchant" ], "nullable": true, "type": "string", "x-enumDescriptions": { "merchant": "返回通过合作伙伴直接帐户进行的交易。", "xsolla": "返回非通过合作伙伴直接帐户进行交易。" } } }, "project-id-query-param": { "description": "项目ID。", "in": "query", "name": "project_id", "required": false, "schema": { "type": "integer" } }, "show-dry-run": { "description": "是否包括测试交易。", "in": "query", "name": "show_dry_run", "required": false, "schema": { "type": "boolean" } }, "transfer-id": { "description": "交易传输 ID。", "in": "query", "name": "transfer_id", "required": false, "schema": { "type": "integer" } }, "report-id": { "description": "财务报告 ID。", "in": "query", "name": "report_id", "required": false, "schema": { "type": "integer" } }, "offset": { "description": "元素编号，从该元素开始生成列表（从0开始数）。", "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, "limit-req": { "description": "页面上显示的交易数限制。如传入了此参数，则不必传入`datetime_from`和`datetime_to`参数。", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, "transaction-status": { "description": "交易状态。", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "done", "canceled", "error", "refunded" ], "type": "string" } }, "datetime-from": { "description": "日期范围的开始时间。", "in": "query", "name": "datetime_from", "required": false, "schema": { "format": "datetime", "type": "string" } }, "datetime-to": { "description": "日期范围的结束时间。", "in": "query", "name": "datetime_to", "required": false, "schema": { "format": "datetime", "type": "string" } }, "transaction-id": { "description": "交易ID。", "in": "query", "name": "transaction_id", "required": false, "schema": { "type": "integer" } }, "type": { "description": "在搜索结果中显示的交易类型：", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "all", "transferred", "canceled", "test" ], "type": "string", "x-enumDescriptions": { "all": "所有交易。", "canceled": "取消的交易（测试交易除外）。", "test": "测试交易。", "transferred": "成功的交易（测试交易除外）。" } } }, "phone": { "description": "用户电话号码（采用国际格式）。", "in": "query", "name": "phone", "required": false, "schema": { "type": "string" } }, "user-id-query-param": { "description": "存储在己侧的游戏内唯一用户ID。请确保传入现有用户ID。如遇到错误，请参阅[常见问题回答](/zh/doc/pay-station/references/faq/#faq_validation)。", "in": "query", "name": "user_id", "required": false, "schema": { "type": "string" } }, "user-name": { "description": "用户名。", "in": "query", "name": "user_name", "required": false, "schema": { "type": "string" } }, "user-custom": { "description": "用户标识的自定义参数。", "in": "query", "name": "user_custom", "required": false, "schema": { "type": "string" } }, "email": { "description": "用户电子邮件。", "in": "query", "name": "email", "required": false, "schema": { "maxLength": 100, "type": "string" } }, "external-id": { "description": "游戏中的交易ID。值对于每个用户付款必须唯一。", "in": "query", "name": "external_id", "required": false, "schema": { "type": "string" } }, "order-id": { "description": "订单ID。您可以使用它调用[获取订单](/zh/api/shop-builder/operation/get-order/) API方法。", "example": 1234, "in": "query", "name": "order_id", "required": false, "schema": { "type": "integer" } }, "limit": { "description": "页面上元素数量的限制。", "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, "status": { "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/status.enum" } }, "legal-entity-id": { "description": "开发者法律实体ID。", "in": "query", "name": "legal_entity_id", "required": false, "schema": { "type": "integer" } }, "payout-status": { "description": "出款状态。", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "hold", "ready", "paid" ], "type": "string", "x-enumDescriptions": { "hold": "正在等待请求处理。", "paid": "出款完成。", "ready": "出款进行中。" } } }, "user-id-path-param": { "description": "存储在己侧的游戏内唯一用户ID。请确保传入现有用户ID。如遇到错误，请参阅[常见问题回答](/zh/doc/pay-station/references/faq/#faq_validation)。", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } }, "mode": { "description": "设置为`sandbox`以测试支付流程。进行真实支付时请移除此参数。", "in": "query", "name": "mode", "required": false, "schema": { "type": "string" } }, "type-path-param": { "description": "支付帐户类型。", "in": "path", "name": "type", "required": true, "schema": { "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" ], "type": "string", "x-enumDescriptions": { "alipayplus_boost": "Boost。", "alipayplus_cn": "支付宝。", "alipayplus_dana": "DANA。", "alipayplus_gcash": "GCash。", "alipayplus_hk": "Alipay HK。", "alipayplus_kplus": "K PLUS.", "alipayplus_maya": "Maya。", "alipayplus_rabbitlinepay": "Rabbit LINE pay。", "alipayplus_tng": "Touch 'n Go。", "alipayplus_truemoney": "TrueMoney Wallet。", "amazon": "Amazon Pay。", "card": "银行卡。", "klarna": "Klarna。保存支付帐户只适用于美国、英国、瑞典、德国、奥地利、挪威、芬兰、丹麦、荷兰。", "mercadopago": "Mercado Pago（包括Mercado Pago Connect）", "nupay": "NuPay.", "paidy": "Paidy.", "paypal": "PayPal。", "paysafecard_eu": "Paysafecard（欧盟）。", "paysafecard_us": "Paysafecard（美国）。", "skrill": "Skrill Digital Wallet。", "softbank_au": "au Easy Payment。", "softbank_docomo": "Docomo。", "softbank_paypay": "PayPay。", "softbank_softbank2": "SoftBank。", "softbank_ymobile": "Y!mobile。", "toss": "Toss Wallet。" } } }, "account-id-path-param": { "description": "艾克索拉数据库中已保存的帐户的ID。", "in": "path", "name": "account_id", "required": true, "schema": { "type": "integer" } } }, "schemas": { "empty-body": { "description": "要让API调用正常工作，请求正文必需为空。", "nullable": true, "type": "object" }, "status.enum": { "description": "交易状态。", "enum": [ "created", "processing", "review", "error", "done", "awaitingRefund", "refunded", "canceled", "partiallyRefunded" ], "type": "string", "x-enumDescriptions": { "awaitingRefund": "交易正在等待退款决定。用户申请退款后，艾克索拉客户支持将手动处理该申请并作出决定。", "canceled": "有两种可能场景：\n - 交易被支付系统侧取消。例如用户帐户中资金不足。\n - 已对用户退款。", "created": "用户发起了交易但交易尚未被处理。", "done": "交易已成功处理。", "error": "处理交易时发生了错误。此类支付可通过联系艾克索拉客户支持进行退款。", "partiallyRefunded": "用户收到了部分退款。", "processing": "交易正在处理中。", "refunded": "退款已退回用户的艾克索拉余额。", "review": "交易处理被反欺诈系统暂停，当前正对交易进行额外验核。" } }, "custom_parameters": { "description": "此对象包含配置防欺诈筛选条件的参数。参数列表如下所示。要添加自定义参数，请联系您的客户成功经理或发送邮件至[csm@xsolla.com](mailto:csm@xsolla.com)。", "properties": { "active_date": { "description": "上一次出现日期（按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式）。", "type": "string" }, "additional_verification": { "description": "玩家是否使用了帐户验证流程。", "type": "boolean" }, "character_customized": { "description": "玩家是否对角色进行了自定义。", "type": "boolean" }, "chat_activity": { "description": "玩家是否使用了聊天功能。", "type": "boolean" }, "completed_tasks": { "description": "完成的任务/目标数。", "type": "integer" }, "forum_activity": { "description": "玩家是否使用了论坛功能。", "type": "boolean" }, "items_used": { "description": "玩家是否使用了购买的游戏装备。", "type": "boolean" }, "karma_points": { "description": "玩家的贡献/业力。", "type": "integer" }, "last_change_password_date": { "description": "上一次出现日期（按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式）。", "type": "string" }, "non_premium_currency": { "description": "非高级货币数量。", "format": "float", "type": "number" }, "notifications_enabled": { "description": "玩家是否启用了通知。", "type": "boolean" }, "profile_completed": { "description": "玩家在帐户资料中是否添加了其它信息。", "type": "boolean" }, "profile_image_added": { "description": "玩家是否上传了简介头像。", "type": "boolean" }, "pvp_activity": { "description": "玩家是否参与了PvP（玩家对战）战斗。", "type": "boolean" }, "registration_date": { "description": "上一次出现日期（按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式）。", "type": "string" }, "session_time": { "description": "上一次出现日期（按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式）。", "type": "string" }, "social_networks_added": { "description": "玩家是否有关联的社交媒体帐户资料。", "type": "boolean" }, "total_bans": { "description": "玩家在聊天/论坛中被禁言的次数。", "type": "integer" }, "total_characters": { "description": "游戏角色数。", "type": "integer" }, "total_clans": { "description": "玩家所属的家族数。", "type": "integer" }, "total_friends": { "description": "好友数。", "type": "integer" }, "total_game_events": { "description": "玩家参与的游戏事件数。", "type": "integer" }, "total_gifts": { "description": "玩家发出/收到的游戏礼物数。", "type": "integer" }, "total_hours": { "description": "游戏总时数。", "type": "integer" }, "total_inventory_value": { "description": "库存总值（以游戏货币为单位）。", "format": "float", "type": "number" }, "total_sum": { "description": "付款总额。", "format": "float", "type": "number" }, "tutorial_completed": { "description": "玩家是否完成了游戏教程。", "type": "boolean" }, "unlocked_achievements": { "description": "未解锁的通关数。", "type": "integer" }, "user_level": { "description": "玩家的等级、口碑或排名。", "type": "integer" }, "win_rate": { "description": "赢率。", "type": "integer" } }, "type": "object" }, "is_lootbox": { "default": false, "description": "该商品是否为宝箱。", "type": "boolean" }, "subscription": { "description": "带有订阅相关数据的对象。", "properties": { "available_plans": { "description": "包含订阅套餐相关数据的数组。只有这些套餐会显示在支付用户界面中。", "items": { "type": "string" }, "type": "array" }, "currency": { "description": "购买计划的货币，以此币种进行所有计算。", "type": "string" }, "operation": { "description": "此操作的类型应用于用户订阅计划。要更改订阅计划，请传入`change_plan`值。需在`purchase.subscription.plan_id`参数中指定新计划的ID。", "type": "string" }, "plan_id": { "description": "订阅计划的外部ID。可在发布商帐户的**订阅 > 订阅计划**中找到。", "type": "string" }, "product_id": { "description": "产品ID。", "type": "string" }, "trial_days": { "description": "试用期，以天为单位。", "type": "integer" } }, "type": "object" }, "purchase": { "description": "带有购买相关数据的对象。", "properties": { "is_lootbox": { "$ref": "#/components/schemas/is_lootbox" }, "subscription": { "$ref": "#/components/schemas/subscription" } }, "type": "object" }, "cancel_url": { "description": "用户在完成支付前关闭支付UI时的重定向页面URL。仅在通过`settings.​ui.​desktop.​header`或`settings.​ui.​mobile`对象配置了支付UI关闭按钮时生效。若配置了关闭按钮但未在此参数中传入URL，则使用`settings.return_url`参数中传入的URL。", "type": "string" }, "currency": { "description": "首选支付币种。参照[ISO 4217](https://developers.xsolla.com/zh/doc/pay-station/references/supported-currencies/)标准的三字母货币代码。", "type": "string" }, "external_id": { "description": "游戏中的交易ID。该值对每个用户支付必须唯一。详细信息请参阅文档。", "type": "string" }, "language": { "description": "界面语言。2字母（小写字母）[语言代码](https://developers.xsolla.com/zh/doc/pay-station/features/localization/)。", "type": "string" }, "mode.settings": { "description": "设置为`sandbox`值以测试支付流程。请使用*https://sandbox-secure.xsolla.com*来访问测试支付UI。", "type": "string" }, "payment_method": { "description": "付款方式ID。", "type": "integer" }, "payment_widget": { "description": "支付小部件。可以是 `paybycash` 或 `giftcard`。如果参数已设置，用户将分别重定向到 Pay by Cash 或 Gift Cards 小部件。", "enum": [ "paybycash", "giftcard" ], "type": "string" }, "project_id": { "description": "游戏的艾克索拉ID。可以在发布商帐户中找到该ID。", "type": "integer" }, "redirect_policy": { "description": "重定向政策设置（对象）。", "properties": { "delay": { "description": "延迟时间（单位为秒），经过该时间后用户将自动重定向至返回URL。", "type": "integer" }, "manual_redirection_action": { "description": "由用户点击关闭按钮或**返回游戏**按钮触发的支付中心行为。可以是`redirect`（默认）或`postmessage`。如果设置为`redirect`，则用户将被重定向至令牌中传入的URL或发布商帐户中指定的URL。如果设置为`postmessage`，则用户留在原页面。点击关闭按钮发起发送`close`事件，点击**返回游戏**则发起发送`return`事件。", "enum": [ "redirect", "postmessage" ], "type": "string" }, "redirect_button_caption": { "description": "手动重定向按钮上的文字。", "type": "string" }, "redirect_conditions": { "description": "将用户重定向至返回URL的支付状态。可以是`none`, `successful`, `successful_or_canсeled`或`any`。", "enum": [ "none", "successful", "successful_or_canceled", "any" ], "type": "string" }, "show_redirect_countdown": { "default": false, "description": "是否在支付状态页面显示重定向倒计时。倒计时时长由`settings.redirect_policy.delay`参数的值决定。", "type": "boolean" }, "status_for_manual_redirection": { "description": "显示让用户重定向至返回URL按钮的支付状态。可以是`none`, `successful`, `successful_or_canсeled`或`any`。", "enum": [ "none", "successful", "successful_or_canceled", "any" ], "type": "string" } }, "type": "object" }, "return_url": { "description": "用户付款后重定向到的页面的URL。关于配置重定向的详细信息，请参阅文档。", "type": "string" }, "alternative_first_screen": { "description": "支付中心界面打开时的备选展示方式。例如，可优先显示某些支付方式。\n\n当设置为`apple-pay`时，用户将看到Apple Pay按钮作为首选支付选项，并可通过链接查看其他支付方式列表。此逻辑不适用于Android设备。\n", "enum": [ "apple-pay" ], "type": "string" }, "ap_quick_payment_button": { "description": "是否在支持设备的支付UI顶部显示通过Apple Pay快速支付的按钮。默认为`true`。如为`false`，则根据[PayRank](/zh/doc/pay-station/how-to/how-to-manage-top-payment-methods/)算法在支付方式列表中显示Apple Pay。\n\n
\n

注：

在Android设备和其他不支持Apple Pay支付的设备上，无论该参数值如何，此支付方式都将在可用支付方式列表中隐藏。

\n
\n", "type": "boolean" }, "components": { "description": "带有模块菜单设置相关数据的对象。", "properties": { "subscriptions": { "description": "带有订阅模块设置相关数据的对象。", "properties": { "hidden": { "description": "在菜单中显示还是隐藏“管理订阅”页面。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" }, "virtual_currency": { "description": "带有虚拟货币模块设置相关数据的对象。", "properties": { "custom_amount": { "description": "是否允许在支付UI中输入任意数量的虚拟货币。", "type": "boolean" }, "hidden": { "description": "在菜单中显示还是隐藏“管理订阅”页面。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" }, "virtual_items": { "description": "带有虚拟物品模块设置相关数据的对象。", "properties": { "hidden": { "description": "在菜单中显示还是隐藏“管理订阅”页面。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" }, "selected_group": { "description": "用户打开虚拟物品选项卡时将会选择的组。", "type": "string" }, "selected_item": { "description": "用户打开虚拟物品选项卡时将会选择的物品。物品 SKU 应发送至此处。", "type": "string" } }, "type": "object" } }, "type": "object" }, "currency_format": { "description": "设置为`code`以在支付UI中显示三字母的[ISO 4217](https://developers.xsolla.com/zh/doc/pay-station/references/supported-currencies/)货币代码。默认显示货币符号而不是三字母货币代码。", "type": "string" }, "close_button_icon": { "description": "支付UI中的**关闭**按钮图标。", "enum": [ "arrow", "cross" ], "type": "string", "x-enumDescriptions": { "arrow": "支付UI页眉左侧的**←**图标。", "cross": "支付UI页眉右侧的**×**图标。" } }, "header.desktop": { "description": "带有标题设置相关数据的对象。", "properties": { "close_button": { "default": false, "description": "是否显示支付UI关闭按钮。用户点击该按钮后，支付UI关闭并重定向至`settings.cancel_url`参数指定的URL。若未在此参数传入URL，则使用`settings.return_url`参数传入的URL。", "type": "boolean" }, "close_button_icon": { "$ref": "#/components/schemas/close_button_icon" }, "is_visible": { "description": "标题在支付UI上是否可见。", "type": "boolean" }, "type": { "description": "如何显示标题。不能为`compact`（隐藏项目名称和用户ID）或`normal`（默认）。", "enum": [ "compact", "normal" ], "type": "string" }, "visible_logo": { "description": "如为`true`，Logo在标题中显示。要上传图片，请在[发布商帐户](https://publisher.xsolla.com/)中打开您的项目，然后前往**支付中心 > 设置**部分。", "type": "boolean" }, "visible_name": { "description": "标题中是否显示项目名称。", "type": "boolean" }, "visible_purchase": { "description": "是否在标题中显示购买描述（`purchase.description.value`）。默认为`true`。", "type": "boolean" } }, "type": "object" }, "subscription_list.desktop": { "description": "带有订阅列表设置相关数据的对象。", "properties": { "description": { "description": "可以在此传递订阅相关的任意文本。文本将显示在订阅计划列表的上方。", "type": "string" }, "display_local_price": { "description": "如为`true`且如果用户的当地货币与订阅计划的货币不同，则用户将看到两种价格：以当地货币和基础货币标价的价格。", "type": "boolean" } }, "type": "object" }, "desktop.ui": { "description": "带有对桌面版本有效的界面设置相关数据的对象。", "properties": { "header": { "$ref": "#/components/schemas/header.desktop" }, "subscription_list": { "$ref": "#/components/schemas/subscription_list.desktop" } }, "type": "object" }, "gp_quick_payment_button": { "description": "Google Pay支付方式的显示方式。如为`true`，则通过Google Pay快速支付的按钮在支付UI顶部显示，无论用户使用的是什么设备或浏览器。如为`false`，则根据[PayRank](/zh/doc/pay-station/how-to/how-to-manage-top-payment-methods/)算法在支付方式列表中显示Google Pay。如果未传递此参数，Google Pay将显示在支付UI的顶部，适用于所有用户设备和除Safari外的浏览器。在Safari浏览器中，它会显示在支付方式列表中。", "type": "boolean" }, "header.ui": { "properties": { "visible_virtual_currency_balance": { "description": "此元素是否可在支付UI上隐藏。默认为`true`。", "type": "boolean" } }, "type": "object" }, "is_cart_open_by_default": { "description": "在支付UI中显示购物车商品列表和结算明细。如为`true`，将以展开视图显示信息。如为`false`（默认情况）或未传递参数，将以折叠视图显示信息。", "type": "boolean" }, "is_independent_windows": { "description": "是否将用户从嵌入式启动器浏览器(WebView)跳转到其默认的浏览器来进行购买。默认为`false`。", "type": "boolean" }, "is_language_selector_hidden": { "description": "是否在支付页面隐藏语言选择器。如为`false`（默认），将显示选择器。", "type": "boolean" }, "is_payment_methods_list_mode": { "description": "打开支付UI时是否显示在该用户所在国家/地区可用的支付方式。如为`false`（默认），将显示在`settings.payment_method`参数中传入的支付方式或[PayRank算法](https://developers.xsolla.com/zh/solutions/payments/payment-ui-management/top-payment-methods-management/)选择的支付方式。", "type": "boolean" }, "is_prevent_external_link_open": { "description": "是否禁用将链接重定向至外部资源。默认为`false`。点击外部链接时，将通过`postMessage`机制发送`external-link-open`事件。重定向链接的地址在`url`参数中传递。", "type": "boolean" }, "is_search_field_hidden": { "description": "是否在支付UI中显示支付方式搜索栏。如为`true`，则隐藏搜索栏，默认为`false`。", "type": "boolean" }, "is_show_close_widget_warning": { "description": "关闭支付页面前鼠标悬停在 **×**图标时是否显示交易正在处理中的警告。如传入`false`，或未传入参数，则不显示警告。默认为`true`。", "type": "boolean" }, "is_three_ds_independent_windows": { "default": false, "description": "是否在新浏览器窗口中打开3-D Secure检查。如果您的设置强制执行内容安全政策(CSP)，请设置为`true`。", "type": "boolean" }, "layout": { "description": "支付UI主要元素的位置。您可以在游戏内打开支付UI和/或交换订单信息和支付方式信息列的位置。详细信息请参阅[自定义说明](https://developers.xsolla.com/zh/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_layout)。", "enum": [ "embed", "column_reverse", "embed_column_reverse" ], "type": "string" }, "mobile.ui": { "properties": { "header": { "properties": { "close_button": { "default": false, "description": "是否在移动端版本显示支付UI关闭按钮。用户点击该按钮后，支付UI关闭并重定向至`settings.cancel_url`参数指定的URL。若未在此参数传入URL，则使用`settings.return_url`参数传入的URL。", "type": "boolean" }, "close_button_icon": { "$ref": "#/components/schemas/close_button_icon" } }, "type": "object" } }, "type": "object" }, "mode.ui": { "description": "支付UI的显示模式，用于管理已保存的支付方式。可设置为`user_account`或省略。在此模式下，用户只能更改语言、添加新支付方式和删除现有支付方式。\n\n
\n

注：

传入此参数后，跳转按钮将不会显示。若要在用户保存支付方式后进行重定向，请配置自动重定向。

\n
\n", "type": "string" }, "theme.ui": { "description": "支付UI主题。可以是`63295a9a2e47fab76f7708e1`（浅色主题（默认）），或`63295aab2e47fab76f7708e3`（深色主题）。您也可以[创建自定义主题](https://developers.xsolla.com/zh/doc/pay-station/features/ui-theme-customization/#pay_station_ui_theme_customization_in_token)，然后在此参数中传入其ID。", "enum": [ "63295a9a2e47fab76f7708e1", "63295aab2e47fab76f7708e3" ], "type": "string" }, "payment_accounts_enable": { "properties": { "enable": { "description": "指定是否在支付UI中显示前往支付方式编辑页面的铅笔图标。默认为`true`。", "type": "boolean" }, "order": { "description": "该部分在支付UI下拉列表中的位置。如传入了`settings.ui.user_account.payment_accounts.enable`，则该属性为必需。", "minimum": 1, "type": "integer" } }, "type": "object" }, "user_account": { "description": "对象以及有关用户账号的数据。", "properties": { "payment_accounts": { "allOf": [ { "description": "**保存的支付方式**部分。" }, { "$ref": "#/components/schemas/payment_accounts_enable" } ] } }, "type": "object" }, "ui": { "description": "带有界面设置相关数据的对象。", "properties": { "alternative_first_screen": { "$ref": "#/components/schemas/alternative_first_screen" }, "apple_pay_quick_payment_button": { "$ref": "#/components/schemas/ap_quick_payment_button" }, "components": { "$ref": "#/components/schemas/components" }, "currency_format": { "$ref": "#/components/schemas/currency_format" }, "desktop": { "$ref": "#/components/schemas/desktop.ui" }, "gp_quick_payment_button": { "$ref": "#/components/schemas/gp_quick_payment_button" }, "header": { "$ref": "#/components/schemas/header.ui" }, "is_cart_open_by_default": { "$ref": "#/components/schemas/is_cart_open_by_default" }, "is_independent_windows": { "$ref": "#/components/schemas/is_independent_windows" }, "is_language_selector_hidden": { "$ref": "#/components/schemas/is_language_selector_hidden" }, "is_payment_methods_list_mode": { "$ref": "#/components/schemas/is_payment_methods_list_mode" }, "is_prevent_external_link_open": { "$ref": "#/components/schemas/is_prevent_external_link_open" }, "is_search_field_hidden": { "$ref": "#/components/schemas/is_search_field_hidden" }, "is_show_close_widget_warning": { "$ref": "#/components/schemas/is_show_close_widget_warning" }, "is_three_ds_independent_windows": { "$ref": "#/components/schemas/is_three_ds_independent_windows" }, "layout": { "$ref": "#/components/schemas/layout" }, "mobile": { "$ref": "#/components/schemas/mobile.ui" }, "mode": { "$ref": "#/components/schemas/mode.ui" }, "theme": { "$ref": "#/components/schemas/theme.ui" }, "user_account": { "$ref": "#/components/schemas/user_account" } }, "type": "object" }, "settings": { "description": "为用户配置支付流程和支付UI的设置。", "properties": { "cancel_url": { "$ref": "#/components/schemas/cancel_url" }, "currency": { "$ref": "#/components/schemas/currency" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "language": { "$ref": "#/components/schemas/language" }, "mode": { "$ref": "#/components/schemas/mode.settings" }, "payment_method": { "$ref": "#/components/schemas/payment_method" }, "payment_widget": { "$ref": "#/components/schemas/payment_widget" }, "project_id": { "$ref": "#/components/schemas/project_id" }, "redirect_policy": { "$ref": "#/components/schemas/redirect_policy" }, "return_url": { "$ref": "#/components/schemas/return_url" }, "ui": { "$ref": "#/components/schemas/ui" } }, "required": [ "project_id" ], "type": "object" }, "age.user": { "description": "用户年龄。", "type": "integer" }, "attributes.user": { "description": "带有用户属性相关数据的对象，用于筛选物品列表。应当是带键值对的有效JSON哈希。", "type": "object" }, "country.user": { "properties": { "allow_modify": { "description": "用户是否可以更改支付UI上的国家/地区。如果令牌中传入了`country.value`值，则值默认为`false`。", "type": "boolean" }, "value": { "description": "使用[ISO 3166-1 alpha-2标准](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)规定的2字母组合表示国家/地区。", "type": "string" } }, "type": "object" }, "email.user": { "description": "`user.email`对象是反欺诈模型的必要部分，有助于提高接受率。同时它也是艾克索拉和支付系统的要求。如果未传入该参数，支付页面将显示输入邮箱必填字段。购买凭证将发送至在该参数中传入的或在支付页面上输入的邮箱地址。", "properties": { "allow_modify": { "description": "用户是否可在支付UI中输入其邮箱。如令牌中传入了`user.email.value`参数，该值默认为`false`。", "type": "boolean" }, "value": { "description": "用户电子邮箱。必须符合[RFC 822](https://www.w3.org/Protocols/rfc822/#z8)协议标准。", "maxLength": 100, "type": "string" } }, "required": [ "value" ], "type": "object" }, "id.user": { "properties": { "value": { "description": "存储在己侧的游戏内唯一用户ID。请确保传入现有用户ID。如遇到错误，请参阅[常见问题回答](/zh/doc/pay-station/references/faq/#faq_validation)。", "type": "string" } }, "required": [ "value" ], "type": "object" }, "is_legal.user": { "description": "用户是否为法律实体。", "type": "boolean" }, "legal": { "description": "包含法律实体详细信息的对象。", "properties": { "address": { "description": "完整法定地址。", "type": "string" }, "country": { "description": "公司所在国家/地区。参照[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)标准的两个大写字母表示的国家/地区代码。", "type": "string" }, "name": { "description": "完整法定名称。", "type": "string" }, "vat_id": { "description": "个人纳税人识别号。", "type": "string" } }, "type": "object" }, "legal.user": { "allOf": [ { "description": "包含法律实体详细信息的对象。如果`user.is_legal`为`true`，则对象及其所有参数为必需。" }, { "$ref": "#/components/schemas/legal" } ] }, "name.user": { "properties": { "allow_modify": { "description": "用户是否可在支付UI中输入其名字。如令牌中传入了`user.name.value`参数，该值默认为`false`。", "type": "boolean" }, "value": { "description": "用户昵称。", "type": "string" } }, "type": "object" }, "phone.user": { "nullable": true, "properties": { "value": { "description": "电话号码。", "type": "string" } }, "type": "object" }, "public_id.user": { "properties": { "value": { "description": "唯一识别用户并为用户所熟知的参数，与用户ID（电子邮件、昵称等）不同。此参数在可以在游戏商店以外进行购买时使用（如现金售货亭中的游戏按键）。", "type": "string" } }, "type": "object" }, "steam_id.user": { "properties": { "value": { "description": "Steam ID。", "type": "string" } }, "type": "object" }, "tracking_id.user": { "properties": { "value": { "description": "唯一用户ID — 用于营销活动。可包含数字和英文字符。", "maxLength": 32, "minLength": 32, "type": "string" } }, "type": "object" }, "utm.user": { "description": "对象包含描述流量特性的数据。", "properties": { "utm_campaign": { "description": "活动标题。该参数应当包含直译的活动标题或者翻译为英文的活动标题。", "type": "string" }, "utm_content": { "description": "该活动的实质。", "type": "string" }, "utm_medium": { "description": "流量渠道（内容关联广告、媒体广告、邮件列表消息）。", "type": "string" }, "utm_source": { "description": "流量来源。", "type": "string" }, "utm_term": { "description": "活动关键词。在指定该参数的情况下，统计数据是基于在确定您的广告活动的目标对象过程中所使用的关键词数据而生成的，而不是基于检索项数据。在Google Analytics中，`utm_term`标签的内容成为包含检索项的综合报告中的一部分。", "type": "string" } }, "type": "object" }, "user": { "description": "带用户相关数据的对象。", "properties": { "age": { "$ref": "#/components/schemas/age.user" }, "attributes": { "$ref": "#/components/schemas/attributes.user" }, "country": { "$ref": "#/components/schemas/country.user" }, "email": { "$ref": "#/components/schemas/email.user" }, "id": { "$ref": "#/components/schemas/id.user" }, "is_legal": { "$ref": "#/components/schemas/is_legal.user" }, "legal": { "$ref": "#/components/schemas/legal.user" }, "name": { "$ref": "#/components/schemas/name.user" }, "phone": { "$ref": "#/components/schemas/phone.user" }, "public_id": { "$ref": "#/components/schemas/public_id.user" }, "steam_id": { "$ref": "#/components/schemas/steam_id.user" }, "tracking_id": { "$ref": "#/components/schemas/tracking_id.user" }, "utm": { "$ref": "#/components/schemas/utm.user" } }, "required": [ "id" ], "type": "object" }, "token": { "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" } } }, "properties": { "custom_parameters": { "$ref": "#/components/schemas/custom_parameters" }, "purchase": { "$ref": "#/components/schemas/purchase" }, "settings": { "$ref": "#/components/schemas/settings" }, "user": { "$ref": "#/components/schemas/user" } }, "type": "object" }, "mock_code": { "description": "在沙盒模式下测试PayPal支付处理时希望重现的错误代码。仅当传入了`\"mode\":\"sandbox\"`参数时才能正确工作。", "enum": [ 1002, 1015, 1039, 1046, 1057, 1089, 1201, 1203, 1801, 1803, 2031, 3006, 3031, 5004 ], "type": "integer" } }, "requestBodies": { "charge-with-saved-account": { "content": { "application/json": { "example": { "purchase": { "description": { "value": "currency purchase" }, "virtual_currency": { "quantity": 100 } }, "settings": { "currency": "USD", "external_id": "ext123", "mode": "sandbox" }, "user": { "ip": "111.11.11.11", "legal": { "address": "17 Crown Street London SW2 0JW United Kingdom", "country": "GB", "name": "My Awesome Company", "vat_id": "GB111111111" }, "name": "John Smith" } }, "schema": { "properties": { "custom_parameters": { "$ref": "#/components/schemas/custom_parameters" }, "purchase": { "description": "带有购买相关数据的对象。", "properties": { "checkout": { "description": "带有结账参数相关数据的对象。", "properties": { "amount": { "description": "购买金额。", "format": "float", "type": "number" }, "currency": { "description": "购买币种。参照[ISO 4217](https://developers.xsolla.com/zh/doc/pay-station/references/supported-currencies/)标准的三字母货币代码。", "type": "string" } }, "type": "object" }, "description": { "properties": { "value": { "maxLength": 4000, "type": "string" } }, "type": "object" }, "virtual_currency": { "description": "带有虚拟货币相关数据的对象。", "properties": { "quantity": { "description": "使用虚拟货币购买的数量。", "format": "float", "type": "number" } }, "type": "object" } }, "type": "object" }, "settings": { "description": "带有购买设置相关数据的对象。", "properties": { "currency": { "$ref": "#/components/schemas/currency" }, "external_id": { "$ref": "#/components/schemas/external_id" }, "mock_code": { "$ref": "#/components/schemas/mock_code" }, "mode": { "description": "设置`sandbox`值以测试支付流程。对于真实支付，应移除此参数。", "type": "string" } }, "type": "object" }, "user": { "description": "带用户相关数据的对象。", "properties": { "ip": { "description": "用户IP。", "type": "string" }, "legal": { "$ref": "#/components/schemas/legal" }, "name": { "description": "用户名。", "type": "string" } }, "required": [ "ip" ], "type": "object" } }, "type": "object" } } }, "required": true } } } }