# 정기 결제 API # 개요 * **버전:** 2.0 * **서버**: `https://api.xsolla.com/merchant/v2/` 본 API 참조는 정기 결제, 쿠폰 및 프로모션 관리 엔드포인트에 관하여 기술하고 있습니다. 정기 결제에 대한 더 자세한 내용은 [제품 가이드](https://developers.xsolla.com/ko/doc/subscriptions) 및 [용어집](https://developers.xsolla.com/ko/doc/subscriptions/integration-guide/get-started/#general_glossary)을 참조하십시오. Version: 2.0 ## Security ### basicAuth 엑솔라 API는 기본 액세스 인증을 사용합니다. API에 대한 모든 요청은 `Authorization: Basic ` 헤더를 포함해야 합니다. 여기에서 ``는 Base64 표준에 따라 인코딩된 `merchant_id:api_key` 쌍입니다. [관리자 페이지](https://publisher.xsolla.com/)로 이동하여 다음 매개 변수를 찾으세요.
API 키 작업에 대한 자세한 내용은 [API 참조](https://developers.xsolla.com/ko/api/getting-started/#api_keys_overview)를 확인하세요. Type: http Scheme: basic ### subscriptionsManagementJwtAuth Type: http Scheme: bearer ## Download OpenAPI description [정기 결제 API](https://developers.xsolla.com/_bundle/@l10n/ko/api/subscriptions/index.yaml) ## 토큰 ### 토큰 생성 - [POST /merchants/{merchant_id}/token](https://developers.xsolla.com/ko/api/subscriptions/token/create-token.md): 임의의 사용자 매개 변수로 토큰을 생성할 수 있습니다. 토큰을 받을 때 이러한 매개 변수를 보내고 성공적인 결제 후에 다시 받습니다. 토큰은 이 문서에 설명되어 있거나 사용자가 미리 정의한 매개 변수만 포함할 수 있습니다. 매개 변수가 잘못된 형식으로 전송되거나 잘못된 유형인 경우 토큰이 발급되지 않습니다. JSON 본문에 오류 설명이 포함된 422 HTTP 코드를 받게 됩니다. extended_message에서 정확히 어떤 매개 변수가 잘못 전송되었는지에 대한 정보를 받게 됩니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ## Plans ### Get Plans - [GET /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/ko/api/subscriptions/plans/get-plans.md): Lists all subscription plans. ### 요금제 생성 - [POST /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/ko/api/subscriptions/plans/create-plan.md): Creates a subscription plan. ### 요금제 비활성화 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ko/api/subscriptions/plans/disable-plan.md): Disables a subscription plan. ### 요금제 활성화 - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ko/api/subscriptions/plans/enable-plan.md): Enables a subscription plan. ### 요금제 업데이트 - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ko/api/subscriptions/plans/update-plan-parameters.md): Updates subscription plan parameters. ### 요금제 삭제 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://developers.xsolla.com/ko/api/subscriptions/plans/delete-plan.md): Deletes a subscription plan. ## 제품 ### 제품 가져오기 - [GET /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/ko/api/subscriptions/products/get-products.md): Lists all subscription-based products. ### Create Product - [POST /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/ko/api/subscriptions/products/create-product.md): Creates a subscription-based product. ### Delete Product - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/ko/api/subscriptions/products/delete-product.md): Deletes a subscription-based product. ### Update Product - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/ko/api/subscriptions/products/update-product.md): Updates a subscription-based product. ## Subscription management ### Get Subscriptions - [GET /merchants/{merchant_id}/subscriptions](https://developers.xsolla.com/ko/api/subscriptions/subscriptions/get-subscriptions.md): 모든 반복 정기 결제를 나열합니다.주의이 API 메소드는 높은 부하에서는 사용할 수 없습니다. 최대 부하는 분당 20개의 요청입니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### Get Subscription - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ko/api/subscriptions/subscriptions/get-subscription.md): Gets a specific subscription details by ID. ### Update Subscription - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ko/api/subscriptions/subscriptions/update-subscription.md): 상태를 변경(active, canceled, 혹은 non_renewing)하거나 다음 청구 날짜를 연기하여 정기 결제를 업데이트합니다. ## 결제 ### Get Currencies - [GET /projects/{project_id}/subscriptions/currencies](https://developers.xsolla.com/ko/api/subscriptions/payments/get-currencies.md): Lists all supported subscription currencies. ### Get Payments - [GET /projects/{project_id}/subscriptions/payments](https://developers.xsolla.com/ko/api/subscriptions/payments/get-payments.md): Lists all subscription payments. ### 사용자 결제 가져오기 - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://developers.xsolla.com/ko/api/subscriptions/payments/get-user-payments.md): Lists all payments made by a specific user. ## 프로모션 ### 프로모션 목록 가져오기 - [GET /merchants/{merchant_id}/promotions](https://developers.xsolla.com/ko/api/subscriptions/promotions/get-promotions-list.md): 모든 프로모션 목록입니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### Create Promotion - [POST /merchants/{merchant_id}/promotions](https://developers.xsolla.com/ko/api/subscriptions/promotions/create-promotion.md): 새로운 프로모션을 생성합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 삭제 - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ko/api/subscriptions/promotions/delete-promotion.md): 프로모션을 삭제합니다. enabled = false인 프로모션만 삭제할 수 있습니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 대상 가져오기 - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ko/api/subscriptions/promotions/get-promotion.md): 프로모션을 검색합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 업데이트 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ko/api/subscriptions/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://developers.xsolla.com/ko/api/subscriptions/promotions/get-payment-systems.md): 프로모션에 지원되는 결제 시스템을 가져옵니다. 목록이 비어 있으면 프로모션이 모든 결제 시스템에 적용됩니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### Set Payment Systems - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://developers.xsolla.com/ko/api/subscriptions/promotions/set-payment-systems.md): 프로모션에 지원되는 결제 시스템을 설정합니다. 목록이 비어 있으면 프로모션이 모든 결제 시스템에 적용됩니다. 프로모션이 읽기 전용(read_only = true)인 경우 이 메서드를 호출할 수 없습니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### Get Validity Periods - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/ko/api/subscriptions/promotions/get-validity-periods.md): 프로모션이 유효한 날짜/시간 범위를 가져옵니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### Set Validity Periods - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/ko/api/subscriptions/promotions/set-validity-periods.md): 프로모션이 유효한 날짜/시간 범위를 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 기존 기간을 편집할 수 없지만 새 기간을 추가할 수는 있습니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 검토 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://developers.xsolla.com/ko/api/subscriptions/promotions/review-promotion.md): 프로모션을 활성화하기 전에 검토해야 합니다. 이 메소드는 오류 목록을 반환합니다(있는 경우). 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 보상 가져오기 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/ko/api/subscriptions/promotions/get-rewards.md): 프로모션과 관련된 보상 목록을 가져옵니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 보상 설정 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/ko/api/subscriptions/promotions/set-rewards.md): 프로모션에 대한 보상을 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 보상을 업데이트할 수 없습니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 대상 가져오기 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/ko/api/subscriptions/promotions/get-subject.md): 프로모션 대상에 대한 정보를 얻습니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 대상 설정 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/ko/api/subscriptions/promotions/set-subject.md): 프로모션의 대상을 설정합니다. 프로모션이 읽기 전용(read_only = true)인 경우 프로모션 대상을 업데이트할 수 없습니다. 프로모션 대상은 다음 값을 가질 수 있습니다: purchase, items, 또는 packages. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션 설정/해제 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://developers.xsolla.com/ko/api/subscriptions/promotions/toggle-promotion.md): 프로모션 상태를 enabled에서 disabled로 전환하고, 그 반대로도 전환합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ## 쿠폰 ### 캠페인 생성 - [POST /merchants/{merchant_id}/coupon_promotions](https://developers.xsolla.com/ko/api/subscriptions/coupons/create-campaign.md): 새로운 쿠폰 캠페인을 생성합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 캠페인에 쿠폰 추가 - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://developers.xsolla.com/ko/api/subscriptions/coupons/add-coupon-to-campaign.md): 쿠폰 캠페인에 쿠폰 코드를 추가합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 프로모션에 캠페인 연결 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://developers.xsolla.com/ko/api/subscriptions/coupons/attach-campaign-to-promotion.md): 특정 프로모션에 쿠폰 캠페인을 첨부합니다. 주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다. ### 쿠폰 가져오기 - [GET /projects/{project_id}/coupons/{code}/details](https://developers.xsolla.com/ko/api/subscriptions/coupons/get-coupon.md): Get coupon details by its code. ### 쿠폰 사용 - [POST /projects/{project_id}/coupons/{code}/redeem](https://developers.xsolla.com/ko/api/subscriptions/coupons/redeem-coupon.md): 쿠폰 코드로 쿠폰을 사용합니다. ## Subscription management ### List subscriptions - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/list-subscriptions.md) ### Get management settings - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/get-management-settings.md) ### Get subscription - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/get-management-subscription.md) ### Activate subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/activate-subscription.md) ### Cancel subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/cancel-subscription.md) ### Get change plan link - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/get-change-plan-link.md) ### Get payment account - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/get-payment-account.md) ### Manage payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/manage-payment-account.md) ### List payment accounts - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/list-payment-accounts.md) ### Link payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/link-payment-account.md) ### Unlink payment account - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/unlink-payment-account.md) ### List plans for change - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://developers.xsolla.com/ko/api/subscriptions/subscription-management/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://developers.xsolla.com/ko/api/subscriptions/subscription-management/get-plan-for-change.md)