Ecom Interface

Interface to handle purchases and verification of ownership

The Ecom Interface gives developers using Epic Online Services (EOS) the ability to support in-game purchases through the Epic Games Store (EGS). With this interface, you can manage products ranging from full games and downloadable content (DLC) to virtual goods and in-game currency. This includes making offers, completing purchase transactions, verifying ownership, and redeeming purchased items.

To access the Ecom Interface, acquire an EOS_HEcom handle through the Platform Interface function, EOS_Platform_GetEcomInterface. All Ecom Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking in order for appropriate callbacks to trigger when requests are completed.

To use the Ecom Interface, your product must have Epic Account Services (EAS) active, and must obtain user consent to access Basic Profile data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and user consent, you will still be able to initialize the EOS SDK and the Ecom Interface, but all Ecom Interface function calls to the back-end service will fail.

Operating an In-Game Store

An in-game store under EOS operates by carrying out two functions: presenting Catalog Offers (sometimes called "Offers") from the store to the user for purchase, and enabling the user to make purchases. The EOS SDK provides functionality to retrieve lists of offers from the store's catalog for display in whatever way the game developer desires. Offer data includes one or more items that the user will gain, as well as key images and release details that you can use to present information about the offer to the user.

Once the user chooses to make a purchase, the checkout process pushes the data to the EGS Overlay, which finalizes the purchasing process. EOS will then notify the game of the result of the transaction, providing a transaction handle so that the game can carry out fulfillment in the event that the purchase was completed successfully.

Catalog Offer Data

Catalog Offers (type EOS_Ecom_CatalogOffer) contain localized pricing information and descriptive text, based on the user browsing the store. Price localization includes applying discounts and converting to the local currency. A localized price will include a currency code, such as "USD" (to represent US dollars), and is represented in the smallest possible unit of that currency. For example, an Offer that costs 2.99 US dollars would correspond to the value 299.

Presenting the Store's Catalog

You can retrieve the list of Catalog Offers defined in the Developer Portal by calling the EOS_Ecom_QueryOffers function. This function takes an EOS_Ecom_QueryOffersOptions data structure and will call your delegate, of type EOS_Ecom_QueryOffersCallbackInfo, upon completion. Initialize your EOS_Ecom_QueryOffersOptions structure as follows:

Property

Value

ApiVersion

EOS_ECOM_QUERYOFFERS_API_LATEST

LocalUserId

The EOS_EpicAccountId of the local user who is requesting the query

OverrideCatalogNamespace

Optional product namespace, if not the one specified during initialization

If the ResultCode in the EOS_Ecom_QueryOffersCallbackInfo that the delegate receives indicates success, the Offer data you requested is available in a temporary cache. Use EOS_Ecom_GetOfferCount to determine the number of Offers stored in the cache, and EOS_Ecom_CopyOfferByIndex to get a copy of an individual Offer (of type EOS_Ecom_CatalogOffer) from it. Each Item within the Offer contains data about images and release details associated with that Item, which you can pull out separately. When you no longer need your copy of an Offer, use EOS_Ecom_CatalogOffer_Release to release it.

Displaying Individual Item Data

After retrieving an Offer from the cache, you can call EOS_Ecom_GetOfferItemCount to determine how many Items that Offer includes, and then use EOS_Ecom_CopyOfferItemByIndex to retrieve a copy of an individual EOS_Ecom_CatalogItem. This structure contains additional localized text as well as the ID of the Entitlement that it will provide upon purchase. To release the memory allocated to your copy of the data, call EOS_Ecom_CatalogItem_Release.

Images associated with Items are also available in the cache; you can call EOS_Ecom_GetItemImageInfoCount to determine how many images are associated with a given Item, and then use EOS_Ecom_CopyItemImageInfoByIndex to obtain an EOS_Ecom_KeyImageInfo for the image's URL, dimensions, and intended usage. When you no longer need your copy of this data, use EOS_Ecom_KeyImageInfo_Release to free the memory it used.

To retrieve release details for an Item from the cache, first use EOS_Ecom_GetItemReleaseCount to discover the number of data entries present. You can then use EOS_Ecom_CopyItemReleaseByIndex to get an individual piece of data (of type EOS_Ecom_CatalogRelease). Call EOS_Ecom_CatalogRelease_Release to release this data when you no longer need it.

Buying from the Store

When a user buys something from the store, that user is accepting a Catalog Offer. Once the purchase is complete, the user will own the Item (or Items) contained within the Offer, each of which adds one or more Entitlements to the buyer's user account.

There are three actions involved in buying from the store: Making the purchase, verifying ownership, and (optionally) redeeming Entitlements.

When a user decides to make a purchase, call EOS_Ecom_Checkout with an EOS_Ecom_CheckoutOptions structure. Initialize the structure as follows:

Property

Value

ApiVersion

EOS_ECOM_CHECKOUT_API_LATEST

LocalUserId

The EOS_EpicAccountId of the local user who is making the purchase

OverrideCatalogNamespace

If not provided, the current SandboxId will be supplied as the catalog namespace.

EntryCount

The number of EOS_EcomCheckoutEntry elements being supplied to this structure in the Entries parameter.

Entries

An array of EOS_Ecom_CheckoutEntry elements, which contain the EOS_Ecom_CatalogOfferId data for each Offer the user wishes to purchase, and the same ApiVersion as this structure

After making this call, EOS will use this information to generate a purchase token. EOS will then use this purchase token to open its own overlay, enabling the user to review the purchase, select payment options, and confirm or cancel the transaction. When the overlay closes, whether by succeeding, failing, or being canceled by the user, your callback (of type EOS_Ecom_OnCheckoutCallback) will run with an EOS_Ecom_CheckoutCallbackInfo parameter detailing the transaction. Within the callback information, the TransactionId will be non-null if the transaction succeeded, and null if it failed or was canceled.

If any additional calls to EOS_Ecom_Checkout are made before the first returns via the callback then it will give an EOS_AlreadyPending error.

Accessing Completed Purchase Data

If you have a valid transaction ID following a successful user purchase, you can pass it to the EOS_Ecom_CopyTransactionById function to receive an EOS_Ecom_HTransaction. EOS_Ecom_Transaction_GetEntitlementsCount returns the number of Entitlements associated with the transaction, and EOS_Ecom_Transaction_CopyEntitlementByIndex will retrieve an individual Entitlement. Call EOS_Ecom_Entitlement_Release to release this data when you no longer need it.

Entitlements associated with transaction IDs contain the same data as those obtained through the EOS_Ecom_QueryEntitlement function, but are subject to a different caching policy. Because of this difference, Entitlements that you acquire using a transaction ID following a purchase will remain in a transaction-specific cache until you explicitly call EOS_Ecom_Transaction_Release.

Fulfilling Purchases

After making a purchase, the user's account gains an Entitlement, but the user may not see the effect of their purchase in the game yet. In some cases, fulfilling a purchase can be as simple as checking that the user owns a specific Entitlement and applying some game logic to the result. In these cases, verifying ownership through the EOS SDK is sufficient. In other cases, such as purchases involving consumable items or game currency, you may also need to fulfill the order in-game or with a third-party backend service by redeeming the Entitlement.

Enumerating Entitlements

To retrieve a user account's Entitlements, call the EOS_Ecom_QueryEntitlements function with an EOS_Ecom_QueryEntitlementsOptions structure initialized as follows:

Property

Value

ApiVersion

EOS_ECOM_QUERYENTITLEMENTS_API_LATEST

LocalUserId

The EOS_EpicAccountId of the local user whose Entitlements you want to retrieve

EntitlementNames

An array of Entitlement Names that you want to check.

EntitlementNameCount

The number of Entitlement Names included in the EntitlementNames property. Accepts up to a maximum of EOS_ECOM_QUERYENTITLEMENTS_MAX_ENTITLEMENT_IDS. If 0 is provided, will request all Entitlements associated with the user account.

bIncludeRedeemed

If true, Entitlements that have been redeemed will be included in the results.

When the operation completes, EOS will cache the resulting information and run your callback function (of type EOS_Ecom_OnQueryEntitlementsCallback) with an EOS_Ecom_QueryEntitlementsCallbackInfo parameter. If the ResultCode of this parameter is EOS_Success, the cache contains the data you requested. You can call EOS_Ecom_GetEntitlementsCount to determine the number of Entitlements in the cache, and EOS_Ecom_CopyEntitlementByIndex to retrieve a copy of an individual element (of type EOS_Ecom_Entitlement), including the the Catalog Item ID that provided the Entitlement, the unique ID for that Entitlement, and other related data.

Redeeming an Entitlement

After fulfilling an Entitlement, or managing its fulfillment through a third-party service, call the EOS_Ecom_RedeemEntitlements function with an EOS_Ecom_RedeemEntitlementsOptions structure. Initialize the structure as follows:

Property

Value

ApiVersion

EOS_ECOM_REDEEMENTITLEMENTS_API_LATEST

LocalUserId

The ID of the user account that is redeeming Entitlements

EntitlementIdCount

The number of elements in EntitlementIds

EntitlementIds

The Entitlements (of type EOS_Ecom_EntitlementId) to redeem

Upon completion, your callback of type EOS_Ecom_OnRedeemEntitlementsCallback will receive an EOS_Ecom_RedeemEntitlementsCallbackInfo structure.

After redeeming an Entitlement, it will no longer show up in the results from EOS_Ecom_QueryEntitlements calls, unless the EOS_Ecom_QueryEntitlementsOptions parameter has its bIncludeRedeemed set to true.

Verifying Ownership

The Ecom Interface provides two methods for ownership verification, known as the "online" and "offline" methods. The online method integrates directly with the Epic Entitlement Service, while the offline method provides a signed token that the user can verify, or can pass to a third-party service. The online method is useful for trusted game servers or less secure checks on client systems for simple validation. The offline method provides a token that includes information about the game client, user, and Entitlement as well as a signature that the game client or an external service can verify. If integrating with a third-party service that performs ownership verification, the offline check is recommended because it avoids granting the outside service access to the user's data.

If you prefer to access ownership information for your titles and services via RESTful endpoints, see Ownership Verification Using REST.

Online Ownership Verification

To determine whether or not a user owns a specific Catalog Item, call EOS_Ecom_QueryOwnership and pass in an EOS_Ecom_QueryOwnershipOptions structure. This will retrieve ownership information from the server and pass it to the EOS_Ecom_OnQueryOwnershipCallback callback function that you provide. The callback function will also receive a void pointer that you specify, which can contain any information your product requires to understand the context of the request. To begin, fill out the EOS_Ecom_QueryOwnershipOptions structure with the following information:

Property

Value

ApiVersion

EOS_ECOM_QUERYOWNERSHIP_API_LATEST

LocalUserId

The EOS_EpicAccountId of the local user whose ownership to query; needed for localization of Catalog Item (Item) description text and pricing information

CatalogItemIds

List of Catalog Item IDs to check for ownership

CatalogItemIdCount

Number of elements in CatalogItemIds

CatalogNamespace

Optional product namespace, if not the one specified during initialization

Upon completion, EOS will invoke your callback function with the data you requested (and your void pointer) stored in an EOS_Ecom_OnQueryOwnershipCallback structure. This structure contains an array of EOS_Ecom_EntitlementOwnership members, each of which describes one of the items you queried, and indicates whether the user owns it or not. Items that the server doesn't recognize will come back as not owned.

Offline Ownership Verification

To check ownership and cache the results locally for a few minutes, use EOS_Ecom_QueryOwnershipToken. This function takes an EOS_Ecom_QueryOwnershipTokenOptions structure, initialized as follows:

Property

Value

ApiVersion

EOS_ECOM_QUERYOWNERSHIPTOKEN_API_LATEST

LocalUserId

The FUniqueNetId of the user whose Entitlements you wish to query

CatalogItemIds

An array of up to 32 (EOS_ECOM_QUERYOWNERSHIPTOKEN_MAX_CATALOGITEM_IDS) Catalog Items to check for Entitlement, of type EOS_Ecom_CatalogItemId

CatalogItemIdCount

The number of Catalog Items in CatalogItemIds

CatalogNamespace

Optional product namespace, if not the one specified during initialization

When the operation completes, your callback function (of type EOS_Ecom_OnQueryOwnershipTokenCallback) will receive an EOS_Ecom_QueryOwnershipTokenCallbackInfo structure that includes a JSON Web Token (JWT) with a five-minute expiration time. You can verify the JWT with a public key, and unpack it to extract the Key ID. You may also send it along to a third-party service, which can then verify that the Entitlement information came from EGS. The public key, retrieved by an additional web call or shared with your organization, will be in the form of a JSON Web Key (JWK) that can be used to verify the signature in the JWT. To make an HTTP request, send a GET to https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}. A sample request follows:

GET
/ecommerceintegration/api/public/publickeys/pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com
{
    "kty": "RSA",
    "e": "AQAB",
    "kid": "pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g",
"n": "gcStqtD8XD9c9ifNuxXT9Xd_EEZLLCw34yxINRQPt0MxEWkoOFsuisRWGktSFtGrnUuQnp8GQY0k4Pyl_yDItWAcRtO7JUjrhQnxx3xXp_0P8xJMH1ny-RcxHF3bEJWhDzNW5PBpBjQTQZis-83499z-4OlNA7oUnDKEJkqNfzh4mMDFluPxvW_Hwpaw71nhzJI7-N-BdsPsLdqUANajLsFKq9fr06Lek_tm-6-RUxNPE3yS0x0UIsGyapA4Apcczz0xTzRDfwOkq_TyKGZiZc7vtgjkWnqdsCyXZC7dzKJvg0ggO3mKXhqZNNC_2pz24o1X_xCbG8rXtuvX8-ux-Q"
}

Ownership Verification Token Details

The Ownership Verification Token is a JWT signed using RS512 (RSA PKCS#1 signature with SHA-512, RSA key size 2048), which expires five minutes after it is created. The token contains the following claims:

Claim

Description

jti

A unique identifier for this token

sub

The account ID for the account that was used to request the token

clid

The client ID for the client that was used to request the token

ent

An array of Entitlements that were verified for this token; if this value is empty, the account is not entitled to any of the requested Entitlements for a given sandboxId

iat

A Unix timestamp representing the time the token was issued

exp

A Unix timestamp representing the time the token will expire

OwnershipVerificationToken.png

Ecom Interface Glossary

This section contains terms and definitions commonly used within the Ecom Interface.

Term

Definition

Catalog Offers

A Catalog Offer is a pairing of one or more Catalog Items and an associated price (which can be 0). When an offer is purchased, an entitlement is granted for each of the items.

Catalog Item

A Catalog Item can be an entire game, some sort of downloadable content, or virtual goods like in-game currency or weapon skins. An item is used to define how an entitlements are granted to accounts. They will also contain an entitlement name which can be used to logically group entitlements.

Entitlement

An Entitlement is anything a user owns, and can mean different things in different Products. An Entitlement can be dynamic, granting access to one or more Catalog Items, but it could also be dynamic in nature, supporting the addition or removal of Item access over the lifetime of a Product.

Consumable Entitlement

Consumable Entitlements have limited persistence, decreasing a "use count" each time the Item is used in game. This is commonly used for things like in-game currency, XP boosts, and other Items that can be used up and replenished with additional purchases. In some cases, an external service fulfills the Entitlement. Once that external service has received the information about the Entitlement, it is redeemed and its use count is decremented to 0, effectively removing it from the user account. The external service accepts responsibility for handling the in-game effects of the Item past that point.

Durable Entitlement

Some purchases persist, like certain forms of downloadable content, or even entire games. If a third party service desires, it can mark the Entitlement as "inactive" once responsibility has been transferred.

Fulfillment

Once an Entitlement is part of a user account, the Entitlement still needs to be fulfilled. It can be implicit (checked by SDK APIs), or a third-party service can accept responsibility for the fulfillment through backend API calls.

The following table contains the different ID types used within the ECom Interface and information about where each comes from and what they each describe.

ID Type

Description

Catalog Offer ID

A Catalog Offer ID is the unique identifier for an Offer in the store. These IDs are unique within a Product. The checkout process requires a Catalog Offer ID.

Catalog Item ID

Catalog Item IDs are unique within a Product and identify a single Catalog Item. You need this ID in order to check whether or not a specific user owns the corresponding Catalog Item.

Entitlement Name

Each Catalog Item can have an Entitlement Name associated with it. These Entitlement Names can be used for grouping. The Ecom Interface allows querying for entitlements based on the Entitlement Name associated with the Catalog Item in the Catalog Offer that granted it.

Entitlement ID

Fulfilled Catalog Offers and their Catalog Items manifest on the user account as a particular Entitlement stored with that user. Each Entitlement will have its own unique identifier. This ID is used by the ECom Interface when redeeming Entitlements.