> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Store Marketplace 리뎀션

> Microsoft Store 애드온을 만들고, PlayFab 번들에 연결하고, RedeemMicrosoftStoreInventoryItems를 사용하여 XBOX 및 Windows 구매를 리뎀션합니다.

# PlayFab과 Microsoft Store를 설정하여 구매 활성화

이 자습서에서는 다음을 수행하는 방법을 보여줍니다.

* Microsoft Store에서 구매 가능한 제품 만들기
* PlayFab 번들에 매핑
* [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API를 사용하여 구매한 아이템을 플레이어의 인벤토리로 리뎀션

## 필수 구성 요소

1. PlayFab의 [Game Manager](https://developer.playfab.com/)의 타이틀.
2. 다음을 포함하는 [선택한 타이틀과 Microsoft Store 간의 기존 통합](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft):
   * Game Manager에 설치되고 구성된 **XBOX Network** 애드온.
   * Partner Center에 구성된 **Product Group**, **Dev Studio**, **Business Partner ID**.
3. 앱에 액세스할 수 있는 [Partner Center](https://partner.microsoft.com/) 계정.
4. Partner Center에 이미 만들어진 앱.
5. Redeem API를 호출하는 플레이어는 XBOX Live ID(예: `LoginWithXbox`를 통해)를 사용하여 PlayFab에 인증되어야 합니다. 다른 ID 유형(예: CustomID 또는 이메일)으로 인증된 플레이어는 이 플로우에 필요한 XBOX 컨텍스트가 없습니다.

## 1단계: Partner Center에서 애드온 만들기

[마켓플레이스 통합 설정](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#step-1-create-your-add-on-in-partner-center)의 일부로 Partner Center에서 애드온을 만들지 않은 경우 다음 단계를 따르세요.

1. [Partner Center](https://partner.microsoft.com/)에 로그인하여 앱으로 이동합니다.
2. **Add-ons**에서 **Create a new add-on**을 선택합니다.
3. 적절한 제품 유형을 선택합니다.
   * 재구매 가능한 아이템(통화, 소모품 팩)의 경우 **Developer-managed consumable**.
   * 일회성 구매(DLC, 시즌 패스, 코스메틱 잠금 해제)의 경우 **Durable**.
4. 애드온 구성(가격, 설명 등)을 완료하고 제출합니다.
5. 애드온을 만든 후 Partner Center에 표시된 **Store ID**—영숫자 문자열(예: `9NBLGGH42CFD`)을 기록해 두세요. PlayFab의 마켓플레이스 매핑에 이 값을 사용하고, 개발자 정의 Product ID나 애드온 이름은 **사용하지 마세요**.

<Info>
  **Store-managed consumables는 지원되지 않습니다.** `RedeemMicrosoftStoreInventoryItems` API에서는 Developer-managed consumables와 Durables만 작동합니다. Partner Center는 Developer-managed consumables가 XBOX에서 지원되지 않는다고 제안하는 경고를 표시할 수 있습니다. 이 경고는 PlayFab 리뎀션 플로우를 사용할 때는 적용되지 않습니다. 자세한 내용은 [Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type)을 참조하세요.
</Info>

6. 테스트할 sandbox나 환경에 애드온을 게시합니다.

## 2단계: Game Manager에서 번들 만들기

<Note>
  **Game Manager**에서 번들을 만들기 전에 카탈로그에서 번들에 추가하려는 아이템을 만들고 게시하세요. 아이템 만드는 방법에 대한 안내가 필요하면 [이 단계](/services/playfab/economy-monetization/economy-v2/tutorials/craftingGame/crafting-game-game-manager#step-4---create-your-first-item)를 참조하세요.
</Note>

**Game Manager**와 **Microsoft Store** 간에 마켓플레이스 매핑을 활성화하려면 Game Manager에서 **번들**을 만들어야 합니다. 번들은 다양한 수량의 여러 아이템을 포함할 수 있으며, PlayFab은 리뎀션되면 이를 플레이어의 인벤토리에 추가합니다. 다음 단계를 따르세요.

1. [Game Manager](https://developer.playfab.com/)로 이동하여 **Title**로 이동합니다.
2. 왼쪽 탐색 메뉴에서 **Engage** > **Economy**를 선택합니다.
3. **Bundles** 탭을 선택합니다.
4. **New bundle**을 선택합니다.
5. 아이템 및 가격과 같이 **번들**에 원하는 정보를 추가합니다.
6. 페이지 끝까지 아래로 스크롤하여 플레이어가 즉시 리뎀션할 수 있도록 하려면 **Save and publish**를 선택합니다. 나중에 게시하려면 **Save as draft**를 선택합니다.

### 번들에 아이템 추가

번들 자체는 플레이어에게 아이템을 부여하지 않습니다. 먼저 아이템을 연결해야 합니다. 리뎀션되면 번들은 특정 플레이어에게 해당 아이템을 부여합니다.

번들에 아이템을 추가하려면:

1. 편집 모드에서 **Items** 섹션으로 이동합니다.
2. **Add**를 선택합니다. 모든 카탈로그 아이템을 표시하는 창이 나타납니다.
3. 원하는 아이템을 찾아 옆에 있는 **Add**를 선택합니다.
4. 하단의 **Add** 버튼을 선택합니다.

## 3단계: 마켓플레이스 매핑 활성화

플레이어가 Microsoft Store에서 제품을 구매할 때 Game Manager에서 올바르게 일치되고 할당되도록 하려면 번들의 **Marketplace Mapping**을 구성해야 합니다.

1. 편집 모드에서 번들로 이동합니다.
2. **Marketplace Mapping** 섹션까지 아래로 스크롤합니다.
3. **Marketplace** 드롭다운에서 **MicrosoftStore**(대/소문자 구분, 정확히 `MicrosoftStore`여야 함)를 선택합니다.
4. **Marketplace ID**의 경우 Partner Center의 정확한 **Store ID**(예: `9NBLGGH42CFD`)를 사용합니다. 개발자 정의 Product ID를 **사용하지 마세요**.
5. 해당 행 오른쪽에서 **+** 를 선택하고 변경 사항을 **저장**합니다.

<Info>
  번들이 리뎀션 중 일치되려면 (드래프트로 남겨두지 않고) **게시**되어야 합니다. 리뎀션 API는 게시되지 않은 카탈로그 아이템을 감지하지 않습니다.
</Info>

alternate ID에 대한 자세한 내용은 [Alternate IDs](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids)를 참조하세요.

## 4단계: 플레이어 인증

리뎀션 호출을 하기 전에 플레이어가 올바르게 인증되었는지 확인해야 합니다. XBOX 및 Microsoft Store 시나리오의 경우 [LoginWithXbox](https://learn.microsoft.com/en-us/rest/api/playfab/client/authentication/login-with-xbox)를 사용하여 플레이어를 PlayFab로 인증합니다.

`LoginWithXbox` 호출이 성공하면 PlayFab은 `X-EntityToken` 키가 있는 리뎀션 호출의 헤더에서 사용해야 하는 `EntityToken`을 반환합니다.

## 5단계: XBOX 토큰 획득

`RedeemMicrosoftStoreInventoryItems` API는 `XboxToken` 매개 변수에 유효한 XBOX 토큰이 필요합니다. 이 토큰은 인증에 사용되는 `EntityToken`과 별개입니다.

* **GDK C API**를 사용하는 경우 다음을 사용합니다.

  ```cpp theme={null}
  XUserGetTokenAndSignatureAsync  // with method "POST", URL "https://playfabapi.com/", and empty body ""
  ```

세 매개 변수(method, URL, body) 모두 표시된 대로 정확히 제공해야 합니다. 잘못 얻은 토큰은 Microsoft Store Collections API 쿼리가 조용히 실패하여 아이템을 반환하지 않습니다.

## 6단계: 구매하기

PlayFab을 통해 리뎀션하기 전에 플레이어는 Microsoft Store에서 애드온을 구매해야 합니다. 이 구매는 XBOX 또는 Windows Store 인터페이스를 통해 이루어질 수 있습니다.

<Note>
  sandbox 환경에서 테스트하는 경우 플레이어 계정과 애드온이 모두 동일한 sandbox에 게시되어 있는지 확인하세요. 리뎀션 API가 리뎀션할 아이템을 찾으려면 플레이어의 계정에 **리뎀션되지 않은 구매**가 있어야 합니다.
</Note>

## 7단계: 구매 리뎀션

플레이어가 인증되고 XBOX 토큰이 획득되고 구매가 완료되면 [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API를 호출할 준비가 되었습니다.

`EntityToken`을 `X-EntityToken` 헤더로 포함하고 요청 본문에 XBOX 토큰을 제공하세요.

```json theme={null}
{
    "XboxToken": "{Your Xbox token from GetTokenAndSignatureAsync}"
}
```

### 리뎀션 작동 방식

`RedeemMicrosoftStoreInventoryItems` 호출이 이루어지면 PlayFab은 XBOX 토큰을 사용하여 Microsoft Store Collections API를 쿼리하여 플레이어의 계정과 연결된 리뎀션되지 않은 구매를 찾습니다. 그런 다음 이러한 구매를 PlayFab 번들 Marketplace Mappings에 구성된 **Store ID**와 일치시키고 해당 아이템을 부여합니다.

성공적인 응답에는 다음을 포함하는 [RedeemMicrosoftStoreInventoryItemsResponse](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)와 함께 `200` 상태 코드가 포함됩니다.

* **Succeeded**—성공적으로 리뎀션된 아이템 목록.
* **Failed**—리뎀션에 실패한 아이템 목록.
* **TransactionIds**—각 리뎀션 트랜잭션에 대한 ID.

각 리뎀션 작업은 플레이어의 트랜잭션 이력에서 해당 이벤트를 트리거하며, [Game Manager](https://developer.playfab.com/)의 플레이어 개요 페이지 아래의 **Transaction History (V2)** 탭에서 검색할 수 있습니다.

플레이어의 트랜잭션 이력에 있는 레코드와 함께 `items_redeemed` **PlayStream** 이벤트도 트리거되고 기록됩니다. [Game Manager](https://developer.playfab.com/)의 왼쪽 탐색 모음의 **Analyze** 섹션 아래에 있는 **Data** 페이지로 이동하여 타이틀의 이러한 로그에 액세스할 수 있습니다.

### Developer-managed consumables의 이행

리뎀션된 제품이 **Developer-managed consumable**인 경우, PlayFab은 성공적인 리뎀션 후 사용자를 대신하여 Microsoft Store에 자동으로 **이행됨**(소비됨)으로 보고합니다. 이행 단계는 플레이어가 동일한 소모품을 재구매하기 전에 필요합니다. 성공적인 리뎀션 후에도 소모품이 이행된 것으로 표시되지 않는 경우 `RedeemMicrosoftStoreInventoryItems` 호출을 다시 시도하세요. 문제가 지속되면 지원 채널을 통해 PlayFab 팀에 에스컬레이션하세요. Durables는 일회성 구매이므로 이행이 필요하지 않습니다. 자세한 내용은 [Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds)를 참조하세요.

## 문제 해결

리뎀션 호출이 `200`을 반환하지만 세 배열(`Succeeded`, `Failed`, `TransactionIds`) 모두가 비어 있는 경우 Microsoft Store Collections API가 일치하는 아이템을 찾지 못한 것입니다. 이 결과는 일반적으로 구성 문제를 나타냅니다. 일반적인 원인과 해결 방법의 전체 목록은 Microsoft Store 통합 가이드의 [문제 해결 섹션](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#troubleshooting)을 참조하세요.

API가 HTTP 오류(예: 400)를 반환하는 경우 `InvalidCatalogItemConfiguration`, `InvalidXboxLiveToken` 또는 `AccountNotLinked`와 같은 코드에 대한 오류 응답을 확인하세요.

## 참고 항목

* [Microsoft Store 마켓플레이스 통합](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft)
* [RedeemMicrosoftStoreInventoryItems API reference](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)
* [Fraud prevention 빠른 시작](/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart)
* [XBOX Live add-on configuration](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on)
* [Apple 앱을 Game Manager에 성공적으로 통합하는 방법](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple)
* [Google 앱을 Game Manager에 성공적으로 통합하는 방법](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google)


## Related topics

- [Marketplace 리뎀션 - 개요](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview.md)
- [Steam Marketplace 리뎀션](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/steam.md)
- [Google Marketplace 리뎀션](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/google.md)
- [Apple App Store 인앱 구매 리뎀션](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/apple.md)
- [Marketplace 통합 - Microsoft Store](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft.md)