Orders and Fulfillment Overview #

Flow #

Below is an example flow with Steam as the chosen third party provider.

You can call FulfillOrders any time you want to check for new orders. For example, you may want to call this endpoint during player login or directly after a player purchases an item through the in game store so that players will have an updated view of their purchased items.

You’ll need to configure and implement your own operation for granting items. See Player Data for more details on how to setup Player Data operations.

1. Player purchases a Steam item with itemDefId 475 from Steam.
2. From the game client the Player calls FulfillOrdersV1 with the provider ID STEAM.
3. The Fulfillment service calls SyncOrders on the Orders service to retrieve new orders to fulfill.
4. The Orders service requests any new orders from Steam.
5. Steam responds that the player has a Steam item with itemDefId 475. This Steam item is mapped to the SKU “SmallGoldBundle” through OrderMappingsSpecs.json content file. Only items defined in the mapping spec will be stored as orders.

[
    {
        "skuId": "SmallGoldBundle",
        "sources": [
            {
                "provider": "STEAM",
                "steamSource": {
                    "inventory": {
                        "itemDefId": "475" 
                    }
                }
            }
        ]
    }
]

6. A Pragma Order is created for SKU ID “SmallGoldBundle” and stored as an order record in the database.
7. Any added or updated order records are returned to the Fulfillment service.
8. “SmallGoldBundle” SKU ID is mapped to Player Data operations through the FulfillmentMappingSpecs.json content file.

[
  {
    "skuId": "SmallGoldBundle",
    "operations": {
      "fulfillmentOperation": {
        "grantCoins": {
          "id": "gold",
          "amount": "60"
        }
      }
    }
  }
]

9. The Fulfillment service calls registered Player Data operations based on the quantity of the order. This is typically to add or remove items.

You’ll need to create your own Player Data operations for this to work. In the example, the grantCoins is a custom Player Data operation.

10. The Fulfillment service creates a Pragma fulfillment record to keep track of whether the transaction has been fulfilled, revoked, or failed.
11. The Fulfillment service returns a list to the player with the items that have been fulfilled or revoked.

Get started #

To use Orders and Fulfillments to grant players their items you’ll need to do the following:

1. Set up a third-party provider.
2. Set up your social backend partner config.
3. Configure an Order Provider Plugin.
4. Configure an OrderMappingSpecs.json content file.
   • Maps each order provider’s item to a Pragma SKU ID.
5. Define Player Data operations to call on fulfillment.
6. Configure a FulfillmentMappingSpecs.json content file.
   • Associates a Pragma SKU ID with Player Data operations to fulfill or revoke.

1. Set up a third party provider #

Before integrating with Pragma Engine, you’ll need to set up an account with a third party provider. For more information on each third-party provider’s system, refer to their respective documentation:

The Orders service allows for integration with multiple third party providers.

2. Ensure your social backend partner is configured #

To enable your Pragma game shard to communicate with your Pragma social shard, we’ll need to set up the backend communication channel. To set up this configuration, add a SocialBackendPartnerClientConfig with a bearerToken that has the encrypted Social Partner token.

game:
  serviceConfigs:
    SocialBackendPartnerClientConfig:
      bearerToken: <encrypted social partner token>

Check out the Generate Partner tokens guide if you need help generating Partner tokens.

3. Configure an Order Provider Plugin #

Under the social config, add your Order Provider Plugin.

social: 
  pluginConfigs:
    ThirdPartyNodeService.orderProviderPlugins:
      plugins:
        Steam:
          class: "pragma.order.SteamOrderProviderPlugin"
          config:
            appId: "{steamAppId}"
            steamWebAPIKey: "{steamWebApiKey}"

social:
  pluginConfigs:
    ThirdPartyNodeService.orderProviderPlugins:
      plugins:
        Steam:
          class: "pragma.order.SteamOrderProviderPlugin"
          config:
            appId: "{steamAppId}"
            steamWebAPIKey: "{steamWebApiKey}"
        Twitch:
          class: "pragma.order.TwitchOrderProviderPlugin"
          config:
            clientId: "{twitchClientId}"
            clientSecret: "{twitchClientSecret}"
            gameId: "{twitchGameId}"
        Epic:
          class: "pragma.order.EpicOrderProviderPlugin"
          config:
            clientId: "{epicClientId}"
            clientSecret: "{epicClientSecret}"
            sandboxId: "{epicSandboxId}" 
            deploymentId: "{epicDeploymentId}"
            clawbackPollingEnabled: true # enables refund processing

You can implement your own custom Order Provider Plugin. See the Custom Order Provider Plugin page for details.

4. Configure an Order Mappings Specs content file #

Below is an example OrderMappingsSpecs.json with Steam, Epic, and Twitch sources defined for the one item:

[
    {
        "skuId": "SmallGoldBundle",
        "sources": [
            {
                "provider": "STEAM",
                "steamSource": {
                    "inventory": {
                        "itemDefId": "475"    
                    }
                }
            },
            {
                "provider" : "EPIC",
                "epicSource" : {
                    "entitlement" : {
                      "audienceItemId" : "231f97b3e1a44fb7b496e1832ec6b3d6"
                    }
                }
            },
            { 
                "provider": "TWITCH",
                "twitchSource": {
                    "rewardId": "twitch_item_drop"
                }
            }
        ]
    }
]

SKU ID must be unique for each order entry.

See the src/main/proto/pragma/order/orderContent.proto file for more information about what data is required for each provider.

5. Define Player Data operations to call on fulfillment #

The fulFillmentOperation defined in the JSON file needs to be configured to specify which Player Data operation should be called to fulfill an order. The example above uses the grantCoins operation to fulfill coins. You’ll need to create your own Player Data operation(s) to be able to fulfill orders.

See the Player Data Overview page for more information.

6. Configure a Fulfillment Mapping Specs content file #

Below is an example FulfillmentMappingSpecs.json:

[
  {
    "skuId": "SmallGoldBundle",
    "operations": {
      "fulfillmentOperation": {
        "grantCoins": { // custom Player Data operation
          "id": "gold",
          "amount": "60"
        }
      }
    }
  },
  {
    "skuId": "SmallOrbBundle",
    "operations": {
      "fulfillmentOperation": {
        "updateCurrency": { // custom Player Data operation
          "id": "elemental_orbs",
          "amount": "60"
        }
      },
      "revocationOperation": {
        "updateCurrency": {
          "id": "elemental_orbs",
          "amount": "-60"
        }
      }
    }
  }
]

Initiate order sync and fulfillment from the SDK #

Through the Pragma SDK you can initiate a sync call to a provider to check for new orders then fulfill and grant items to players.

Pragma stores the date of the last time a player ran FulfillOrders successfully. We will only fulfill newly synced orders since the last successful run date.

Unreal SDK #

Player->OrderApi().FulfillOrders(
	FPragmaProviderData
	{
		EnumToString<EPragma_Account_IdProvider>(EPragma_Account_IdProvider::STEAM)
	},
	UPragmaOrderApi::FFulfillOrdersDelegate::CreateLambda(
		[](TPragmaResult<TArray<FPragmaFulfillment>> Result)
		{
			//Handle Result
		}
	)
);

Player->OrderApi().FulfillOrders(
	FPragmaProviderData
	{
		EnumToString<EPragma_Account_IdProvider>(EPragma_Account_IdProvider::EPIC)
	},
	UPragmaOrderApi::FFulfillOrdersDelegate::CreateLambda(
		[](TPragmaResult<TArray<FPragmaFulfillment>> Result)
		{
			//Handle Result
		}
	)
);

Player->OrderApi().FulfillOrders(
	FPragmaProviderData
	{
		EnumToString<EPragma_Account_IdProvider>(EPragma_Account_IdProvider::TWITCH)
	},
	UPragmaOrderApi::FFulfillOrdersDelegate::CreateLambda(
		[](TPragmaResult<TArray<FPragmaFulfillment>> Result)
		{
			//Handle Result
		}
	)
);

Unity SDK #

player.OrderApi.FulfillOrders(
    new ProviderData{ ProviderId = IdProvider.Steam.GetOriginalName() },
    (result) =>
    {
        //Handle result;
    }
);

player.OrderApi.FulfillOrders(
    new ProviderData{ ProviderId = IdProvider.Epic.GetOriginalName() },
    (result) =>
    {
        //Handle result;
    }
);

player.OrderApi.FulfillOrders(
    new ProviderData{ ProviderId = IdProvider.Twitch.GetOriginalName() },
    (result) =>
    {
        //Handle result;
    }
);

Chargebacks & Refunds #

Pragma handles any incoming chargeback and refund requests using the revocationOperation you defined.

View fulfillment history in Game Operator Portal #

To view a player’s fulfillment history:

1. From the Accounts page, click on the relevant player name to view individual account information.
2. See the Orders tab for details.
   • The four possible order statuses include: FULFILLED, FULFILLMENT_FAILED, REVOKED, and REVOKED_FAILED.