Set Up Virtual Currencies #

This guide outlines how to set up hard currencies that players can purchase through the most popular platforms.

Below we will outline how set up a Steam Inventory Item that represents a pack of 500 coins.

Set Up VC with supported platform #

Before you can configure your Connect backend to process orders, you need to set up the virtual currency pack with a supported platforms:

These platforms require verification before docs can be shared. Please contact customer support for more information.

Configure login and account linking #

To process orders, you must first configure the backend to allow login through the platform.

Portal

  • Navigate to the ID Provider page: select the Accounts Tab → ID Provider in the side menu.
  • Select a provider and fill out the form.
    • Each provider requires unique configuration.
  • Click Confirm.
  • Click Deploy.

For Steam:

  • you will need the App ID and a Web API Key.
  • Make sure to select Enable Player Login and Enable Account Linking.

Configure order processing #

To process orders, you need to add a Order Provider.

Portal

  • Navigate to the Order Providers page: select the Economy Tab → Order Providers in side menu.
  • Select platform to configure.
    • Fill out the form. For Steam you will need to enter the App ID and a Web API Key.
    • Each platform requires unique configuration.
  • Click Confirm.
  • Click Deploy.

Define the currency catalog #

Define the currency type. This is a unique ID to represent the currency that will be granted to players.

Portal

  • Navigate to the Currency Definitions page: select the Economy Tab → Currency Definitions in the side menu.
  • Click the Add Currency button.
  • Fill out the form.
    • Use coins as the ID/name.
    • Click Add Currency.

Add SKUs #

SKUs map the platform’s item identifier to a currency grant on fulfillment and a currency revoke if the player initiates a chargeback or refund.

Add a SKU for each currency pack you want to sell.

Portal

  • Navigate to the SKU’s dashboard: select the Economy Tab → SKUs in the side menu.
  • Click the Add SKU button.
    • Fill out the form.
      • SKU ID: 500_coins_pack
        • SKU IDs must be unique.
      • Select the Fulfillment Action from the dropdown.
        • Select Virtual Currency + Add Balance.
        • Select the currency type: coins
        • Enter 500 for the Amount
      • The Revocation Action defaults to the opposite action. Example: Virtual Currency + Revoke Balance.
        • You can select and customize this action if needed.
      • Under SKU Mapping to 3rd Party Platform.
        • Click the Add dropdown.
          • The dropdown will only contain platforms you have configured in the Order Providers dashboard.
          • You will then be prompted to add the platform’s unique identifier.
        • Select Steam.
          • Enter the itemDefId that you set up in Steam Inventory to represent the 500 coins pack.
        • Submit by clicking the Add SKU.

Process orders for player #

Use the OrderApi on the FPragmaPlayer to sync any orders the player has made through a configured platform.

We recommend you call this once after login, and in response to any events or hooks the platform provides.

A player must log in with the platform at least once before orders can be processed for that platform.

Fulfill orders from the client #

This guide is based on an example Unreal project using the Third Person Unreal C++ project template. The example project is named ‘Narwhal’, update references accordingly.

Below is an example of calling the fulfill orders from the client using the SDK.

Source\Narwhal\NarwhalPlayerController.h

// ...
class NARWHAL_API ANarwhalPlayerController : public APlayerController
{
    GENERATED_BODY()

public:
    // ...

    UFUNCTION(Exec)
    void FulfillOrders();  

    // ...
};

Source\Narwhal\NarwhalPlayerController.cpp

void ANarwhalPlayerController::FulfillOrders() {
    Player->OrderApi().FulfillOrders(FPragmaProviderData("STEAM"),
        UPragmaOrderApi::FFulfillOrdersDelegate::CreateLambda(
            [](const TPragmaResult<TArray<FPragmaFulfillment>> &Result) {
                if (Result.IsSuccessful()) {
                    const auto Fulfillments = Result.Payload<>(); 
                    for (const FPragmaFulfillment& Fulfillment : Fulfillments) {
                        UE_LOG(LogTemp, Display, TEXT("Order fulfilled by platform: %s"), *Fulfillment.ProviderId);

                        /*
                         * Fulfillment Status Codes:
                         *   1 = Fulfilled
                         *   2 = Failed
                         *   3 = Revoked
                         *   4 = Revoke Failed
                         */
                        UE_LOG(LogTemp, Display, TEXT("Status: %d"), Fulfillment.Status);
                    }
                } else {
                    UE_LOG(LogTemp, Error, TEXT("FulfillOrders request failed"));
                }
            }));
}
}

Fulfill orders from a trusted backend #

You can also call fulfill orders from a trusted backend by making an HTTP request.

Trusted backend must send a valid partner token. Tokens can be generated in the portal.
Method: POST
Protocol: https
URL: <title>.<shard>.cloud.pragmaengine.com:10100/v1/rpc
Authorization: <valid-partner-token> // partner token from portal
JSON Payload: 
{
    "requestId": 1,
    "type": "FulfillmentRpc.GetFulfillmentsPartnerV1Request",
    "payload": {
        "pragmaPlayerId": "<player-game-uuid-as-string>",
        "providerData": [
            {
                "providerId": "STEAM"
            }
         ]
    }
}

Example cURL request:

curl --location 'https://GAME-TITLE.STUDIO-TITLE.cloud.pragmaengine.com:10100/v1/rpc' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "requestId": 1,
    "type": "FulfillmentRpc.GetFulfillmentsPartnerV1Request",
    "payload": {
        "pragmaPlayerId": "00000000-0000-0000-0000-000000000001",
        "providerData": [
            {
                "providerId": "STEAM"
            }
         ]
    }
}'

Example Response:

A successful response will include a fulfillment object for each order processed. Check the status field to determine success.


{
    "requestId":10,
    "type":"FulfillmentRpc.FulfillOrdersV1Response",
    "payload":{
        "fulfillments":[
            {
                "fulfillmentId":"<uuid-for-fulfillment>",
                "orderId":"<uuid-for-order>",
                "pragmaPlayerId":"00000000-0000-0000-0000-000000000001",
                "skuId":"500_coin_pack", // from the SKU mapping
                "quantity":1.0,
                "providerId":"STEAM",
                "status":"FULFILLMENT_STATUS_FULFILLED",
                "createdTimestampMillis":"1755296097555",
                "lastUpdatedTimestampMillis":"1755296097555",
                "contentVersion":"2"
            }
        ]
    }
}

View order history #

You can view all internal tracking of orders for a player in the Portal. If a player reports an issue with a purchase, check here first.

Portal

  • From the Player Support page, click the relevant player name to view account details.
  • Select Orders from the side menu.
    • The table shows all orders processed for this player.
    • The four possible order statuses are: FULFILLED, FULFILLMENT_FAILED, REVOKED, and REVOKED_FAILED.

Recap #

This guide covered setting up hard currency packs, processing orders, and viewing player order history.


Overview
Overview