Register Login

Step-by-step setup

Connect your game in Studio, test a purchase, then go live.

First check Before you start: your game is published on Roblox and sells at least one developer product.

Step 1. Download and install the SDK

Download R3FTO.rbxm from the latest release on GitHub. The current version is 0.4.0.

  1. Open your game in Roblox Studio.
  2. Drag R3FTO.rbxm onto ServerScriptService in the Explorer, or right-click ServerScriptService and choose Insert from File.
  3. Check that the Explorer shows this:
    Studio layout · Explorer
    ServerScriptService
      R3FTO              (ModuleScript)
        Client           (ModuleScript)
        Engine           (ModuleScript)
        RobloxAdapters   (ModuleScript)
        Version          (ModuleScript)
        Wire             (ModuleScript)
        KeyPanelGui      (Folder)
          Look           (ModuleScript)
          Panel          (LocalScript)
    
  4. Keep R3FTO under ServerScriptService. Code there never reaches players' devices. In ReplicatedStorage or Workspace it would. The optional key panel is the one exception: when your server opens it, R3FTO copies only the panel to that player's device.

Other ways to install

Wally. Add this to your wally.toml, run wally install, and map ServerPackages into ServerScriptService in your Rojo project. In your scripts, use the line below wherever a script loads R3FTO with require.

wally.toml
[server-dependencies]
R3FTO = "mrcha0s/r3fto-roblox-sdk@0.4.0"
Luau · the SDK from ServerPackages
local R3FTO = require(game:GetService("ServerScriptService").ServerPackages.R3FTO)

Git. Add the SDK repository as a submodule at a release tag, then point your Rojo project at vendor/r3fto-roblox-sdk/src/R3FTO inside ServerScriptService.

Bash
git submodule add https://github.com/R3Fto/roblox-sdk.git vendor/r3fto-roblox-sdk
git -C vendor/r3fto-roblox-sdk checkout v0.4.0

The SDK's source code is on GitHub.

Step 2. Find your universe ID

  1. Click the Command Bar, the thin line at the bottom of Studio. If you do not see it, open it from the View tab.
  2. Type this line and press Enter:
    Command Bar
    print(game.GameId)
    
  3. The number in the Output is your universe ID. If the Output is closed, open it with Window, Output.
  4. If the number is 0, the game is not published yet. Select File, Publish to Roblox, then Create new experience, give it a name and select Create. Run the line again. DataStores and R3FTO need a published experience.

The same number is in the address of your experience's page in Creator Hub.

Step 3. Save the universe ID and copy the Test token

  1. In R3FTO, open your game, then Platforms, then the Roblox tab.
  2. Paste the number in Universe ID and select Save. R3FTO then makes your SDK tokens, one for Test and one for Production, and the webhook for your game.
  3. Switch to Test with the Production and Test switch in the sidebar. In R3FTO SDK token, select the eye button (Show SDK token) or the copy button (Copy SDK token). The token starts with r3rbx_. If the row says "No token yet. Regenerate makes one.", select Regenerate.

Keep the token only as a Roblox secret (next step). Never put it in a script, a chat message or an email. R3FTO records each time a token is shown. If a token leaks, select Regenerate and put the new token in the secret. The old token stops working at once.

Step 4. Studio settings and the Local Secret

  1. In Studio, stop Play if it is running. Open File, Experience Settings, Security.
  2. Turn on Allow HTTP Requests.
  3. Turn on Enable Studio Access to API Services. Studio needs it for DataStores.
  4. Under Local Secrets, add a secret: Name R3FTO_SDK_TOKEN, Secret: the Test token, Domain r3f.to.
  5. Select Save. If Save is greyed out, the secret is not saved yet.
  6. Open Experience Settings again and check that R3FTO_SDK_TOKEN is still in Local Secrets. If it is gone, see The Local Secret is not saved.

Local Secrets work only when you select Play in Studio. Team Test and live servers read the secret from Creator Hub (Step 11). No script can read a secret's value. Roblox only adds it to the request R3FTO receives.

Step 5. Start the SDK

  1. In the Explorer, hover over ServerScriptService, select + and choose Script. Do not choose LocalScript or ModuleScript.
  2. Press F2 and name it R3FTOStart.
  3. Delete the line Studio wrote in the new script and paste this code:
    ServerScriptService/R3FTOStart · Script
    -- Script · ServerScriptService/R3FTOStart
    -- Starts the R3FTO SDK once, on the server. Replace nothing here except ENVIRONMENT when you go live.
    --
    -- Before you press Play:
    --   * Experience Settings > Security: turn on "Allow HTTP Requests" and "Enable Studio Access to API Services".
    --   * Experience Settings > Security > Local Secrets (Studio) or Creator Hub > your experience > Secrets (live servers):
    --     add the secret R3FTO_SDK_TOKEN with the SDK token R3FTO gave you, domain r3f.to. Never paste the token here.
    
    local ServerScriptService = game:GetService("ServerScriptService")
    
    local R3FTO = require(ServerScriptService:WaitForChild("R3FTO"))
    
    local ENVIRONMENT = "test" -- "test" while you integrate; "production" only with your Production token
    
    local ok, reason = R3FTO.start({
    	environment = ENVIRONMENT,
    	tokenSecretName = "R3FTO_SDK_TOKEN",
    })
    if not ok then
    	warn("[Example] R3FTO did not start: " .. tostring(reason))
    end
    

Keep ENVIRONMENT = "test" until you go live in Step 11.

Step 6. Add one line to your receipt handler

Your game keeps its own receipt handler. R3FTO adds one line to it.

  1. Press Ctrl+Shift+F and search the whole game for ProcessReceipt.
  2. At the top of that script, add:
    At the top of that script
    local R3FTO = require(game:GetService("ServerScriptService"):WaitForChild("R3FTO"))
    
  3. Add this line as the first line inside the handler, before your own product delivery:
    Inside your receipt handler · one line
    pcall(R3FTO.observeReceipt, receiptInfo)
    
  • The line returns at once and never changes your decision. The purchase stays fully in your code.
  • Never add a second ProcessReceipt. Roblox uses only the last one set, so your own handler would stop working. If you use BindReceiptHandler, add the line inside your bound handler.
  • Every path that handles a developer product must reach this line, or those sales are not reported.

If your game has no receipt handler yet

Add a Script named ReceiptHandler in ServerScriptService, the same way as in Step 5, with this test stand-in. It gives nothing and only prints the purchase. Before you go live, put your own product delivery where the comment is.

ServerScriptService/ReceiptHandler · Script, test stand-in
local MarketplaceService = game:GetService("MarketplaceService")
local ServerScriptService = game:GetService("ServerScriptService")
local R3FTO = require(ServerScriptService:WaitForChild("R3FTO"))

MarketplaceService.ProcessReceipt = function(receiptInfo)
	pcall(R3FTO.observeReceipt, receiptInfo)
	-- Test stand-in: give the product and save it here, then return PurchaseGranted.
	print("Purchase granted:", receiptInfo.PurchaseId, "product", receiptInfo.ProductId)
	return Enum.ProductPurchaseDecision.PurchaseGranted
end

Return PurchaseGranted only after the product is given and saved. Otherwise return NotProcessedYet. For a full handler, see the example game.

Step 7. Make a test purchase

  1. Optional, if your game has no buy button yet: hover over StarterPlayer, StarterPlayerScripts, select + and choose LocalScript. Name it BuyTest and paste this code. Put your product ID in place of 0. You find the ID in Creator Hub, your experience, Monetization, Developer Products.
    StarterPlayer/StarterPlayerScripts/BuyTest · LocalScript, optional
    local Players = game:GetService("Players")
    local MarketplaceService = game:GetService("MarketplaceService")
    local UserInputService = game:GetService("UserInputService")
    
    local PRODUCT_ID = 0 -- your developer product ID
    
    UserInputService.InputBegan:Connect(function(input, processed)
    	if processed then return end
    	if input.KeyCode == Enum.KeyCode.B then
    		MarketplaceService:PromptProductPurchase(Players.LocalPlayer, PRODUCT_ID)
    	end
    end)
    
  2. Select Play.
  3. Click in the game, press B (or use your own buy button) and buy the product. A purchase in Studio is a test purchase and spends no Robux.
  4. Check the Output:
    Expected Output
    [R3FTO] started for test (SDK 0.4.0)
    [R3FTO] server signal started sent
    [R3FTO] receipt <PurchaseId>: DataStore copy written
    [R3FTO] receipt <PurchaseId>: delivered to R3FTO (recorded)
    

The two receipt lines can come in either order. With the test stand-in, a Purchase granted line comes before the two receipt lines. If you see a [R3FTO] warning, see Troubleshooting.

Step 8. Check it in R3FTO

  1. In R3FTO, in Test, open Roblox activity in your game's menu. Your purchase is there as a Purchase from SDK, marked Recorded, next to a Server started row marked Running.
  2. On the Roblox tab, Last SDK signal shows the time, the SDK version, 1 server and Live.

Both pages update by themselves.

Step 9. Set up the webhook

The webhook lets Roblox send its notifications for your experience to R3FTO. R3FTO made it when you saved the universe ID. One webhook serves Test and Production.

  1. On the Roblox tab, copy the Webhook URL and the Webhook secret with the copy buttons next to them.
  2. In Creator Hub, open Webhooks and create a webhook. Paste the URL (it looks like https://r3f.to/rwh/…) and the secret. If the form asks for a content type, choose application/json.
  3. Turn on every event in the list.
  4. Select Test Response to send a test notification.
  5. In R3FTO, Roblox activity shows a Webhook row with SampleNotification, marked Accepted. On the Roblox tab, Last webhook shows the same.

If it says Rejected, the line under it names the check that failed, most often the secret you pasted in Roblox. If nothing arrives, check the URL. Roblox allows up to 5 webhooks in total. For a group-owned game, only group owners can configure and receive webhook notifications.

Step 10. Add your Open Cloud API key

With this key, R3FTO reads your experience's start place, so creator links open your game, and the SDK's receipt copies in your data stores, so it still finds a receipt that did not reach R3FTO. One key serves Test and Production.

  1. In Creator Hub, open Open Cloud, API Keys, Create API Key.
  2. Choose the API system Data stores, for this experience only, with the operations list entries and read entries (universe-datastores.objects:list and universe-datastores.objects:read). Add nothing that writes or deletes, and no other API system.
  3. On the Roblox tab, paste the key in Roblox Open Cloud API key and select Save key. R3FTO stores it encrypted and shows only its last four characters from now on.
  4. Look at Last API check. It shows Waiting at first, because R3FTO checks at most once an hour. Then it shows Working, or No records yet while your data store has no receipt copies. Key refused means the key needs list and read access to this experience's data stores.

Step 11. Go live

  1. Before you go live, test once on a Roblox server with Team Test and the Test token (see Team Test and live servers).
  2. Remove BuyTest and R3FTOTestDemos if you added them. If you used the test stand-in handler, put your own product delivery in it.
  3. In R3FTO, switch to Production and copy the R3FTO SDK token.
  4. In Creator Hub, open your experience, Secrets. Create the secret R3FTO_SDK_TOKEN with the Production token and the domain r3f.to. If you made it for Team Test, edit it and replace the Test token with the Production token. Live servers read this secret, not your Local Secrets.
  5. In R3FTOStart, set ENVIRONMENT to "production".
  6. Publish the game. When a live server starts, Last SDK signal in Production shows Live.

Test and Production never mix. R3FTO refuses a report when the token does not match the environment in R3FTOStart, or when it comes from another experience. Simulated receipts work only in Test.

Documentation

Back to site