# 구매

> Use the SDK to make virtual purchases and redeem real money purchases.

`Purchases` 네임스페이스에서 메서드를 사용하면 현재 로그인한 사용자의 구매를 생성할 수 있습니다.

> **Note:**
>
> 이 네임스페이스에 있는 모든 메서드로 인해 [EconomyException](./exceptions.md#economyexception)이 발생할 수 있습니다.

## MakeVirtualPurchaseAsync##makevirtualpurchase

ID별로 지정된 가상 구매를 생성합니다.

이 메서드는 필요에 따라 `MakeVirtualPurchaseOptions` 오브젝트를 사용합니다. 이를 사용해 플레이어 인벤토리에 있는 아이템의 `PlayersInventoryItems` ID를 지정하여 구매 비용에 사용되도록 할 수 있습니다. 이렇게 지정하지 않으면 비용에 사용되는 아이템이 자동으로 정해집니다.

`MakeVirtualPurchaseResult`가 반환됩니다.

예시:

```cs title="C#"
string purchaseID = "BUY_A_SWORD";
MakeVirtualPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.MakeVirtualPurchaseAsync(purchaseID);
```

`PlayersInventoryItem` ID를 사용하는 다른 예시:

```cs title="C#"
string purchaseID = "BUY_A_SWORD";
MakeVirtualPurchaseOptions options = new MakeVirtualPurchaseOptions
{
    PlayersInventoryItemIds = new List<string> { "playersInventoryItemId1", "playersInventoryItemId2" }
};

MakeVirtualPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.MakeVirtualPurchaseAsync(purchaseID, options);
```

### MakeVirtualPurchaseOptions##makevirtualpurchaseoptions

`MakeVirtualPurchaseAsync` 호출의 옵션 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `PlayersInventoryItemIds`: 문자열 목록입니다. 기본값은 `null`입니다. 구매 비용에 사용하려는 플레이어 인벤토리에 있는 아이템의 `PlayersInventoryItem` ID입니다.

### MakeVirtualPurchaseResult##makevirtualpurchaseresult

이 오브젝트는 `MakeVirtualPurchaseAsync` 호출로 반환됩니다. 포함되는 필드는 다음과 같습니다.

* `Costs`: 구매에서 지출된 비용을 나타내는 `Costs` 오브젝트입니다. 다음 필드 2개로 구성됩니다.

  * `Currency`: [`CurrencyExchangeItem`](#currencyexchangeitem) 목록이며, 구매를 생성하는 데 사용되는 재화를 설명해 줍니다.
  * `Inventory`: [`InventoryExchangeItem`](#inventoryexchangeitem) 목록이며, 구매를 생성하기 위해 비용으로 사용되는 아이템을 설명해 줍니다.

* `Rewards`: `Rewards` 오브젝트이며, 구매의 대가로 제공되는 보상을 나타냅니다. 위의 오브젝트처럼 다음 필드 2개로 구성됩니다.

  * `Currency`: [`CurrencyExchangeItem`](#currencyexchangeitem) 목록이며, 구매의 일환으로 보상되는 재화를 설명해 줍니다.
  * `Inventory`: [`InventoryExchangeItem`](#inventoryexchangeitem) 목록이며, 구매의 일환으로 보상되는 아이템을 설명해 줍니다.

## RedeemAppleAppStorePurchaseAsync##redeemappleappstorepurchaseasync

Apple 앱 스토어에서 영수증을 제출하여 현금 구매를 보상받습니다. 확인하는 절차를 거치고 검증되면 구성에 정의된 대로 플레이어 인벤토리와 재화 잔액에 보상이 적용됩니다.

필수 [`RedeemAppleAppStorePurchaseArgs`](#redeemappleappstorepurchaseargs) 오브젝트를 사용합니다. 이를 사용하여 구매 세부 정보를 제공합니다.

```cs title="C#"
RedeemAppleAppStorePurchaseArgs args = new RedeemAppleAppStorePurchaseArgs("PURCHASE_ID", "RECEIPT_FROM_APP_STORE", 0, "USD");
RedeemAppleAppStorePurchaseResult purchaseResult = await EconomyService.Instance.RedeemAppleAppStorePurchaseAsync(args);
```

### RedeemAppleAppStorePurchaseArgs##redeemappleappstorepurchaseargs

`RedeemAppleAppStorePurchaseAsync` 호출의 인수 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `RealMoneyPurchaseId`: 문자열이며, 생성할 구매의 구성 ID입니다.
* `Receipt`: 문자열이며, Apple 앱 스토어에서 반환된 영수증 데이터입니다.
* `LocalCost`: 정수입니다. 뒷자리 재화 형식의 구매 비용이 정수로 표시됩니다. 예: USD1.99인 경우 199로 표시
* `LocalCurrency`: 문자열이며, 구매에 사용된 재화의 ISO-4217 코드입니다.

### RedeemAppleAppStorePurchaseResult##redeemappleappstorepurchaseresult

이 오브젝트는 `RedeemAppleAppStorePurchaseAsync` 호출로 반환됩니다. 포함되는 필드는 다음과 같습니다.

* `Verification`: 확인 서비스에서 제출된 영수증 확인 세부 정보입니다.

  * `Status`: 영수증 확인의 상태입니다. 다음 중 하나로 구분됩니다.

    * `VALID`: 유효한 구매입니다.
    * `VALID_NOT_REDEEMED`: 유효한 구매이고 이미 확인했지만 아직 보상되지 않았습니다.
    * `INVALID_ALREADY_REDEEMED`: 이미 보상된 구매입니다.
    * `INVALID_VERIFICATION_FAILED`: 영수증 데이터가 유효하지 않아 영수증 확인 서비스에서 반환되었습니다.
    * `INVALID_ANOTHER_PLAYER`: 이미 다른 플레이어가 사용한 영수증이며 확인된 건입니다.
    * `INVALID_CONFIGURATION`: 서비스 구성이 유효하지 않으니, 응답의 세부 정보 세션에서 자세한 내용을 확인해야 합니다.
    * `INVALID_PRODUCT_ID_MISMATCH`: 구매 구성 스토어 제품 ID가 영수증상의 내용과 일치하지 않습니다.

  * `Store`: 영수증 확인 서비스의 세부 정보입니다. 다음 필드 3개로 구성됩니다.

    * `Code`: Apple 앱 스토어 확인 서비스에서 다시 전송된 상태 코드입니다.
    * `Message`: 반환된 상태 코드의 텍스트 설명입니다.
    * `Receipt`: 구매 영수증 데이터입니다.

* `Rewards`: `Rewards` 오브젝트이며, 구매의 대가로 제공되는 보상을 나타냅니다. 다음 필드로 구성됩니다.

  * `Currency`: [`CurrencyExchangeItem`](#currencyexchangeitem) 목록이며, 구매의 일환으로 보상되는 재화를 설명해 줍니다.
  * `Inventory`: [`InventoryExchangeItem`](#inventoryexchangeitem) 목록이며, 구매의 일환으로 보상되는 아이템을 설명해 줍니다.

### EconomyAppleAppStorePurchaseFailedException##economyappleappstorepurchasefailedexception

`RedeemAppleAppStorePurchaseAsync`에서 `EconomyAppleAppStorePurchaseFailedException` 예외 유형이 발생할 수 있습니다. 이는 `EconomyException`에서 상속되며 `Data`라는 추가 필드 하나가 포함됩니다.

`Data` 데이터 필드는 `RedeemAppleAppStorePurchaseResult` 유형입니다([위](#redeemappleappstorepurchaseresult) 참고).

> **Note:**
>
> 이 `Data` 필드는 기본 `Exception` 클래스에 있는 `Data` 필드와는 다릅니다.

## RedeemGooglePlayPurchaseAsync##redeemgoogleplaypurchaseasync

Google Play 스토어에서 영수증을 제출하여 현금 구매를 보상받습니다. 확인하는 절차를 거치고 검증되면 구성에 정의된 대로 플레이어 인벤토리와 재화 잔액에 보상이 적용됩니다.

필수 [`RedeemGooglePlayStorePurchaseArgs`](#redeemgoogleplaystorepurchaseargs) 오브젝트를 사용합니다. 이를 사용하여 구매 세부 정보를 제공합니다.

```cs title="C#"
RedeemGooglePlayStorePurchaseArgs args = new RedeemGooglePlayStorePurchaseArgs("PURCHASE_ID", "PURCHASE_DATA", "PURCHASE_DATA_SIGNATURE", 0, "USD");
RedeemGooglePlayPurchaseResult purchaseResult = await EconomyService.Instance.RedeemGooglePlayPurchaseAsync(args);
```

### RedeemGooglePlayStorePurchaseArgs##redeemgoogleplaystorepurchaseargs

`RedeemGooglePlayPurchaseAsync` 호출의 인수 오브젝트입니다. 포함되는 필드는 다음과 같습니다.

* `RealMoneyPurchaseId`: 문자열이며, 생성할 구매의 구성 ID입니다.
* `PurchaseData`: 문자열이며, 성공적인 앱 결제 구매에서 반환된 JSON 인코딩 문자열입니다.
* `PurchaseDataSignature`: 문자열이며, 성공적인 앱 결제 구매에서 반환된 `PurchaseData`의 서명입니다.
* `LocalCost`: 정수입니다. 뒷자리 재화 형식의 구매 비용이 정수로 표시됩니다. 예: USD1.99인 경우 199로 표시
* `LocalCurrency`: 문자열이며, 구매에 사용된 재화의 ISO-4217 코드입니다.

### RedeemGooglePlayPurchaseResult##redeemgoogleplaypurchaseresult

이 오브젝트는 `RedeemGooglePlayPurchaseAsync` 호출로 반환됩니다. 포함되는 필드는 다음과 같습니다.

* `Verification`: 확인 서비스에서 제출된 영수증 확인 세부 정보입니다.

  * `Status`: 영수증 확인의 상태입니다. 다음 중 하나로 구분됩니다.

    * `VALID`: 유효한 구매입니다.
    * `VALID_NOT_REDEEMED`: 유효한 구매이고 이미 확인했지만 아직 보상되지 않았습니다.
    * `INVALID_ALREADY_REDEEMED`: 이미 보상된 구매입니다.
    * `INVALID_VERIFICATION_FAILED`: 영수증 데이터가 유효하지 않아 영수증 확인 서비스에서 반환되었습니다.
    * `INVALID_ANOTHER_PLAYER`: 이미 다른 플레이어가 사용한 영수증이며 확인된 건입니다.
    * `INVALID_CONFIGURATION`: 서비스 구성이 유효하지 않으니, 응답의 세부 정보 세션에서 자세한 내용을 확인해야 합니다.
    * `INVALID_PRODUCT_ID_MISMATCH`: 구매 구성 스토어 제품 ID가 영수증상의 내용과 일치하지 않습니다.

  * `Store`: 영수증 확인 서비스의 세부 정보입니다. 다음 필드 1개로 구성됩니다.

    * `Receipt`: 구매 영수증 데이터입니다.

* `Rewards`: `Rewards` 오브젝트이며, 구매의 대가로 제공되는 보상을 나타냅니다. 다음 필드로 구성됩니다.

  * `Currency`: [`CurrencyExchangeItem`](#currencyexchangeitem) 목록이며, 구매의 일환으로 보상되는 재화를 설명해 줍니다.
  * `Inventory`: [`InventoryExchangeItem`](#inventoryexchangeitem) 목록이며, 구매의 일환으로 보상되는 아이템을 설명해 줍니다.

### EconomyGooglePlayStorePurchaseFailedException##economygoogleplaystorepurchasefailedexception

`RedeemGooglePlayPurchaseAsync`에서 `EconomyGooglePlayStorePurchaseFailedException` 예외 유형이 발생할 수 있습니다. 이는 `EconomyException`에서 상속되며 `Data`라는 추가 필드 하나가 포함됩니다.

`Data` 데이터 필드는 `RedeemGooglePlayPurchaseResult` 유형입니다([위](#redeemgoogleplaypurchaseresult) 참고).

> **Note:**
>
> 이 `Data` 필드는 기본 `Exception` 클래스에 있는 `Data` 필드와는 다릅니다.

## CurrencyExchangeItem##currencyexchangeitem

이 오브젝트는 구매와 관련된 재화를 나타냅니다. 다음 필드로 구성됩니다.

* `Id`: 재화 ID입니다.
* `Amount`: 구매에 사용된 재화의 금액입니다.

## InventoryExchangeItem##inventoryexchangeitem

이 오브젝트는 구매와 관련된 인벤토리 아이템을 나타냅니다. 다음 필드로 구성됩니다.

* `Id`: 재화 ID입니다.
* `Amount`: 구매에서 사용하거나 보상된 이 인벤토리 아이템의 금액입니다.
* `InstanceIds`: 구매에서 사용되거나 보상된 인스턴스 ID 목록입니다.