Purchases
The methods in the Purchases
namespace allow you to make purchases for the currently signed in user.
All the methods in this namespace can throw an EconomyException.
MakeVirtualPurchaseAsync
Makes a virtual purchase specified by ID.
This method optionally takes a MakeVirtualPurchaseOptions
object. This can be used to specify the PlayersInventoryItems
IDs of the items in the players inventory that should be used towards the cost(s) of the purchase. If these are not supplied, the items used towards the cost(s) are chosen automatically.
Returns a MakeVirtualPurchaseResult
.
Example:
C#
string purchaseID = "BUY_A_SWORD";
MakeVirtualPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.MakeVirtualPurchaseAsync(purchaseID);
Alternative Example using PlayersInventoryItem
IDs:
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
The options object for a MakeVirtualPurchaseAsync
call. It has the following field:
PlayersInventoryItemIds
: A list of strings. Defaults tonull
. ThePlayersInventoryItem
IDs of the items in the players inventory that you want to use towards the cost(s) of the purchase.
MakeVirtualPurchaseResult
This object is returned by a MakeVirtualPurchaseAsync
call. It contains the following fields:
Costs
: ACosts
object representing the costs that were spent in this purchase. This in turn has two fields:Currency
: A list ofCurrencyExchangeItem
describing the currencies used to make this purchase.Inventory
: A list ofInventoryExchangeItem
describing the items used as a cost in order to make this purchase.
Rewards
: ARewards
object representing the rewards given in exchange for this purchase. This also has two fields as above:Currency
: A list ofCurrencyExchangeItem
describing the currencies rewarded as part of this purchase.Inventory
: A list ofInventoryExchangeItem
describing the items rewarded as part of this purchase.
RedeemAppleAppStorePurchaseAsync
Redeems a real money purchase by submitting a receipt from the Apple App Store. This is validated and if valid, the rewards as defined in the configuration are applied to the player’s inventory and currency balances.
Takes a required RedeemAppleAppStorePurchaseArgs
object. This is used to provide the purchase details.
C#
RedeemAppleAppStorePurchaseArgs args = new RedeemAppleAppStorePurchaseArgs("PURCHASE_ID", "RECEIPT_FROM_APP_STORE", 0, "USD");
RedeemAppleAppStorePurchaseResult purchaseResult = await EconomyService.Instance.Purchases.RedeemAppleAppStorePurchaseAsync(args);
RedeemAppleAppStorePurchaseArgs
The arguments object for a RedeemAppleAppStorePurchaseAsync
call. It has the following fields:
RealMoneyPurchaseId
: A string. The configuration ID of the purchase to make.Receipt
: A string. The receipt data as returned from the Apple App Store.LocalCost
: An int. The cost of the purchase as an integer in the minor currency format, for example, $1.99 USD would be 199.LocalCurrency
: A string. ISO-4217 code of the currency used in the purchase.
RedeemAppleAppStorePurchaseResult
This object is returned by a RedeemAppleAppStorePurchaseAsync
call. It contains the following fields:
Verification
: The receipt verification details from the validation service.Status
: Status of the receipt verification. This will be one of:VALID
: The purchase was valid.VALID_NOT_REDEEMED
: The purchase was valid but seen before, but had not yet been redeemed.INVALID_ALREADY_REDEEMED
: The purchase has already been redeemed.INVALID_VERIFICATION_FAILED
: The receipt verification service returned that the receipt data was not valid.INVALID_ANOTHER_PLAYER
: The receipt has previously been used by a different player and validated.INVALID_CONFIGURATION
: The service configuration is invalid, further information in the details section of the response.INVALID_PRODUCT_ID_MISMATCH
: The purchase configuration store product identifier does not match the one in the receipt.
Store
: Details from the receipt validation service. This has three fields:Code
: The status code sent back from the Apple App Store verification service.Message
: A textual description of the returned status code.Receipt
: The purchase receipt data.
Rewards
: ARewards
object representing the rewards given in exchange for this purchase. This has the following fields:Currency
: A list ofCurrencyExchangeItem
describing the currencies rewarded as part of this purchase.Inventory
: A list ofInventoryExchangeItem
describing the items rewarded as part of this purchase.
INVALID_VERIFICATION_FAILED
If you get an INVALID_VERIFICATION_FAILED
error with the store message The receipt could not be authenticated.
and with error code 21003
, it might be because your receipt contains a renewable subscription, which is not supported for validation by the Economy service.
EconomyAppleAppStorePurchaseFailedException
RedeemAppleAppStorePurchaseAsync
may throw an exception of type EconomyAppleAppStorePurchaseFailedException
. This inherits from EconomyException
and contains one additional field called Data
.
The Data
field is of type RedeemAppleAppStorePurchaseResult
(see above).
This Data
field is different from the Data
field in the base Exception
class.
RedeemGooglePlayPurchaseAsync
Redeems a real money purchase by submitting a receipt from the Google Play Store. This is validated and if valid, the rewards as defined in the configuration are applied to the player’s inventory and currency balances.
Takes a required RedeemGooglePlayStorePurchaseArgs
object. This is used to provide the purchase details.
C#
RedeemGooglePlayStorePurchaseArgs args = new RedeemGooglePlayStorePurchaseArgs("PURCHASE_ID", "PURCHASE_DATA", "PURCHASE_DATA_SIGNATURE", 0, "USD");
RedeemGooglePlayPurchaseResult purchaseResult = await EconomyService.Instance.Purchases.RedeemGooglePlayPurchaseAsync(args);
RedeemGooglePlayStorePurchaseArgs
The arguments object for a RedeemGooglePlayPurchaseAsync
call. It has the following fields:
RealMoneyPurchaseId
: A string. The configuration ID of the purchase to make.PurchaseData
: A string. A JSON encoded string returned from a successful in app billing purchase.PurchaseDataSignature
: A string. A signature of thePurchaseData
returned from a successful in app billing purchase.LocalCost
: An int. The cost of the purchase as an integer in the minor currency format, for example, $1.99 USD would be 199.LocalCurrency
: A string. ISO-4217 code of the currency used in the purchase.
RedeemGooglePlayPurchaseResult
This object is returned by a RedeemGooglePlayPurchaseAsync
call. It contains the following fields:
Verification
: The receipt verification details from the validation service.Status
: Status of the receipt verification. This will be one of:VALID
: The purchase was valid.VALID_NOT_REDEEMED
: The purchase was valid but seen before, but had not yet been redeemed.INVALID_ALREADY_REDEEMED
: The purchase has already been redeemed.INVALID_VERIFICATION_FAILED
: The receipt verification service returned that the receipt data was not valid.INVALID_ANOTHER_PLAYER
: The receipt has previously been used by a different player and validated.INVALID_CONFIGURATION
: The service configuration is invalid, further information in the details section of the response.INVALID_PRODUCT_ID_MISMATCH
: The purchase configuration store product identifier does not match the one in the receipt.
Store
: Details from the receipt validation service. This has one field:Receipt
: The purchase receipt data.
Rewards
: ARewards
object representing the rewards given in exchange for this purchase. This has the following fields:Currency
: A list ofCurrencyExchangeItem
describing the currencies rewarded as part of this purchase.Inventory
: A list ofInventoryExchangeItem
describing the items rewarded as part of this purchase.
EconomyGooglePlayStorePurchaseFailedException
RedeemGooglePlayPurchaseAsync
may throw an exception of type EconomyGooglePlayStorePurchaseFailedException
. This inherits from EconomyException
and contains one additional field called Data
.
The Data
field is of type RedeemGooglePlayPurchaseResult
(see above).
This Data
field is different from the Data
field in the base Exception
class.
CurrencyExchangeItem
This object represents a currency that was part of a purchase. It has these fields:
Id
: The ID of the currency.Amount
: The amount of this currency used in the purchase.
InventoryExchangeItem
This object represents an inventory item that was part of a purchase. It has these fields:
Id
: The ID of the currency.Amount
: The amount of this inventory item used/rewarded in the purchase.InstanceIds
: A list of instance IDs that were used/rewarded in the purchase.