Ecom Interface

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 callbacks to trigger when requests are completed.

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:

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:

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.

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:

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:

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

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:

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:

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:

Ecom Interface Glossary

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

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.