{ "components": { "parameters": { "array-group-id-query-param": { "description": "计划关联的组ID列表。", "in": "query", "name": "group_id[]", "schema": { "items": { "type": "string" }, "type": "array" } }, "array-plan-id-query-param": { "description": "订阅计划ID列表。", "in": "query", "name": "plan_id[]", "schema": { "items": { "type": "integer" }, "type": "array" } }, "array-product-id-query-param": { "description": "计划关联的产品ID列表。", "in": "query", "name": "product_id[]", "schema": { "items": { "type": "integer" }, "type": "array" } }, "array-project-id-query-param": { "description": "项目ID列表。", "in": "query", "name": "project_id[]", "schema": { "items": { "type": "integer" }, "type": "array" } }, "campaign-id-path-param": { "description": "优惠券活动ID。", "in": "path", "name": "campaign_id", "required": true, "schema": { "type": "integer" } }, "code-path-param": { "description": "优惠券代码。", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, "datetime-from-query-param": { "description": "示例日期。查找在请求日期之后创建的订阅。", "in": "query", "name": "datetime_from", "schema": { "format": "datetime", "type": "string" } }, "datetime-from-query-param2": { "description": "日期范围的开始时间。", "in": "query", "name": "datetime_from", "schema": { "format": "datetime", "type": "string" } }, "datetime-to-query-param": { "description": "示例日期。查找在请求日期之后创建的订阅。", "in": "query", "name": "datetime_to", "schema": { "format": "datetime", "type": "string" } }, "datetime-to-query-param2": { "description": "日期范围的结束时间。", "in": "query", "name": "datetime_to", "schema": { "format": "datetime", "type": "string" } }, "external-id-query-param": { "description": "外部计划标识符。", "in": "query", "name": "external_id", "schema": { "type": "string" } }, "group-id-query-param": { "description": "这些计划与之连接的组的 ID。", "in": "query", "name": "group_id", "schema": { "type": "string" } }, "limit-query-param": { "description": "页面上元素数量的限制。", "in": "query", "name": "limit", "required": true, "schema": { "type": "integer" } }, "merchant-id-path-param": { "description": "商户ID。", "in": "path", "name": "merchant_id", "required": true, "schema": { "type": "integer" } }, "offset-query-param": { "description": "元素编号，从该元素开始生成列表（从0开始数）。", "in": "query", "name": "offset", "schema": { "type": "integer" } }, "plan-id-path-param": { "description": "计划 ID。", "in": "path", "name": "plan_id", "required": true, "schema": { "type": "integer" } }, "plan-id-query-param": { "description": "订阅计划ID。", "in": "query", "name": "plan_id", "schema": { "type": "integer" } }, "product-id-path-param": { "description": "这些计划与之连接的产品的 ID。", "in": "path", "name": "product_id", "required": true, "schema": { "type": "integer" } }, "product-id-query-param": { "description": "这些计划与之连接的产品的 ID。", "in": "query", "name": "product_id", "schema": { "type": "integer" } }, "project-id-path-param": { "description": "项目ID。", "in": "path", "name": "project_id", "required": true, "schema": { "type": "integer" } }, "promotion-id-path-param": { "description": "促销活动 ID。", "in": "path", "name": "promotion_id", "required": true, "schema": { "type": "integer" } }, "query-query-param": { "description": "搜索查询（搜索name.en（默认区域位置））。", "in": "query", "name": "query", "schema": { "type": "string" } }, "status-id-query-param": { "description": "交易状态。", "in": "query", "name": "status", "schema": { "enum": [ "done", "fail" ], "type": "string", "x-enumDescriptions": { "done": "支付处理成功。", "fail": "支付未成功处理或发起了退款。" } } }, "status-query-param-array": { "description": "状态。", "in": "query", "name": "status[]", "schema": { "items": { "enum": [ "active", "canceled", "non_renewing" ], "type": "string" }, "type": "array" } }, "subscription-id-path-param": { "description": "订阅ID。", "in": "path", "name": "subscription_id", "required": true, "schema": { "type": "integer" } }, "subscription-id-query-param": { "description": "订阅ID。", "in": "query", "name": "subscription_id", "schema": { "type": "integer" } }, "user-id-path-param": { "description": "用户ID。", "in": "path", "name": "user_id", "required": true, "schema": { "type": "string" } }, "user-id-query-param": { "description": "用户ID。", "in": "query", "name": "user_id", "schema": { "type": "string" } } }, "schemas": { "BillingAccountResponse": { "properties": { "id": { "example": "12345", "type": "integer" }, "name": { "example": "PP_saved_account", "nullable": true, "type": "string" }, "payment_system": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentSystemResponse" } ] }, "type": { "example": "paypal", "nullable": true, "type": "string" } }, "required": [ "id" ], "type": "object" }, "BillingAccountsListResponse": { "properties": { "items": { "default": [], "items": { "$ref": "#/components/schemas/BillingAccountResponse" }, "type": "array" } }, "type": "object" }, "Campaign": { "properties": { "campaign_code": { "description": "优惠券活动名称。", "type": "string" }, "campaign_names": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "包含优惠券活动本地化名称的对象。" } ] }, "campaign_redeems_count_for_user": { "description": "每个用户在一个优惠券活动中最多可兑换的优惠券数量。如传入`null`，则可兑换数量不限。", "type": "integer" }, "expiration_date": { "description": "按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)规定的`YYYY-MM-DD’T’HH:MM:SS`格式的活动到期日。", "format": "datetime", "type": "string" }, "project_id": { "description": "项目ID。", "type": "integer" }, "redeems_count": { "description": "可兑换优惠券的最大数量。如传入`null`，则数量不限。", "type": "integer" }, "redeems_count_for_user": { "description": "每个用户最多可兑换的优惠券数量。如传入`null`，则可兑换数量不限。", "type": "integer" }, "subscription_coupon": { "description": "奖励中包含订阅参数的对象。", "properties": { "plan_id": { "description": "订阅计划ID。", "type": "integer" }, "product_id": { "description": "订阅产品ID。", "type": "integer" }, "trial_period": { "description": "以天为单位的试用期长度。", "type": "integer" } }, "required": [ "plan_id", "product_id", "trial_period" ], "type": "object" }, "virtual_currency_amount": { "description": "奖励中的虚拟货币数。", "format": "float", "type": "number" }, "virtual_items": { "description": "奖励中的虚拟物品参数数组。", "properties": { "quantity": { "description": "虚拟物品数量。", "type": "integer" }, "sku": { "description": "虚拟物品SKU。", "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" } }, "type": "object" }, "ChangePlanPaymentDetailsResponse": { "properties": { "charge": { "$ref": "#/components/schemas/Charge2" }, "payment_details": { "$ref": "#/components/schemas/PaymentDetails" }, "period": { "$ref": "#/components/schemas/Period2" }, "plan_description": { "example": "Localized plan description", "type": "string" }, "plan_end_date": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "plan_external_id": { "example": "PlanExternalId", "type": "string" }, "plan_group_id": { "example": "TestGroupId", "nullable": true, "type": "string" }, "plan_id": { "example": "54321", "type": "integer" }, "plan_name": { "example": "Localized plan name", "type": "string" }, "plan_start_date": { "example": "2021-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "plan_type": { "example": "all", "type": "string" }, "promotion": { "$ref": "#/components/schemas/Promotion" }, "trial_period": { "example": "7", "nullable": true, "type": "integer" } }, "required": [ "plan_id", "plan_external_id", "plan_type", "plan_name", "plan_description", "period", "charge", "promotion", "payment_details" ], "type": "object" }, "Charge": { "properties": { "amount": { "example": "4.99", "format": "float", "type": "number" }, "amount_with_promotion": { "default": null, "example": "3.99", "format": "float", "nullable": true, "type": "number" }, "currency": { "example": "USD", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "Charge2": { "properties": { "amount": { "example": "4.99", "format": "float", "type": "number" }, "currency": { "example": "USD", "type": "string" }, "setup_fee": { "example": "0.99", "format": "float", "nullable": true, "type": "number" } }, "required": [ "amount", "currency" ], "type": "object" }, "Charge3": { "properties": { "amount": { "example": "4.99", "format": "float", "type": "number" }, "amount_with_promotion": { "default": null, "example": "3.99", "format": "float", "nullable": true, "type": "number" }, "currency": { "example": "USD", "type": "string" } }, "required": [ "amount", "currency" ], "type": "object" }, "Charge4": { "properties": { "amount": { "example": "4.99", "format": "float", "type": "number" }, "currency": { "example": "USD", "type": "string" }, "setup_fee": { "example": "0.99", "format": "float", "nullable": true, "type": "number" } }, "required": [ "amount", "currency" ], "type": "object" }, "Coupon": { "properties": { "campaign_code": { "type": "string" }, "coupon_code": { "type": "string" }, "coupon_id": { "type": "integer" }, "expiration_date": { "type": "string" }, "is_active": { "type": "boolean" }, "project_id": { "type": "integer" }, "redeems_count_for_user": { "type": "integer" }, "redeems_count_remain": { "type": "integer" }, "subscription_coupon": { "nullable": true, "type": "string" }, "virtual_currency_amount": { "type": "integer" }, "virtual_items": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "CouponAttribute": { "properties": { "key": { "description": "用户属性键值。", "type": "string" }, "list_of_values": { "description": "enum 类型可能值的数组。", "items": { "type": "object" }, "type": "array" }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "用户属性本地化名称的数组。" } ] }, "skip_condition_on_nonexistent_key": { "description": "键值不存在时是否应跳过条件。", "type": "boolean" }, "type": { "description": "键类型。", "enum": [ "int", "string", "enum", "date" ], "type": "string" }, "visible": { "type": "boolean" } }, "type": "object" }, "CreatePromotion": { "properties": { "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "本地化促销描述数组。" } ] }, "label": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "本地化标签数组，显示在支付 UI 中。" } ] }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "本地化促销名称数组。" } ] }, "project_id": { "description": "项目ID。", "type": "integer" }, "technical_name": { "description": "促销活动的技术名称。", "type": "string" } }, "type": "object" }, "GetPromotion": { "allOf": [ { "$ref": "#/components/schemas/CreatePromotion" }, { "properties": { "enabled": { "type": "boolean" }, "id": { "type": "integer" }, "read_only": { "type": "boolean" }, "show_banner": { "type": "boolean" } }, "type": "object" } ] }, "LastSuccessfulCharge": { "properties": { "amount": { "example": "3.99", "format": "float", "nullable": true, "type": "number" }, "currency": { "example": "USD", "nullable": true, "type": "string" }, "date": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "type": "string" } }, "required": [ "date" ], "type": "object" }, "ListManagementSubscriptionsResponse": { "properties": { "has_more": { "example": "false", "type": "boolean" }, "items": { "default": [], "items": { "$ref": "#/components/schemas/ManagementSubscriptionResponse2" }, "type": "array" } }, "required": [ "has_more" ], "type": "object" }, "ListPlansResponse": { "properties": { "has_more": { "example": "false", "type": "boolean" }, "items": { "default": [], "items": { "$ref": "#/components/schemas/PlanResponse" }, "type": "array" } }, "required": [ "has_more" ], "type": "object" }, "LocalizedStringPairs": { "properties": { "ar": { "description": "阿拉伯语。", "type": "string" }, "bg": { "description": "保加利亚语。", "type": "string" }, "cn": { "description": "中文（简体）。", "type": "string" }, "cs": { "description": "捷克语。", "type": "string" }, "de": { "description": "德语。", "type": "string" }, "en": { "description": "英语。", "type": "string" }, "es": { "description": "西班牙语。", "type": "string" }, "fr": { "description": "法语。", "type": "string" }, "he": { "description": "希伯来语。", "type": "string" }, "it": { "description": "意大利语。", "type": "string" }, "ja": { "description": "日语。", "type": "string" }, "ko": { "description": "韩语。", "type": "string" }, "pl": { "description": "波兰语。", "type": "string" }, "pt": { "description": "葡萄牙语。", "type": "string" }, "ro": { "description": "罗马尼亚语。", "type": "string" }, "ru": { "description": "俄语。", "type": "string" }, "th": { "description": "泰语。", "type": "string" }, "tr": { "description": "土耳其语。", "type": "string" }, "tw": { "description": "中文（繁体）。", "type": "string" }, "vi": { "description": "越南语。", "type": "string" } }, "type": "object" }, "ManagementSubscriptionResponse": { "properties": { "charge": { "$ref": "#/components/schemas/Charge" }, "date_create": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "type": "string" }, "date_end": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "date_last_charge": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "date_next_charge": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "id": { "example": "12345", "type": "integer" }, "is_change_plan_allowed": { "example": "false", "type": "boolean" }, "is_change_to_non_renew_possible": { "example": "true", "type": "boolean" }, "is_in_trial": { "example": "false", "type": "boolean" }, "is_renew_possible": { "example": "true", "type": "boolean" }, "last_successful_charge": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/LastSuccessfulCharge" } ] }, "payment_account": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse2" } ] }, "period": { "$ref": "#/components/schemas/Period" }, "plan_description": { "example": "Localized plan description", "type": "string" }, "plan_name": { "example": "Localized plan name", "type": "string" }, "product_description": { "example": "Localized product description", "nullable": true, "type": "string" }, "product_name": { "example": "Product name", "nullable": true, "type": "string" }, "status": { "example": "active", "type": "string" }, "trial_period": { "example": "0", "nullable": true, "type": "integer" } }, "required": [ "id", "plan_name", "plan_description", "status", "is_in_trial", "date_create", "charge", "period", "is_renew_possible", "is_change_to_non_renew_possible", "is_change_plan_allowed" ], "type": "object" }, "ManagementSubscriptionResponse2": { "properties": { "charge": { "$ref": "#/components/schemas/Charge3" }, "date_create": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "type": "string" }, "date_last_charge": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "date_next_charge": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "id": { "example": "12345", "type": "integer" }, "is_in_trial": { "example": "false", "type": "boolean" }, "payment_account": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse3" } ] }, "period": { "$ref": "#/components/schemas/Period3" }, "plan_description": { "example": "Localized plan description", "type": "string" }, "plan_name": { "example": "Localized plan name", "type": "string" }, "product_description": { "example": "Localized product description", "nullable": true, "type": "string" }, "product_name": { "example": "Product name", "nullable": true, "type": "string" }, "status": { "example": "active", "type": "string" }, "trial_period": { "example": "0", "nullable": true, "type": "integer" } }, "required": [ "id", "plan_name", "plan_description", "status", "is_in_trial", "date_create", "charge", "period" ], "type": "object" }, "PayStationLinkResponse": { "properties": { "link_to_ps": { "example": "https://secure.xsolla.com/paystation2/?access_token=", "type": "string" } }, "required": [ "link_to_ps" ], "type": "object" }, "PaymentDetails": { "properties": { "surcharge": { "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Surcharge" } ] }, "unused": { "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Unused" } ] } }, "type": "object" }, "PaymentRecurrentAccountResponse": { "properties": { "card_expiry_date": { "nullable": true, "properties": { "month": { "example": "09", "type": "string" }, "year": { "example": "2023", "type": "string" } }, "type": "object" }, "id": { "example": "123", "type": "integer" }, "name": { "example": "** 7398", "nullable": true, "type": "string" }, "ps_name": { "example": "Mastercard", "nullable": true, "type": "string" }, "switch_icon_name": { "example": "mastercard.svg", "nullable": true, "type": "string" }, "type": { "example": "card", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "PaymentRecurrentAccountResponse2": { "properties": { "card_expiry_date": { "nullable": true, "properties": { "month": { "example": "09", "type": "string" }, "year": { "example": "2023", "type": "string" } }, "type": "object" }, "id": { "example": "123", "type": "integer" }, "name": { "example": "** 7398", "nullable": true, "type": "string" }, "ps_name": { "example": "Mastercard", "nullable": true, "type": "string" }, "switch_icon_name": { "example": "mastercard.svg", "nullable": true, "type": "string" }, "type": { "example": "card", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "PaymentRecurrentAccountResponse3": { "properties": { "card_expiry_date": { "nullable": true, "properties": { "month": { "example": "09", "type": "string" }, "year": { "example": "2023", "type": "string" } }, "type": "object" }, "id": { "example": "123", "type": "integer" }, "name": { "example": "** 7398", "nullable": true, "type": "string" }, "ps_name": { "example": "Mastercard", "nullable": true, "type": "string" }, "switch_icon_name": { "example": "mastercard.svg", "nullable": true, "type": "string" }, "type": { "example": "card", "type": "string" } }, "required": [ "id", "type" ], "type": "object" }, "PaymentSystemResponse": { "properties": { "id": { "example": "12345", "type": "integer" }, "name": { "example": "PayPal", "nullable": true, "type": "string" } }, "required": [ "id" ], "type": "object" }, "Period": { "properties": { "unit": { "default": null, "example": "month", "nullable": true, "type": "string" }, "value": { "default": null, "example": "1", "nullable": true, "type": "integer" } }, "type": "object" }, "Period2": { "properties": { "unit": { "default": null, "example": "month", "nullable": true, "type": "string" }, "value": { "default": null, "example": "1", "nullable": true, "type": "integer" } }, "type": "object" }, "Period3": { "properties": { "unit": { "default": null, "example": "month", "nullable": true, "type": "string" }, "value": { "default": null, "example": "1", "nullable": true, "type": "integer" } }, "type": "object" }, "Period4": { "properties": { "unit": { "default": null, "example": "month", "nullable": true, "type": "string" }, "value": { "default": null, "example": "1", "nullable": true, "type": "integer" } }, "type": "object" }, "PlanResponse": { "properties": { "charge": { "$ref": "#/components/schemas/Charge4" }, "period": { "$ref": "#/components/schemas/Period4" }, "plan_description": { "example": "Localized plan description", "type": "string" }, "plan_end_date": { "example": "2031-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "plan_external_id": { "example": "PlanExternalId", "type": "string" }, "plan_group_id": { "example": "TestGroupId", "nullable": true, "type": "string" }, "plan_id": { "example": "54321", "type": "integer" }, "plan_name": { "example": "Localized plan name", "type": "string" }, "plan_start_date": { "example": "2021-04-11T13:51:02+03:00", "format": "date-time", "nullable": true, "type": "string" }, "plan_type": { "example": "all", "type": "string" }, "promotion": { "$ref": "#/components/schemas/Promotion2" }, "trial_period": { "example": "7", "nullable": true, "type": "integer" } }, "required": [ "plan_id", "plan_external_id", "plan_type", "plan_name", "plan_description", "period", "charge", "promotion" ], "type": "object" }, "ProjectManageSubscriptionSettingsResponse": { "properties": { "allow_change_package": { "example": "true", "type": "boolean" }, "recurrent_cancel_possible": { "example": "true", "type": "boolean" } }, "required": [ "recurrent_cancel_possible", "allow_change_package" ], "type": "object" }, "Promotion": { "properties": { "promotion_charge_amount": { "default": null, "example": "3.99", "format": "float", "nullable": true, "type": "number" }, "promotion_remaining_charges": { "default": null, "example": "3", "nullable": true, "type": "integer" } }, "type": "object" }, "Promotion2": { "properties": { "promotion_charge_amount": { "default": null, "example": "3.99", "format": "float", "nullable": true, "type": "number" }, "promotion_remaining_charges": { "default": null, "example": "3", "nullable": true, "type": "integer" } }, "type": "object" }, "PromotionPaymentSystem": { "properties": { "payment_systems": { "description": "付款系统。", "items": { "properties": { "id": { "description": "付款系统ID。", "type": "integer" }, "name": { "description": "付款系统名称。", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PromotionPeriod": { "properties": { "periods": { "description": "日期/时间范围。", "items": { "properties": { "from": { "description": "日期范围的开始时间。", "format": "datetime", "type": "string" }, "offset": { "description": "元素编号，从该元素开始生成列表（从0开始数）。", "type": "string" }, "to": { "description": "日期范围的结束时间。", "format": "datetime", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "PromotionReward": { "properties": { "item": { "description": "设置虚拟物品的额外奖励。", "properties": { "bonus": { "description": "将一些额外的虚拟物品设置为额外奖励。", "items": { "properties": { "id": { "type": "integer" }, "localized_name": { "description": "计划名称（使用默认语言英文），复制name.en值。", "type": "string" }, "quantity": { "description": "虚拟物品金额。", "type": "integer" }, "sku": { "description": "商品SKU。", "type": "string" } }, "type": "object" }, "type": "array" }, "discount": { "description": "设置虚拟物品购买的折扣。", "items": { "properties": { "discount_percent": { "description": "折扣金额百分比。", "format": "float", "type": "number" }, "localized_name": { "description": "计划名称（使用默认语言英文），复制name.en值。", "type": "string" }, "max_amount": { "description": "可进行促销活动的虚拟物品的最大金额。", "format": "integer", "type": "number" }, "sku": { "description": "商品SKU。", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "package": { "description": "设置虚拟货币包购买的额外奖励。", "properties": { "bonus_amount": { "description": "虚拟货币额外奖励金额。", "format": "float", "type": "number" }, "bonus_percent": { "description": "额外奖励百分比值。", "format": "float", "type": "number" } }, "type": "object" }, "purchase": { "description": "设置整个购买的奖励。", "properties": { "discount_percent": { "description": "折扣金额百分比。", "format": "float", "type": "number" } }, "type": "object" }, "subscription": { "description": "设置订阅奖励。", "properties": { "trial_days": { "description": "试用期，以天为单位。", "type": "integer" } }, "type": "object" } }, "type": "object" }, "PromotionSubject": { "properties": { "digital_contents": { "nullable": true, "type": "object" }, "items": { "description": "促销将应用到列出的虚拟物品。", "items": { "properties": { "id": { "type": "integer" }, "localized_name": { "description": "计划名称（使用默认语言英文），复制name.en值。", "type": "string" }, "sku": { "description": "商品SKU。", "type": "string" } }, "type": "object" }, "type": "array" }, "packages": { "description": "促销活动适用于列出的虚拟货币包。", "items": { "type": "object" }, "nullable": true, "type": "array" }, "purchase": { "description": "促销活动是否应当适用于整个购买。", "type": "boolean" }, "subscriptions": { "description": "将要进行促销的订阅计划或产品相关数据的对象。", "nullable": true, "properties": { "max_charges_count": { "description": "将要进行促销的最多收费次数。", "type": "integer" }, "plans": { "items": { "description": "将要进行促销的订阅计划的数组。", "type": "string" }, "type": "array" }, "products": { "items": { "description": "将要进行促销的订阅产品的数组。", "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "Subscription": { "properties": { "cancel_subscription_payment": { "description": "如果设为`true`，此订阅的最后一次付款将被退回。**只有状态更改为`canceled`，此选项才会有效**。", "type": "boolean" }, "status": { "description": "状态。", "enum": [ "active", "canceled", "non_renewing" ], "type": "string" }, "timeshift": { "description": "账单推迟。", "properties": { "type": { "description": "账单时间单位，可以是`day`或`month`。", "enum": [ "day", "month" ], "type": "string" }, "value": { "description": "推迟账单的时间单位数。该值取决于类型参数：
- 如果`type`为`day`，可以是1-366
- 如果`type`为`month`，可以是1-12", "type": "string" } }, "type": "object" }, "xsolla_network": { "properties": { "collaborator_id": { "description": "协作推广者ID — [圈内达人](https://developers.xsolla.com/zh/doc/partner-network/#guides_network_glossary_influencer)或[联盟网络](https://developers.xsolla.com/zh/doc/partner-network/#guides_network_glossary_affiliate_network)标识符。可在**发布商帐户 > 流量联盟 > 圈内达人**部分找到。", "type": "string" } }, "type": "object" } }, "type": "object" }, "SubscriptionResponse": { "properties": { "charge_amount": { "description": "支付金额。", "format": "float", "type": "number" }, "comment": { "description": "更改订阅状态的原因", "type": "string" }, "currency": { "description": "交易使用的币种。符合ISO 4217标准的三字母货币代码。", "type": "string" }, "date_create": { "description": "按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)规定的`YYYY-MM-DD’T’HH:MM:SS`格式的订阅创建日期。", "format": "datetime", "type": "string" }, "date_end": { "description": "按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)规定的`YYYY-MM-DD’T’HH:MM:SS`格式的订阅结束日期。", "format": "datetime", "type": "string" }, "date_last_charge": { "description": "按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)规定的`YYYY-MM-DD’T’HH:MM:SS`格式的上次订阅扣费日期。", "format": "datetime", "nullable": true, "type": "string" }, "date_next_charge": { "description": "按照[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)规定的`YYYY-MM-DD’T’HH:MM:SS`格式的下次订阅扣费日期。", "format": "datetime", "nullable": true, "type": "string" }, "id": { "description": "订阅ID", "type": "integer" }, "plan": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsPlan" } ] }, "product": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsProductWithId" } ] }, "status": { "description": "状态", "enum": [ "new", "active", "canceled", "non_renewing", "freeze" ], "type": "string" }, "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ] } }, "type": "object" }, "SubscriptionsPlan": { "properties": { "billing_retry": { "description": "账单扣费重试详情。", "properties": { "value": { "description": "账单扣费重试次数。", "type": "integer" } }, "required": [ "value" ], "type": "object" }, "charge": { "description": "账单详情。", "properties": { "amount": { "description": "支付金额。", "format": "float", "type": "number" }, "currency": { "description": "购买币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" }, "period": { "description": "账单周期。", "properties": { "type": { "description": "时间单位。可以是`day`、`month`或`lifetime`。", "enum": [ "day", "month", "lifetime" ], "type": "string" }, "value": { "description": "时间单位数。该值取决于类型参数：
- 如果`type`为`day`，可以是1-366
- 如果`type`为`month`，可以是1-12
- 如果`type`为`lifetime`，则为0", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "prices": { "description": "不同货币下的价格列表。", "items": { "properties": { "amount": { "description": "支付金额。", "format": "float", "type": "number" }, "currency": { "description": "购买币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" }, "setup_fee": { "description": "包含在首次发票中收取的一次性初设费。", "format": "float", "type": "number" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" } }, "required": [ "period" ], "type": "object" }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "计划描述。由\"localization\":\"plan description\"组成的键值对。" } ] }, "expiration": { "description": "订阅到期详情。", "properties": { "type": { "description": "时间单位，可以是`day`或`month`。", "enum": [ "day", "month" ], "type": "string" }, "value": { "description": "过期之前的时间。", "nullable": true, "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "external_id": { "description": "外部计划标识符。", "type": "string" }, "grace_period": { "description": "带有宽限期相关数据的对象。", "properties": { "type": { "description": "时间单位，可以是`day`。", "enum": [ "day" ], "type": "string" }, "value": { "description": "两次收费之间的间隔时间。", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "group_id": { "description": "计划关联的组ID。", "nullable": true, "type": "string" }, "id": { "description": "订阅计划ID。", "type": "integer" }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "计划名称。值包含 \"localization\":\"plan name\" 对。" } ] }, "project_id": { "description": "项目ID。", "type": "integer" }, "refund_period": { "description": "订阅计划可退款的时间期限（单位为天）。", "nullable": true, "type": "integer" }, "status": { "properties": { "value": { "description": "订阅计划状态。", "enum": [ "active", "disabled" ], "type": "string" } }, "type": "object" }, "tags": { "description": "计划标签。", "items": { "type": "string" }, "type": "array" }, "trial": { "description": "试用期详情。", "properties": { "type": { "description": "时间单位，可以是`day`。", "enum": [ "day" ], "type": "string" }, "value": { "description": "两次收费之间的间隔时间。", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" } }, "type": "object" }, "SubscriptionsPlanRequest": { "properties": { "billing_retry": { "description": "账单扣费重试详情。", "properties": { "value": { "description": "账单扣费重试次数。", "type": "integer" } }, "required": [ "value" ], "type": "object" }, "charge": { "description": "账单详情。", "properties": { "amount": { "description": "支付金额。", "format": "float", "type": "number" }, "currency": { "description": "购买币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" }, "period": { "description": "账单周期。", "properties": { "type": { "description": "时间单位。可以是`day`、`month`或`lifetime`。", "enum": [ "day", "month", "lifetime" ], "type": "string" }, "value": { "description": "时间单位数。该值取决于类型参数：
- 如果`type`为`day`，可以是1-366
- 如果`type`为`month`，可以是1-12
- 如果`type`为`lifetime`，则为0", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "prices": { "description": "不同货币下的价格列表。", "items": { "properties": { "amount": { "description": "支付金额。", "format": "float", "type": "number" }, "currency": { "description": "购买币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" }, "setup_fee": { "description": "包含在首次发票中收取的一次性初设费。", "format": "float", "type": "number" } }, "required": [ "amount", "currency" ], "type": "object" }, "type": "array" } }, "required": [ "period" ], "type": "object" }, "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "计划描述。由\"localization\":\"plan description\"组成的键值对。" } ] }, "expiration": { "description": "订阅到期详情。", "properties": { "type": { "description": "时间单位，可以是`day`或`month`。", "enum": [ "day", "month" ], "type": "string" }, "value": { "description": "过期之前的时间。", "nullable": true, "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "external_id": { "description": "外部计划标识符。", "type": "string" }, "grace_period": { "description": "带有宽限期相关数据的对象。", "properties": { "type": { "description": "时间单位，可以是`day`。", "enum": [ "day" ], "type": "string" }, "value": { "description": "两次收费之间的间隔时间。", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" }, "group_id": { "description": "计划关联的组ID。", "type": "string" }, "name": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "计划名称。值包含 \"localization\":\"plan name\" 对。" } ] }, "refund_period": { "description": "订阅计划可退款的时间期限（单位为天）。", "nullable": true, "type": "integer" }, "status": { "properties": { "value": { "description": "订阅计划状态。", "enum": [ "active", "disabled" ], "type": "string" } }, "type": "object" }, "tags": { "description": "计划标签。", "items": { "type": "string" }, "type": "array" }, "trial": { "description": "试用期限详细信息。如未传入此参数，则使用默认值（0天）。", "properties": { "type": { "description": "时间单位，可以是`day`。", "enum": [ "day" ], "type": "string" }, "value": { "description": "两次收费之间的间隔时间。", "type": "integer" } }, "required": [ "value", "type" ], "type": "object" } }, "type": "object" }, "SubscriptionsProduct": { "nullable": true, "properties": { "description": { "allOf": [ { "$ref": "#/components/schemas/LocalizedStringPairs" }, { "description": "本地化商品描述。" } ] }, "group_id": { "description": "产品关联的组ID。", "type": "string" }, "name": { "description": "产品名称。", "type": "string" } }, "type": "object" }, "SubscriptionsProductWithId": { "allOf": [ { "properties": { "id": { "description": "这些计划与之连接的产品的 ID。", "nullable": true, "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] }, "Surcharge": { "properties": { "surcharge_amount": { "default": null, "example": "1.99", "format": "float", "nullable": true, "type": "number" }, "surcharge_currency": { "default": null, "example": "USD", "nullable": true, "type": "string" } }, "type": "object" }, "Unused": { "properties": { "unused_amount": { "default": null, "example": "1.99", "format": "float", "nullable": true, "type": "number" }, "unused_currency": { "default": null, "example": "USD", "nullable": true, "type": "string" } }, "type": "object" }, "User": { "properties": { "id": { "description": "用户ID", "type": "string" }, "name": { "description": "用户名", "type": "string" } }, "type": "object" }, "token": { "example": { "purchase": { "checkout": { "amount": 10, "currency": "USD" }, "subscription": { "gift": { "email": "recipient_email@email.com", "recipient": "test_recipient_v1" } } }, "settings": { "currency": "USD", "language": "en", "project_id": 16184, "ui": { "components": { "virtual_currency": { "custom_amount": true } }, "desktop": { "virtual_item_list": { "button_with_price": true, "layout": "list" } }, "size": "medium" } }, "user": { "age": 19, "country": { "allow_modify": true, "value": "US" }, "email": { "value": "john.smith@mail.com" }, "id": { "value": "user_2" }, "name": { "value": "John Smith" } } }, "properties": { "custom_parameters": { "description": "您可以在令牌的`custom_parameters`对象中传递其他参数以配置反欺诈筛选器。推荐参数在下拉列表中显示。[请参阅支付中心文档](https://developers.xsolla.com/zh/doc/pay-station/features/antifraud/)。", "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": "integer" }, "notifications_enabled": { "description": "玩家是否启用了通知。", "type": "boolean" }, "profile_completed": { "description": "玩家在帐户资料中是否添加了其它信息。", "type": "boolean" }, "profile_image_added": { "description": "玩家是否上传了简介头像。", "type": "boolean" }, "pvp_activity": { "description": "玩家是否参与了玩家对战。", "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": "integer" }, "total_sum": { "description": "付款总额。", "format": "float", "type": "integer" }, "tutorial_completed": { "description": "玩家是否完成了游戏教程。", "type": "boolean" }, "unlocked_achievements": { "description": "未解锁的通关数。", "type": "integer" }, "user_level": { "description": "玩家的等级、口碑或排名。", "type": "integer" }, "win_rate": { "description": "赢率。", "type": "integer" } }, "type": "object" }, "purchase": { "description": "带有购买相关数据的对象。", "properties": { "checkout": { "description": "带有结账参数相关数据的对象。", "properties": { "amount": { "description": "购买金额。", "format": "float", "type": "integer" }, "currency": { "description": "购买币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" } }, "type": "object" }, "subscription": { "description": "带有订阅相关数据的对象。", "properties": { "available_plans": { "description": "包含订阅套餐相关数据的数组。只有这些套餐会显示在支付用户界面中。", "items": { "type": "string" }, "type": "array" }, "currency": { "description": "购买计划的货币，以此币种进行所有计算。", "type": "string" }, "gift": { "description": "赠礼订阅的详细信息。", "properties": { "anonymous": { "description": "是否隐藏送礼人姓名。如为`true`，则在邮件通知中隐藏送礼人姓名。默认为`false`。", "type": "boolean" }, "email": { "description": "接收人邮箱。", "type": "string" }, "message": { "description": "给接收者的留言。", "type": "string" }, "recipient": { "description": "接收者ID。", "type": "string" }, "redirect_url": { "description": "在此处提供包含赠礼订阅额外信息的页面链接或帐户创建页面的链接。收礼人可从订阅赠礼邮件通知中跳转到该页面。", "type": "string" } }, "required": [ "recipient", "email" ], "type": "object" }, "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" } }, "type": "object" }, "settings": { "description": "自定义项目设置。", "properties": { "currency": { "description": "首选支付币种。参照[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母货币代码。", "type": "string" }, "external_id": { "description": "游戏中的交易ID。值对于每个用户付款必须唯一。", "type": "string" }, "language": { "description": "界面语言。2字母（小写字母）[语言代码](https://developers.xsolla.com/zh/doc/pay-station/features/localization/)。", "type": "string" }, "mode": { "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": { "autoredirect_from_status_page": { "description": "从状态页面自动重定向。", "type": "boolean" }, "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" }, "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": "用户会在支付过后被重定向到此页面。参数`user_id`、`foreigninvoice`、`invoice_id`和`status`会被自动添加到此链接。", "type": "string" }, "ui": { "description": "带有界面设置相关数据的对象。", "properties": { "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" }, "desktop": { "description": "带有对桌面版本有效的界面设置相关数据的对象。", "properties": { "header": { "description": "带有标题设置相关数据的对象。", "properties": { "close_button": { "description": "是否在支付中心桌面端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到`settings.return_url`参数中指定的URL。默认为`false`。", "type": "boolean" }, "is_visible": { "description": "标题在支付 UI 上是否可见。", "type": "boolean" }, "type": { "description": "如何显示标题。不能为`compact`（隐藏项目名称和用户ID）或`normal`（默认）。", "enum": [ "compact", "normal" ], "type": "string" }, "visible_logo": { "description": "如果为`true`，标题中将显示Logo（请先把Logo文件提供给您的客户成功经理）。", "type": "boolean" }, "visible_name": { "description": "标题中是否显示项目名称。", "type": "boolean" }, "visible_purchase": { "description": "是否在标题中显示购买描述（`purchase.description.value`）。默认为`true`。", "type": "boolean" } }, "type": "object" }, "subscription_list": { "description": "带有订阅列表设置相关数据的对象。", "properties": { "description": { "description": "可以在此传递订阅相关的任意文本。文本将显示在订阅计划列表的上方。", "type": "string" }, "display_local_price": { "description": "如为`true`且如果用户的当地货币与订阅计划的货币不同，则用户将看到两种价格：以当地货币和基础货币标价的价格。", "type": "boolean" }, "layout": { "description": "订阅列表模式。可以是`list`（默认值）或`grid`。", "enum": [ "list", "grid" ], "type": "string" } }, "type": "object" }, "virtual_currency_list": { "description": "带有虚拟货币列表设置相关数据的对象。", "properties": { "button_with_price": { "description": "如果为`true`，则价格会显示在按钮里。如果为`false`，则价格会显示在按钮左侧。默认值为`false`。", "type": "boolean" }, "description": { "description": "可以在此传递虚拟货币列表相关的任意文本。文本将显示在虚拟货币包列表的上方。", "type": "string" } }, "type": "object" }, "virtual_item_list": { "description": "带有虚拟物品列表设置相关数据的对象。", "properties": { "button_with_price": { "description": "如果为`true`，则价格会显示在按钮里。如果为`false`，则价格会显示在按钮左侧。默认值为`false`。", "type": "boolean" }, "layout": { "description": "订阅列表模式。可以是`list`（默认值）或`grid`。", "enum": [ "list", "grid" ], "type": "string" }, "view": { "description": "以垂直/水平菜单显示虚拟项目组。可以`horizontal_navigation`或`vertical_navigation`（默认）。", "enum": [ "horizontal_navigation", "vertical_navigation" ], "type": "string" } }, "type": "object" } }, "type": "object" }, "header": { "properties": { "visible_virtual_currency_balance": { "description": "此元素是否可在支付UI上隐藏。默认为`true`。", "type": "boolean" } }, "type": "object" }, "is_prevent_external_link_open": { "description": "是否禁用将链接重定向至外部资源。默认为`true`。点击外部链接时，将通过`postMessage`机制发送`external-link-open`事件。重定向链接的地址在`url`参数中传递。", "type": "boolean" }, "license_url": { "description": "EULA的链接。", "type": "string" }, "mobile": { "properties": { "footer": { "properties": { "is_visible": { "description": "是否在移动版本的支付UI中隐藏或显示脚注。", "type": "boolean" } }, "type": "object" }, "header": { "properties": { "close_button": { "description": "是否在支付中心移动端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到`settings.return_url`参数中指定的URL。默认为`false`。", "type": "boolean" } }, "type": "object" }, "mode": { "description": "用户仅可以通过他们已保存的付款方式进行付款。可以为`saved_accounts`。", "enum": [ "saved_accounts" ], "type": "string" } }, "type": "object" }, "mode": { "description": "支付中心的界面模式。可能的值为`user_account`。请注意，页眉仅包含用户帐户的导航菜单，而没有用于选择产品或进行付款的任何选项。“用户帐户”仅在桌面模式下可用。", "type": "string" }, "size": { "description": "支付UI的大小。此参数可拥有以下值之一，具体取决于支付UI的所需大小：\n - [small](https://livedemo.xsolla.com/developers/small/)：支付UI支持的最小尺寸。当窗口大小严格受限时，请使用此值（尺寸：620 x 630）\n - [medium](https://livedemo.xsolla.com/developers/medium/)：支付UI的推荐大小。使用此值可以在灯箱中显示支付UI（尺寸：740 x 760）\n - [large](https://livedemo.xsolla.com/developers/large/)：在新窗口或者选项卡中显示支付UI的最佳大小（尺寸：820 x 840）", "enum": [ "small", "medium", "large" ], "type": "string" }, "theme": { "description": "支付UI的外观主题。可以是`default`（默认值）或`default_dark`。", "enum": [ "default", "default_dark" ], "type": "string" }, "user_account": { "description": "对象以及有关用户账号的数据。", "properties": { "history": { "allOf": [ { "description": "**历史记录**子菜单。" }, { "properties": { "enable": { "description": "在菜单中显示还是隐藏“管理订阅”页面。默认值为`false`。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" } ] }, "info": { "allOf": [ { "description": "**我的账户**页面。" }, { "properties": { "enable": { "description": "在菜单中显示还是隐藏“管理订阅”页面。默认值为`false`。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" } ] }, "payment_accounts": { "allOf": [ { "description": "**保存的付款方法**子菜单。" }, { "properties": { "enable": { "description": "在菜单中显示还是隐藏“管理订阅”页面。默认值为`false`。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" } ] }, "subscriptions": { "allOf": [ { "description": "**管理订阅**子菜单。" }, { "properties": { "enable": { "description": "在菜单中显示还是隐藏“管理订阅”页面。默认值为`false`。", "type": "boolean" }, "order": { "description": "虚拟物品在模块菜单中的排列顺序。", "type": "integer" } }, "type": "object" } ] } }, "type": "object" }, "version": { "description": "设备的类型。可以是`desktop`（默认值）或`mobile`。", "enum": [ "desktop", "mobile" ], "type": "string" } }, "type": "object" } }, "required": [ "project_id" ], "type": "object" }, "user": { "description": "带用户相关数据的对象。", "properties": { "age": { "description": "用户年龄。", "type": "integer" }, "attributes": { "description": "带有用户属性相关数据的对象，用于筛选物品列表。应当是带键值对的有效JSON哈希。", "type": "object" }, "country": { "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": { "description": "`user.email`对象是反欺诈模型的必要部分，有助于提高接受率。同时它也是艾克索拉和支付系统的要求。如果未传入该参数，支付页面将显示输入邮箱必填字段。购买凭证将发送至在该参数中传入的或在支付页面上输入的邮箱地址。", "properties": { "value": { "description": "用户电子邮箱。必须符合[RFC 822](https://www.w3.org/Protocols/rfc822/#z8)协议标准。", "type": "string" } }, "required": [ "value" ], "type": "object" }, "id": { "properties": { "value": { "description": "用户ID。", "type": "string" } }, "required": [ "value" ], "type": "object" }, "is_legal": { "description": "用户是否为法律实体。", "type": "boolean" }, "legal": { "allOf": [ { "description": "包含法律实体详细信息的对象。如果`user.is_legal`为`true`，则对象及其所有参数为必需。" }, { "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" } ] }, "name": { "properties": { "value": { "description": "用户昵称。", "type": "string" } }, "type": "object" }, "phone": { "properties": { "value": { "description": "电话号码。", "type": "string" } }, "type": "object" }, "public_id": { "properties": { "value": { "description": "唯一识别用户并为用户所熟知的参数，与用户ID（电子邮件、昵称等）不同。此参数在可以在游戏商店以外进行购买时使用（如现金售货亭中的游戏按键）。", "type": "string" } }, "type": "object" }, "steam_id": { "properties": { "value": { "description": "Steam ID。", "type": "string" } }, "type": "object" }, "tracking_id": { "properties": { "value": { "description": "唯一的跟踪ID（用于营销活动）。", "type": "string" } }, "type": "object" }, "utm": { "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" } }, "required": [ "id" ], "type": "object" } }, "type": "object" } }, "securitySchemes": { "basicAuth": { "description": "艾克索拉API使用基本认证。所有发送到API的请求必须包含`Authorization: Basic `头，其中``是按照Base64标准加密的`merchant_id:api_key`对。\n\n请前往[发布商帐户](https://publisher.xsolla.com/)找到这些参数：
  • `merchant_id`在以下部分中显示：
    • 公司设置 > 公司部分。
    • 发布商帐户任意页面浏览器地址栏的URL中。URL的格式如下：`https://publisher.xsolla.com/`。
  • `api_key`仅在创建时在发布商帐户中显示一次，必须在己侧妥善保存。您可以在以下部分创建新密钥：
    • 公司设置 > API密钥。
    • 项目设置 > API密钥。

\n关于使用API密钥的详细信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。", "scheme": "basic", "type": "http" }, "subscriptionsManagementJwtAuth": { "scheme": "bearer", "type": "http" } } }, "info": { "description": "# 概览\n\n* **Version:** 2.0\n* **服务器**：`https://api.xsolla.com/merchant/v2/`\n\n本API参考介绍管理订阅、优惠券和促销活动的端点。\n如需了解关于订阅的详细信息，请参考[产品指南](https://developers.xsolla.com/zh/doc/subscriptions)和[词汇表](https://developers.xsolla.com/zh/doc/subscriptions/integration-guide/get-started/#general_glossary)。", "title": "Subscriptions API", "version": "2.0" }, "openapi": "3.0.0", "paths": { "/api/user/v1/management/projects/{project_id}/subscriptions": { "get": { "operationId": "list-subscriptions", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListManagementSubscriptionsResponse" } } }, "description": "Get subscriptions info" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.bad_request", "description": "Incorrect limit value, maximum allowed is 100" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "List subscriptions", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/settings": { "get": { "operationId": "get-management-settings", "parameters": [ { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectManageSubscriptionSettingsResponse" } } }, "description": "Returns project settings for managing subscription" }, "403": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.access_denied", "description": "You don't have access to requested project or resource." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Project not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Retrieving data from cache has failed." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Get management settings", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}": { "get": { "operationId": "get-management-subscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementSubscriptionResponse" } } }, "description": "Get subscription info" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Project with id = 123 was not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Get subscription", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate": { "put": { "operationId": "activate-subscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "status": "successful" } } }, "description": "Move subscription from non-renew to active" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.bad_request", "description": "Subscription is not allowed to change to active" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Activate subscription", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel": { "put": { "operationId": "cancel-subscription", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": {} }, "description": "Make subscription non-renewable" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_active", "description": "Subscription is not active" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Cancel subscription", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan": { "post": { "operationId": "get-change-plan-link", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "plan_external_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "sandbox", "required": false, "schema": { "type": "boolean" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayStationLinkResponse" } } }, "description": "Returns link to change subscription plan" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Change plan is not possible" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "ubscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Get change plan link", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account": { "get": { "operationId": "get-payment-account", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRecurrentAccountResponse" } } }, "description": "Get payment account info" }, "404": { "content": { "application/json": { "example": { "error": { "code": "data.not_found", "description": "Data not found" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Get payment account", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage": { "post": { "operationId": "manage-payment-account", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "sandbox", "required": false, "schema": { "type": "boolean" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayStationLinkResponse" } } }, "description": "Returns link for managing payment accounts" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Token retrieve error" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Manage payment account", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts": { "get": { "operationId": "list-payment-accounts", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingAccountsListResponse" } } }, "description": "Returns the user's billing accounts" }, "403": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.access_denied", "description": "You don't have access to requested project or resource." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed." }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "List payment accounts", "tags": [ "subscription-management" ] }, "post": { "operationId": "link-payment-account", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "payment_account_id", "required": true, "schema": { "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "status": "successful" } } }, "description": "Links a payment account to a subscription" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "This account is already linked" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Publisher API request failed" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Link payment account", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}": { "delete": { "operationId": "unlink-payment-account", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "payment_account_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "example": { "status": "successful" } } }, "description": "Unlink payment accounts" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" }, "500": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Error saving data" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Internal server error" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Unlink payment account", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change": { "get": { "operationId": "list-plans-for-change", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPlansResponse" } } }, "description": "List of available plans for change" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Incorrect limit value, maximum allowed is 100" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "List plans for change", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}": { "get": { "operationId": "get-plan-for-change", "parameters": [ { "in": "path", "name": "subscription_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "path", "name": "plan_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } }, { "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "in": "path", "name": "project_id", "required": true, "schema": { "pattern": "\\d+", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanPaymentDetailsResponse" } } }, "description": "Available plans for change with payment details" }, "400": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.exception", "description": "Change plan is not possible" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Bad request" }, "404": { "content": { "application/json": { "example": { "error": { "code": "subscriptions.not_found", "description": "Subscription with id = 123 not found or not belongs to user" }, "request_id": "e54d2081-33cc-4682-b65c-b22d98686d0a" } } }, "description": "Not found" } }, "security": [ { "subscriptionsManagementJwtAuth": [] } ], "summary": "Get plan for change", "tags": [ "subscription-management" ] }, "servers": [ { "url": "https://subscriptions.xsolla.com" } ] }, "/merchants/{merchant_id}/coupon_promotions": { "post": { "description": "创建一个新的优惠券活动。\n
\n

注意

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

\n
", "operationId": "create-campaign", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "campaign_code": "sample_campaign", "campaign_names": { "en": "Campaign Name", "ru": "Название кампании" }, "campaign_redeems_count_for_user": 1, "expiration_date": "2019-12-31", "project_id": 12345, "redeems_count": 10, "redeems_count_for_user": 1, "subscription_coupon": { "plan_id": 123, "product_id": 456, "trial_period": 30 }, "virtual_currency_amount": 200 }, "schema": { "allOf": [ { "required": [ "campaign_code", "project_id", "campaign_names" ] }, { "$ref": "#/components/schemas/Campaign" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "id": { "example": 9134, "type": "integer" } }, "type": "object" } } }, "description": "Created." } }, "security": [ { "basicAuth": [] } ], "summary": "创建优惠券活动", "tags": [ "coupons" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons": { "post": { "description": "将优惠券代码添加到优惠券活动中。\n
\n

注意

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

\n
", "operationId": "add-coupon-to-campaign", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/campaign-id-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "coupon_code": { "description": "优惠券代码。", "example": "34bryrb3", "type": "string" } }, "required": [ "coupon_code" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "添加优惠券至优惠券活动", "tags": [ "coupons" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions": { "get": { "description": "所有促销活动的列表。\n
\n

注意

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

\n
", "operationId": "get-promotions-list", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "datetime": { "from": "2020-02-01T00:00:00+04:00", "to": "2020-11-30T01:28:42+04:00" }, "enabled": true, "id": 17840, "is_active": true, "is_infinite": false, "project": { "id": 12345, "localized_name": "Christmas sale" }, "read_only": false, "technical_name": "christmas" }, { "datetime": null, "enabled": false, "id": 17891, "is_active": false, "is_infinite": true, "project": { "id": 12345, "localized_name": "30% discount" }, "read_only": false, "technical_name": "Sale promotion" } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取促销活动列表", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "post": { "description": "创建一个新的推广。\n
\n

注意

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

\n
", "operationId": "create-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": { "en": "Promotion with 30% discount", "ru": "Акция со скидкой 30%" }, "label": { "en": "30%", "ru": "30%" }, "name": { "en": "30% discount", "ru": "скидка 30%" }, "project_id": 12345, "technical_name": "Sale promotion" }, "schema": { "allOf": [ { "required": [ "project_id", "technical_name" ] }, { "$ref": "#/components/schemas/GetPromotion" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "id": 17890 }, "schema": { "properties": { "id": { "description": "促销活动 ID。", "type": "integer" } }, "type": "object" } } }, "description": "Created." } }, "security": [ { "basicAuth": [] } ], "summary": "创建新促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}": { "delete": { "description": "删除提升。 您只能使用`enabled`=`false`删除促销活动。\n
\n

注意

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

\n
", "operationId": "delete-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "删除促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "get": { "description": "检索促销。\n
\n

注意

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

\n
", "operationId": "get-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "description": { "en": "Promotion with 30% discount", "ru": "Акция со скидкой 30%" }, "enabled": false, "id": 17890, "label": { "en": "30%", "ru": "30%" }, "name": { "en": "30% discount", "ru": "Скидка 30%" }, "project_id": 40544, "read_only": false, "show_banner": true, "technical_name": "Sale promotion" }, "schema": { "$ref": "#/components/schemas/GetPromotion" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "put": { "description": "更新促销。 如果提升是只读的(`read_only`=`true`)，则不允许更改`project_id`参数。\n
\n

注意

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

\n
", "operationId": "update-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": { "en": "Promotion with 5% discount", "ru": "Акция со скидкой 5%" }, "label": { "en": "5%", "ru": "5%" }, "name": { "en": "5% discount", "ru": "скидка 5%" }, "project_id": 40544, "technical_name": "Sale promotion" }, "schema": { "allOf": [ { "required": [ "project_id", "technical_name" ] }, { "$ref": "#/components/schemas/GetPromotion" } ] } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "更新促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/coupons": { "put": { "description": "将优惠券活动附加到特定促销活动。\n
\n

注意

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

\n
", "operationId": "attach-campaign-to-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "campaigns": { "description": "优惠券活动ID数组。", "example": [ 9135 ], "items": { "type": "integer" }, "type": "array" } }, "required": [ "campaigns" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "将优惠券活动添加至促销活动", "tags": [ "coupons" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems": { "get": { "description": "获得支持促销的支付系统。 如果列表为空，促销将适用于所有支付系统。\n
\n

注意

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

\n
", "operationId": "get-payment-systems", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "id": 17840, "payment_systems": [ { "id": 27, "name": "Yandex.Money" } ] }, "schema": { "allOf": [ { "properties": { "id": { "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/PromotionPaymentSystem" } ] } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取支付系统", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "put": { "description": "设置支持促销的支付系统。 如果列表为空，促销将适用于所有支付系统。 如果提升为只读(`read_only`=`true`)，则无法调用此方法。\n
\n

注意

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

\n
", "operationId": "set-payment-systems", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "payment_systems": [ { "id": 24, "name": "PayPal" } ] }, "schema": { "$ref": "#/components/schemas/PromotionPaymentSystem" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "设置支付系统", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/periods": { "get": { "description": "获取促销有效的日期/时间范围。\n
\n

注意

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

\n
", "operationId": "get-validity-periods", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "id": 17840, "periods": [ { "from": "2020-02-01T00:00:00+04:00", "offset": "+04:00", "to": "2020-11-30T01:28:42+04:00" } ] }, "schema": { "allOf": [ { "properties": { "id": { "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/PromotionPeriod" } ] } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取期间", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "put": { "description": "获取促销有效的日期/时间范围。设置促销有效的日期/时间范围。 如果促销是只读的(`read_only`=`true`)，则不能编辑现有时段，但可以添加新时段。\n
\n

注意

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

\n
", "operationId": "set-validity-periods", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "periods": [ { "from": "2019-03-02T00:00:00+04:00", "to": "2019-04-02T00:00:00+04:00" } ] }, "schema": { "$ref": "#/components/schemas/PromotionPeriod" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "设置期间", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/review": { "get": { "description": "您需要在激活促销之前查看促销。 此方法返回错误列表（如果有）。\n
\n

注意

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

\n
", "operationId": "review-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "component": "rewards", "message": "Please select a reward" } ], "schema": { "items": { "properties": { "component": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "type": "array" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "检查促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/rewards": { "get": { "description": "获取与促销相关的奖励列表。\n
\n

注意

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

\n
", "operationId": "get-rewards", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "id": 17840, "item": { "bonus": [ { "id": 123456, "localized_name": "T-34-3", "quantity": 2, "sku": "1234" } ], "discount": [ { "discount_percent": 5, "localized_name": "T-34-3", "max_amount": 10, "sku": "1234" } ] }, "package": { "bonus_amount": 5, "bonus_percent": 5 }, "purchase": { "discount_percent": 10 }, "subscription": { "trial_days": 30 } }, "schema": { "allOf": [ { "properties": { "id": { "type": "integer" } }, "type": "object" }, { "$ref": "#/components/schemas/PromotionReward" } ] } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取奖励", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "put": { "description": "设置促销的奖励。 如果促销是只读的（`read_only`=`true`），则无法更新奖励。\n
\n

注意

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

\n
", "operationId": "set-rewards", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "item": { "bonus": [ { "quantity": 2, "sku": "1234" } ], "discount": [ { "discount_percent": 5, "max_amount": 10, "sku": "1234" } ] }, "package": { "bonus_amount": 5, "bonus_percent": 5 }, "purchase": { "discount_percent": 10 }, "subscription": { "trial_days": 30 } }, "schema": { "$ref": "#/components/schemas/PromotionReward" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "设置奖励", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/subject": { "get": { "description": "获取有关促销主题的信息。\n
\n

注意

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

\n
", "operationId": "get-subject", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "digital_contents": null, "id": 178, "items": [ { "id": 1234, "localized_name": "T-34-3", "sku": "1234" } ], "packages": null, "purchase": false, "subscriptions": null }, "schema": { "allOf": [ { "$ref": "#/components/schemas/PromotionSubject" }, { "properties": { "id": { "type": "integer" } }, "type": "object" } ] } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取主题", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "put": { "description": "设置促销的主题。 如果提升为只读(`read_only`=`true`)，则无法更新主题。 主题可以采用以下值：`purchase`，或`items`，或`packages`。\n
\n

注意

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

\n
", "operationId": "set-subject", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "digital_contents": null, "items": [ { "sku": "1234" } ], "packages": null, "purchase": false, "subscriptions": null }, "schema": { "$ref": "#/components/schemas/PromotionSubject" } } }, "required": true }, "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "设定主题", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/promotions/{promotion_id}/toggle": { "put": { "description": "将促销的状态从`enabled`切换到`disabled`，反之亦然。\n
\n

注意

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

\n
", "operationId": "toggle-promotion", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/promotion-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "切换促销活动", "tags": [ "promotions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/subscriptions": { "get": { "description": "列出所有经常订阅。
注意

这种API方法不能在高负载下使用。 最大负载为每分钟20个请求。
\n
\n

注意

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

\n
", "operationId": "get-subscriptions", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/user-id-query-param" }, { "$ref": "#/components/parameters/array-project-id-query-param" }, { "$ref": "#/components/parameters/array-plan-id-query-param" }, { "$ref": "#/components/parameters/array-product-id-query-param" }, { "$ref": "#/components/parameters/array-group-id-query-param" }, { "$ref": "#/components/parameters/status-query-param-array" }, { "$ref": "#/components/parameters/datetime-from-query-param" }, { "$ref": "#/components/parameters/datetime-to-query-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "charge_amount": 0.03, "currency": "USD", "date_create": "2013-09-05T15:27:47+04:00", "date_end": "2014-02-06T11:32:48+04:00", "date_last_charge": null, "date_next_charge": null, "id": 45, "plan": { "id": 12345, "project_id": 12345 }, "product": { "id": null }, "status": "canceled", "user": { "id": "User1", "name": "John Smith" } } ], "schema": { "items": { "$ref": "#/components/schemas/SubscriptionResponse" }, "type": "array" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有订阅", "tags": [ "subscriptions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/merchants/{merchant_id}/token": { "post": { "description": "您可以使用任意用户参数创建令牌。 您在获取令牌时发送这些参数，并在成功付款后接收它们。 令牌只能包含本文档中描述的或由您预定义的参数。\n\nIf任何参数以错误的格式发送或具有错误的类型，都不会发出令牌。 您将收到一个422HTTP代码，其中包含JSON正文中的错误描述。 在`extended_message`中，您将收到错误发送的确切参数的信息。 \n
\n

注意

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

\n
", "operationId": "create-token", "parameters": [ { "$ref": "#/components/parameters/merchant-id-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$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 }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/coupons/{code}/details": { "get": { "description": "按代码获取有关优惠券的信息。", "operationId": "get-coupon", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "key": "12", "list_of_values": [], "name": { "en": "Level", "ru": "Уровень" }, "skip_condition_on_nonexistent_key": true, "type": "int", "visible": false }, "schema": { "$ref": "#/components/schemas/CouponAttribute" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取优惠券", "tags": [ "coupons" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/coupons/{code}/redeem": { "post": { "description": "按代码兑换优惠券。", "operationId": "redeem-coupon", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "user_id": { "description": "用户ID。", "example": "1234", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "campaign_code": "new_campaign", "coupon_code": "ddgf5bn4", "coupon_id": 89613996, "expiration_date": "2019-12-31T00:00:00+00:00", "is_active": true, "project_id": 12345, "redeems_count_for_user": 10, "redeems_count_remain": 20, "subscription_coupon": null, "virtual_currency_amount": 200, "virtual_items": [] }, "schema": { "$ref": "#/components/schemas/Coupon" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "兑换优惠券", "tags": [ "coupons" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/currencies": { "get": { "description": "列示所有重复性货币。", "operationId": "get-currencies", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ "AED", "ALL", "AMD", "ARS", "AUD", "AZN", "BAM", "BBD", "BGN", "BHD", "BND", "BRL", "BYN", "BZD", "CAD", "CHF", "CLP", "CNY", "COP", "CRC", "CZK", "DKK", "DZD", "EGP", "EUR", "GBP", "GEL", "GHS", "GIP", "GTQ", "HKD", "HRK", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KRW", "KWD", "KZT", "LAK", "LBP", "LKR", "MAD", "MDL", "MKD", "MMK", "MNT", "MUR", "MXN", "MYR", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "SAR", "SEK", "SGD", "SVC", "THB", "TND", "TRY", "TWD", "UAH", "USD", "UYU", "UZS", "VEF", "VND", "XOF", "YER", "ZAR" ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有货币", "tags": [ "payments" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/payments": { "get": { "description": "列示所有重复性支付。", "operationId": "get-payments", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/user-id-query-param" }, { "$ref": "#/components/parameters/status-id-query-param" }, { "$ref": "#/components/parameters/datetime-from-query-param2" }, { "$ref": "#/components/parameters/datetime-to-query-param2" }, { "$ref": "#/components/parameters/subscription-id-query-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "date_payment": "2016-04-05T10:02:01+03:00", "id": 67683, "id_payment": 203960, "status": "fail", "subscription": { "charge_amount": 1, "comment": null, "currency": "RUB", "date_create": "2015-05-28T14:33:54+03:00", "date_end": "2016-04-05T10:02:07+03:00", "date_last_charge": "2015-06-03T16:07:29+03:00", "date_next_charge": "2015-06-04T00:00:00+03:00", "id": 3646, "plan": { "billing_retry": { "value": 1 }, "charge": { "amount": 1, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8nJ79", "grace_period": { "type": "day", "value": 0 }, "group_id": "charge", "id": 24, "localized_name": null, "name": null, "project_id": 12345, "refund_period": null, "status": { "value": "deleted" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": { "description": null, "group_id": "charge", "id": 1, "name": "charge" }, "status": "freeze", "user": { "id": "10", "name": "user2" } } }, { "date_payment": "2015-09-21T17:06:47+03:00", "id": 1531, "id_payment": 168866, "status": "done", "subscription": { "charge_amount": 1, "comment": " \r\n", "currency": "RUB", "date_create": "2015-09-21T17:06:47+03:00", "date_end": null, "date_last_charge": "2015-09-21T18:10:09+03:00", "date_next_charge": "2015-09-22T18:10:09+03:00", "id": 2004846, "plan": { "billing_retry": { "value": 1 }, "charge": { "amount": 1, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8nX9", "grace_period": { "type": "day", "value": 0 }, "group_id": "charge", "id": 200, "localized_name": null, "name": null, "project_id": 70, "refund_period": null, "status": { "value": "deleted" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": null, "status": "new", "user": { "id": "12", "name": "user1" } } } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有支付", "tags": [ "payments" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/plans": { "get": { "description": "列示所有重复性计划。", "operationId": "get-plans", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/external-id-query-param" }, { "$ref": "#/components/parameters/group-id-query-param" }, { "$ref": "#/components/parameters/product-id-query-param" }, { "$ref": "#/components/parameters/query-query-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "billing_retry": { "value": 1 }, "charge": { "amount": 19.99, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 17.99, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 2000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "10x more experience!" }, "expiration": { "type": "day", "value": 0 }, "external_id": "3b355320", "grace_period": { "type": "day", "value": 0 }, "group_id": null, "id": 241037, "localized_name": "Platinum VIP", "name": { "en": "Platinum VIP", "fr": "Le VIP-statut platinum" }, "project_id": 40797, "refund_period": null, "status": { "value": "active" }, "tags": [], "trial": { "type": "day", "value": 0 } }, { "billing_retry": { "value": 1 }, "charge": { "amount": 9.99, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 8, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 1000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "3x more experience!" }, "expiration": { "type": "day", "value": 0 }, "external_id": "0fe1b6fc", "grace_period": { "type": "day", "value": 0 }, "group_id": null, "id": 241038, "localized_name": "Gold Status", "name": { "en": "Gold Status", "fr": "Le statut d’or" }, "project_id": 40797, "refund_period": null, "status": { "value": "active" }, "tags": [], "trial": { "type": "day", "value": 0 } } ], "schema": { "items": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionsPlan" }, { "properties": { "localized_name": { "description": "计划名称（使用默认语言英文），复制name.en值。", "type": "string" } }, "type": "object" } ] }, "type": "array" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "列示所有计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "post": { "description": "创建重复性计划", "operationId": "create-plan", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "billing_retry": { "value": 1 }, "charge": { "amount": 10, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 8, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 1000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "2x more experience!" }, "expiration": { "type": "day", "value": null }, "external_id": "exp", "grace_period": { "type": "day", "value": 2 }, "name": { "en": "Experience boost" }, "refund_period": null, "status": { "value": "active" }, "trial": { "type": "day", "value": 7 } }, "schema": { "allOf": [ { "required": [ "name", "charge" ] }, { "$ref": "#/components/schemas/SubscriptionsPlan" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "external_id": "exp", "plan_id": 241082 }, "schema": { "properties": { "external_id": { "type": "string" }, "plan_id": { "type": "integer" } }, "type": "object" } } }, "description": "已创建。" } }, "security": [ { "basicAuth": [] } ], "summary": "创建计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/plans/{plan_id}": { "delete": { "description": "禁用重复性计划。", "operationId": "disable-plan", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "禁用计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "patch": { "description": "启用重复性计划。", "operationId": "enable-plan", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "启用计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "put": { "description": "更新订阅计划参数。", "operationId": "update-plan-parameters", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "billing_retry": { "value": 1 }, "charge": { "amount": 20, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 17, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 2000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "3x more experience!" }, "expiration": { "type": "day", "value": null }, "external_id": "exp", "grace_period": { "type": "day", "value": 2 }, "name": { "en": "Experience boost" }, "refund_period": null, "tags": [], "trial": { "type": "day", "value": 7 } }, "schema": { "$ref": "#/components/schemas/SubscriptionsPlanRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "billing_retry": { "value": 1 }, "charge": { "amount": 20, "currency": "USD", "period": { "type": "month", "value": 1 }, "prices": [ { "amount": 17, "currency": "EUR", "setup_fee": 1.5 }, { "amount": 2000, "currency": "JPY", "setup_fee": 2.5 } ] }, "description": { "en": "3x more experience!" }, "expiration": { "type": "day", "value": 0 }, "external_id": "exp", "grace_period": { "type": "day", "value": 2 }, "group_id": null, "id": 241082, "localized_name": "Experience boost", "name": { "en": "Experience boost" }, "project_id": 40797, "refund_period": null, "status": { "value": "active" }, "tags": [], "trial": { "type": "day", "value": 7 }, "type": "all" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "更新计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/plans/{plan_id}/delete": { "delete": { "description": "删除重复性计划。", "operationId": "delete-plan", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/plan-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "删除计划", "tags": [ "plans" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/products": { "get": { "description": "列示所有重复性产品。", "operationId": "get-products", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/group-id-query-param" }, { "$ref": "#/components/parameters/product-id-query-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "description": { "en": "Description in English." }, "group_id": "charge", "id": 714, "name": "Channel" }, { "description": { "en": "Description in English." }, "group_id": "notify", "id": 715, "name": "notify" }, { "description": { "en": "Description in English." }, "group_id": "charge", "id": 716, "name": "charge2" }, { "description": { "en": "Description in English." }, "group_id": "charge", "id": 486, "name": "Channel2" } ], "schema": { "items": { "$ref": "#/components/schemas/SubscriptionsProductWithId" }, "type": "array" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取产品", "tags": [ "products" ], "x-admin": true, "x-server": true }, "post": { "description": "创建产品。", "operationId": "create-product", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": { "en": "Kids TV" }, "group_id": "charge", "name": "Channel2" }, "schema": { "allOf": [ { "required": [ "name", "group_id" ] }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "product_id": 172003 }, "schema": { "properties": { "product_id": { "type": "integer" } }, "type": "object" } } }, "description": "Created." } }, "security": [ { "basicAuth": [] } ], "summary": "创建产品", "tags": [ "products" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/products/{product_id}": { "delete": { "description": "删除产品。", "operationId": "delete-product", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/product-id-path-param" } ], "responses": { "204": { "description": "No content." } }, "security": [ { "basicAuth": [] } ], "summary": "删除产品", "tags": [ "products" ], "x-admin": true, "x-server": true }, "put": { "description": "更新产品。", "operationId": "update-product", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/product-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "description": { "en": "Description in English." }, "group_id": "charge13", "name": "Channel23" }, "schema": { "allOf": [ { "required": [ "name", "group_id" ] }, { "$ref": "#/components/schemas/SubscriptionsProduct" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "description": { "en": "Description in English." }, "group_id": "charge13", "id": 1713603, "name": "Channel23" }, "schema": { "$ref": "#/components/schemas/SubscriptionsProductWithId" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "更新产品", "tags": [ "products" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/subscriptions/{subscription_id}": { "get": { "description": "通过ID获取特定订阅的详细信息。", "operationId": "get-subscription", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/subscription-id-path-param" } ], "responses": { "200": { "content": { "application/json": { "example": { "charge_amount": 0.03, "comment": "The subscription was not extended in due time", "currency": "USD", "date_create": "2018-09-21T16:54:59+03:00", "date_end": "2019-02-06T12:43:04+03:00", "date_last_charge": "2018-09-21T16:55:05+03:00", "date_next_charge": "2018-09-21T16:55:05+03:00", "id": 249579, "plan": { "external_id": "lowcost", "id": 601 }, "product": { "id": 123456 }, "status": "canceled", "user": { "id": "user1", "name": "John Smith" } }, "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取订阅", "tags": [ "subscriptions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/users/{user_id}/subscriptions/payments": { "get": { "description": "按用户列示所有重复性支付。", "operationId": "get-user-payments", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/status-id-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/datetime-from-query-param" }, { "$ref": "#/components/parameters/datetime-to-query-param" }, { "$ref": "#/components/parameters/subscription-id-query-param" } ], "responses": { "200": { "content": { "application/json": { "example": [ { "date_payment": "2016-04-05T10:02:01+03:00", "id": 6746083, "id_payment": 202789960, "status": "fail", "subscription": { "charge_amount": 200, "comment": null, "currency": "RUB", "date_create": "2015-05-28T14:33:54+03:00", "date_end": "2016-04-05T10:02:07+03:00", "date_last_charge": "2015-06-03T16:07:29+03:00", "date_next_charge": "2015-06-04T00:00:00+03:00", "id": 36946, "plan": { "charge": { "amount": 200, "currency": "RUB", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "E8n34J79", "grace_period": { "type": "day", "value": 0 }, "group_id": "charge", "id": 24, "localized_name": null, "name": null, "project_id": 1234, "refund_period": null, "status": { "value": "deleted" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "charge" }, "product": { "description": null, "group_id": "charge", "id": 1, "name": "charge" }, "status": "freeze", "user": { "id": "12", "name": "John" } } } ] } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "获取用户付款", "tags": [ "payments" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] }, "/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}": { "put": { "description": "更新重复性订阅。可以更新订阅的状态（`active`、`canceled`或`non_renewing`）以及推迟当前订阅的下一次收费日期。", "operationId": "update-subscription", "parameters": [ { "$ref": "#/components/parameters/project-id-path-param" }, { "$ref": "#/components/parameters/user-id-path-param" }, { "$ref": "#/components/parameters/subscription-id-path-param" } ], "requestBody": { "content": { "application/json": { "example": { "status": "active" }, "schema": { "$ref": "#/components/schemas/Subscription" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "charge_amount": 0.03, "currency": "USD", "date_create": "2018-09-21T16:54:59+03:00", "date_end": null, "date_last_charge": "2018-09-21T16:55:05+03:00", "date_next_charge": "2018-09-21T16:55:05+03:00", "id": 24953579, "plan": { "billing_retry": { "value": 1 }, "charge": { "amount": 0.03, "currency": "USD", "period": { "type": "day", "value": 1 } }, "description": null, "expiration": { "type": "day", "value": 0 }, "external_id": "lowcost", "grace_period": { "type": "day", "value": 2 }, "group_id": "newPlans", "id": 66001, "localized_name": null, "name": null, "project_id": 18404, "refund_period": null, "status": { "value": "active" }, "tags": null, "trial": { "type": "day", "value": 0 }, "type": "all" }, "product": null, "status": "active", "user": { "id": "jb1", "name": "J.Black" } } } }, "description": "OK." } }, "security": [ { "basicAuth": [] } ], "summary": "更新订阅", "tags": [ "subscriptions" ], "x-admin": true, "x-server": true }, "servers": [ { "url": "https://api.xsolla.com/merchant/v2" } ] } }, "tags": [ { "name": "token", "x-displayName": "令牌" }, { "name": "plans", "x-displayName": "计划" }, { "name": "products", "x-displayName": "产品" }, { "name": "subscriptions", "x-displayName": "Subscription management" }, { "name": "payments", "x-displayName": "支付" }, { "name": "promotions", "x-displayName": "促销活动" }, { "name": "coupons", "x-displayName": "优惠券" }, { "name": "subscription-management", "x-displayName": "Subscription management" } ], "x-tagGroups": [ { "name": "Admin subscription management", "tags": [ "token", "plans", "products", "subscriptions", "payments", "promotions", "coupons" ] }, { "name": "User subscription management", "tags": [ "subscription-management" ] } ] }