# 정기 결제 API

# Overview {% #overview %}

* **Version:** 2.0
* **Servers**: `https://api.xsolla.com/merchant/v2/`

This API reference describes endpoints for managing subscriptions, coupons, and promotions.
To get more information about Subscriptions, see the [product guide](https://developers.xsolla.com/ko/doc/subscriptions) and the [glossary](https://developers.xsolla.com/ko/doc/subscriptions/integration-guide/get-started/#general_glossary).

Version: 2.0

## Security

### basicAuth

Xsolla API uses basic access authentication. All requests to API must contain the `Authorization: Basic <your_authorization_basic_key>` header, where `<your_authorization_basic_key>` is the `merchant_id:api_key` pair encoded according to the Base64 standard.
Go to **[Xsolla Publisher Account](https://publisher.xsolla.com/) > Company settings** to find <ul><li> `merchant_id` on the Company tab</li><li> `api_key` on the API key tab.</li></ul><br>

Type: http
Scheme: basic

### managementJwtAuth

Type: http
Scheme: bearer

### projectUserJwtAuth

Type: http
Scheme: bearer

## Download OpenAPI description

[정기 결제 API](https://xsolla.redocly.app/_bundle/@l10n/ko/api/subscriptions/index.yaml)

## 토큰

### 토큰 생성

 - [POST /merchants/{merchant_id}/token](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_token/create-token.md): 임의의 사용자 매개 변수로 토큰을 생성할 수 있습니다. 토큰을 받을 때 이러한 매개 변수를 보내고 성공적인 결제 후에 다시 받습니다. 토큰은 이 문서에 설명되어 있거나 사용자가 미리 정의한 매개 변수만 포함할 수 있습니다.

매개 변수가 잘못된 형식으로 전송되거나 잘못된 유형인 경우 토큰이 발급되지 않습니다. JSON 본문에 오류 설명이 포함된 422 HTTP 코드를 받게 됩니다. extended_message에서 정확히 어떤 매개 변수가 잘못 전송되었는지에 대한 정보를 받게 됩니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

## Plans

### List plans

 - [GET /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/get-plans.md): Lists all subscription plans.

### Create plan

 - [POST /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/create-plan.md): Creates a subscription plan.

### Disable plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/disable-plan.md): Disables a subscription plan.

### Enable plan

 - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/enable-plan.md): Enables a subscription plan.

### Update plan

 - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/update-plan-parameters.md): Updates subscription plan parameters.

### Delete plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_plans/delete-plan.md): Deletes a subscription plan.

## 제품

### List products

 - [GET /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_products/get-products.md): Lists all subscription-based products.

### Create product

 - [POST /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_products/create-product.md): Creates a subscription-based product.

### Delete product

 - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_products/delete-product.md): Deletes a subscription-based product.

### Update product

 - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_products/update-product.md): Updates a subscription-based product.

## Subscriptions

### Get user account link

 - [POST /api/v1/projects/{projectId}/subscriptions/user_account](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_subscriptions/post-subscriptions-get-user-account-link.md)

### List subscriptions

 - [GET /merchants/{merchant_id}/subscriptions](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_subscriptions/get-subscriptions.md): 모든 반복 정기 결제를 나열합니다.주의이 API 메소드는 높은 부하에서는 사용할 수 없습니다. 최대 부하는 분당 20개의 요청입니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get subscription

 - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_subscriptions/get-subscription.md): Gets a specific subscription details by ID.

### Update subscription

 - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_subscriptions/update-subscription.md): 상태를 변경(active, canceled, 혹은 non_renewing)하거나 다음 청구 날짜를 연기하여 정기 결제를 업데이트합니다.

## 결제

### List currencies

 - [GET /projects/{project_id}/subscriptions/currencies](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_payments/get-currencies.md): Lists all supported subscription currencies.

### List payments

 - [GET /projects/{project_id}/subscriptions/payments](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_payments/get-payments.md): Lists all subscription payments.

### List user payments

 - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_payments/get-user-payments.md): Lists all payments made by a specific user.

## 프로모션

### List promotions

 - [GET /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-promotions-list.md): 모든 프로모션 목록입니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Create promotion

 - [POST /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/create-promotion.md): 새로운 프로모션을 생성합니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Delete promotion

 - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/delete-promotion.md): 프로모션을 삭제합니다. enabled = false인 프로모션만 삭제할 수 있습니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-promotion.md): 프로모션을 검색합니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Update promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/update-promotion.md): 프로모션을 업데이트합니다. 프로모션이 읽기 전용(read_only = true)인 경우 project_id 매개 변수를 변경할 수 없습니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get payment systems

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-payment-systems.md): 프로모션에 지원되는 결제 시스템을 가져옵니다. 목록이 비어 있으면 프로모션이 모든 결제 시스템에 적용됩니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Set payment systems

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/set-payment-systems.md): 프로모션에 지원되는 결제 시스템을 설정합니다. 목록이 비어 있으면 프로모션이 모든 결제 시스템에 적용됩니다. 프로모션이 읽기 전용(read_only = true)인 경우 이 메서드를 호출할 수 없습니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get validity periods

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-validity-periods.md): 프로모션이 유효한 날짜/시간 범위를 가져옵니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Set validity periods

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/set-validity-periods.md): 프로모션이 유효한 날짜/시간 범위를 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 기존 기간을 편집할 수 없지만 새 기간을 추가할 수는 있습니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Review promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/review-promotion.md): 프로모션을 활성화하기 전에 검토해야 합니다. 이 메소드는 오류 목록을 반환합니다(있는 경우).

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get rewards

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-rewards.md): 프로모션과 관련된 보상 목록을 가져옵니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Set rewards

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/set-rewards.md): 프로모션에 대한 보상을 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 보상을 업데이트할 수 없습니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get promotion scope

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/get-subject.md): 프로모션 대상에 대한 정보를 얻습니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Set promotion scope

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/set-subject.md): 프로모션의 대상을 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 프로모션 대상을 업데이트할 수 없습니다. 프로모션 대상은 다음 값을 가질 수 있습니다: purchase, items, 또는 packages.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Toggle promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_promotions/toggle-promotion.md): 프로모션 상태를 enabled에서 disabled로 전환하고, 그 반대로도 전환합니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

## 쿠폰

### Create campaign

 - [POST /merchants/{merchant_id}/coupon_promotions](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_coupons/create-campaign.md): 새로운 쿠폰 캠페인을 생성합니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Add coupon to campaign

 - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_coupons/add-coupon-to-campaign.md): 쿠폰 캠페인에 쿠폰 코드를 추가합니다.

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Attach campaign to promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_coupons/attach-campaign-to-promotion.md): 특정 프로모션에 쿠폰 캠페인을 첨부합니다. 

  주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### Get coupon

 - [GET /projects/{project_id}/coupons/{code}/details](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_coupons/get-coupon.md): Get coupon details by its code.

### Redeem coupon

 - [POST /projects/{project_id}/coupons/{code}/redeem](https://xsolla.redocly.app/ko/api/subscriptions/admin_api_coupons/admin-redeem-coupon.md): 쿠폰 코드로 쿠폰을 사용합니다.

## Subscriptions

### List active subscriptions

 - [GET /api/user/v1/projects/{project_id}/subscriptions](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/get-user-active-subscriptions.md)

### Buy subscription

 - [POST /api/user/v1/projects/{project_id}/subscriptions/buy](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/buy-subscription.md)

### Get management link

 - [POST /api/user/v1/projects/{project_id}/subscriptions/manage](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/get-manage-subscriptions-link.md)

### Get user account link

 - [GET /api/user/v1/projects/{project_id}/subscriptions/user_account](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/get-user-account-link.md)

### Get subscription

 - [GET /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/get-user-subscription.md)

### Cancel subscription

 - [PUT /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/cancel-user-subscription.md)

### Renew subscription

 - [POST /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/renew](https://xsolla.redocly.app/ko/api/subscriptions/client_api_subscriptions/renew-user-subscription.md)

## Catalog

### List products (no auth)

 - [GET /api/public/v1/projects/{project_id}/products](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/list-public-products.md)

### List plans by product (no auth)

 - [GET /api/public/v1/projects/{project_id}/products/{productId}/user_plans](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/list-public-plans-by-product.md)

### List plans (no auth)

 - [GET /api/public/v1/projects/{project_id}/user_plans](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/list-public-plans.md)

### Get catalog

 - [GET /api/user/v1/projects/{project_id}/catalog](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/get-subscriptions-catalog.md)

### List plans

 - [GET /api/user/v1/projects/{project_id}/plans](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/get-subscription-plans.md)

### List products

 - [GET /api/user/v1/projects/{project_id}/products](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/get-subscription-products.md)

### List plans by product

 - [GET /api/user/v1/projects/{project_id}/products/{productId}/plans](https://xsolla.redocly.app/ko/api/subscriptions/client_api_catalog/get-subscription-plans-by-product.md)

## 쿠폰

### Redeem coupon

 - [POST /api/user/v1/projects/{project_id}/redeem_coupon](https://xsolla.redocly.app/ko/api/subscriptions/client_api_coupons/redeem-coupon.md)

## Subscriptions

### List subscriptions

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/list-subscriptions.md)

### Get management settings

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/get-management-settings.md)

### Get subscription

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/get-management-subscription.md)

### Activate subscription

 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/activate-subscription.md)

### Cancel subscription

 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/cancel-subscription.md)

### Get change plan link

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/get-change-plan-link.md)

### List plans for change

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/list-plans-for-change.md)

### Get plan for change

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_subscriptions/get-plan-for-change.md)

## Payment accounts

### Get payment account

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_payment-accounts/get-payment-account.md)

### Manage payment account

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_payment-accounts/manage-payment-account.md)

### List payment accounts

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_payment-accounts/list-payment-accounts.md)

### Link payment account

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_payment-accounts/link-payment-account.md)

### Unlink payment account

 - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://xsolla.redocly.app/ko/api/subscriptions/user_management_api_payment-accounts/unlink-payment-account.md)