Implement Orders and Fulfillment #

This guide covers setting up the Orders and Fulfillment services to grant players their items.

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.
   • This 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.
   • This 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 Create a Custom Order Provider Plugin guide 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"
        }
      }
    }
  }
]

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.