Start typing to search packages!
r3fto-roblox-sdk
By @mrcha0s
Roblox
Mirrored from WallyR3FTO Roblox SDK (server, Luau) · 0.4.0
A server-only Luau package. Only its optional key panel reaches a player's device, and only when your server opens it for that player. It reports developer-product receipts and R3FTO creator-link references from a Roblox game server to R3FTO. It observes evidence. It never grants a product, never decides a purchase and never computes a creator share or an earning.
Full guide: https://r3f.to/docs/roblox. License: MIT (see LICENSE).
Install
Pick one. Each gives you the same R3FTO ModuleScript in ServerScriptService (never in ReplicatedStorage: the SDK
must not reach players' devices). Only the optional key panel's own part (KeyPanelGui) is copied to a player's device,
and only when your server calls R3FTO.openKeyPanel for that player.
A. Roblox Studio: drag and drop
- Download
R3FTO.rbxmfrom the latest release. - In Studio, drag the file onto ServerScriptService in the Explorer.
B. Rojo with Wally
# wally.toml
[server-dependencies]
R3FTO = "mrcha0s/r3fto-roblox-sdk@0.4.0"
Run wally install, map ServerPackages into ServerScriptService in your Rojo project, then use this line in place of
require(ServerScriptService:WaitForChild("R3FTO")) in your scripts:
local R3FTO = require(game:GetService("ServerScriptService").ServerPackages.R3FTO)
C. Rojo with Git
git submodule add https://github.com/R3Fto/roblox-sdk.git vendor/r3fto-roblox-sdk
git -C vendor/r3fto-roblox-sdk checkout v0.4.0
"ServerScriptService": {
"$className": "ServerScriptService",
"R3FTO": { "$path": "vendor/r3fto-roblox-sdk/src/R3FTO" }
}
D. By hand
Create these objects in Roblox Studio (names must match exactly) and paste each file into the object of the same name:
ServerScriptService
└── R3FTO ModuleScript ← src/R3FTO/init.luau
├── Client ModuleScript ← src/R3FTO/Client.luau
├── Engine ModuleScript ← src/R3FTO/Engine.luau
├── RobloxAdapters ModuleScript ← src/R3FTO/RobloxAdapters.luau
├── Version ModuleScript ← src/R3FTO/Version.luau
├── Wire ModuleScript ← src/R3FTO/Wire.luau
└── KeyPanelGui Folder
├── Look ModuleScript ← src/R3FTO/KeyPanelGui/Look.luau
└── Panel LocalScript ← src/R3FTO/KeyPanelGui/Panel.client.luau
Then, for every install
- Turn on Allow HTTP Requests (Experience Settings › Security).
- Store the SDK token from your game's Roblox tab on R3FTO (one for Test, one for Production; show or copy it there) as the
secret
R3FTO_SDK_TOKENwith domainr3f.to: Creator Hub › Secrets for live servers, and Experience Settings › Security › Local Secrets for Studio.
A working game is in examples/minimal-developer-product/.
API
local R3FTO = require(game:GetService("ServerScriptService"):WaitForChild("R3FTO"))
R3FTO.start({ environment = "test" }) -- once, from one server Script; "production" with the Production token
-- inside YOUR receipt handler, before your own grant code:
pcall(R3FTO.observeReceipt, receiptInfo)
R3FTO.simulateTestReceipt({ userId = 1, productId = 2, currencySpent = 25, simulationId = "demo-1" }) -- Test only
R3FTO.getReceiptStatus(purchaseId) -- this server's view of one receipt
R3FTO.getDiagnostics() -- safe to print: no token, no PlayerId, no creator key
R3FTO.openKeyPanel(player) -- optional: the R3FTO Key panel for one player
start options:
| Option | Default | Notes |
|---|---|---|
environment | none (required) | "test" or "production". Must match the token's environment; R3FTO refuses a mismatch. |
tokenSecretName | "R3FTO_SDK_TOKEN" | The secret name. The SDK reads it with HttpService:GetSecret; no script can read its value. |
apiBaseUrl | "https://r3f.to" | An https origin. |
quiet | false | Hides the [R3FTO] info lines; warnings still print. |
observeReceipt returns { accepted, purchaseId, firstObservedAtUtc, duplicate, queuedUntilStart?, reason? } at once.
It does no I/O itself: the work starts after your handler returns (task.defer). Calls made before start are kept,
with their own observation time, and sent when start runs.
Your handler stays the only handler. The SDK never sets MarketplaceService.ProcessReceipt and never calls
BindReceiptHandler. If you use BindReceiptHandler, add the same pcall(R3FTO.observeReceipt, receiptInfo) line
inside your bound handler. You still grant the product and return the decision. An R3FTO or DataStore-copy failure never
changes that decision.
What happens to a receipt
observeReceipttakes the first observation time (DateTime.now(), UTC, milliseconds) before anything that can yield, and checks the receipt fields.- DataStore copy.
UpdateAsyncon DataStoreR3FTO_Receipts_v1, scopetest|production, key = PurchaseId, tagged with the buyer's UserId. If a record already exists (written earlier, maybe by another server), it is kept unchanged and itsfirstObservedAtUtcbecomes the one this server reports. The transform makes no network call. - Direct delivery.
POST {apiBaseUrl}/v1/roblox-sdk/receiptswithAuthorization: Bearer <secret>. R3FTO answers200only after its PostgreSQL commit. A repeat of the same PurchaseId answersalready_recordedand is never counted twice. - Retries. Each channel makes its first attempt immediately. Retries follow at 60, 180 and 300 seconds after
that channel's first attempt, four attempts at most per channel. A channel that succeeds stops. A request R3FTO
rejects (4xx other than 408/425/429) is not retried.
Retry-Aftercan only skip a scheduled attempt, never add one. A repeated callback on the same server joins the running work and never restarts the schedule. A player arrival (see Creator links) retries longer: at 60, 180, 300, 600, 900, 1800 and 3600 seconds, eight attempts at most.
Durability (getReceiptStatus(...).durability):
| Value | Meaning |
|---|---|
delivered | R3FTO committed it to PostgreSQL. |
stored_awaiting_delivery | The DataStore copy exists; R3FTO has not acknowledged it yet. |
memory_only | No durable copy yet. Attempts remain. |
not_durable | Every attempt ended with no durable copy. If this server stops, the receipt evidence is lost. |
Per channel: state is pending, in_progress, retry_scheduled, succeeded, failed (all attempts used) or
rejected. lastError is storage_failed, transport_failed, ambiguous (a timeout: R3FTO may or may not have it;
the same PurchaseId is retried), throttled, rejected or not_configured (the SDK token secret is not available on
this server, so nothing was sent).
Creator links
A creator link brings a player into your experience with r3f_ and the creator's R3FTO key in its launch data (for
example r3f_KAEL). You never create these links and need no code for them: after start, the SDK reads the launch
data of every player who joins.
- Every join counts. Each join that carries a creator link value is reported once with the server-seen UserId, also when the player comes back with the same value or with another creator's. The same join is never reported twice.
- What.
POST {apiBaseUrl}/v1/roblox-sdk/referral-observationswith the same token: the value (prefix in lower case, key in upper case), the UserId and the join time. Any other launch data is yours and is ignored. - Retries. At 0, 60, 180, 300, 600, 900, 1800 and 3600 seconds after the first attempt, so a short outage does not lose an arrival. Every retry sends the same report, and R3FTO counts it once.
- Test and Production. A Test token accepts only the Test keys
TSTA,TSTBandTSTC; a Production token accepts real creator keys. When R3FTO does not recognize a value, one warning is printed per server (a creator link value was not recognized); later ones are info lines. - Diagnostics.
getDiagnostics().referralObservationscounts this server's arrivals, andgetDiagnostics().referralOutcomescounts R3FTO's answers (recorded,already_recorded,unrecognized_reference) andfailed(no answer after every attempt, or refused). No key and no UserId is printed or kept in diagnostics.
The R3FTO Key panel (optional)
Players can also type a creator's R3FTO Key in your game. Call R3FTO.openKeyPanel(player) from server code, for
example when the player presses your own button. The panel's words and layout are fixed, and no function sets a key for
a player.
- What a key does. A key the player types counts for that creator from the moment R3FTO records it, and comes before any creator link. Between creator links, the last link still wins.
- What is sent.
POST {apiBaseUrl}/v1/roblox-sdk/creator-selectionswith your SDK token: the server-seen UserId and the key. The panel shows only fixed words for each answer. - Limits. One request at a time per player and at most 60 a minute per server, so receipts keep their share of your server's HTTP requests. R3FTO also limits requests per game. A request is never retried on its own.
- Test and Production. Use the Test token in Studio. A Test token accepts only the Test keys
TSTA,TSTBandTSTC. A Production token in Studio records real keys that count in public numbers. - Diagnostics.
getDiagnostics().keyPanelOutcomescounts the answers. No key and no UserId is printed or kept.
Server signal
After start, each game server tells R3FTO that it runs the SDK, so your Roblox page can show your servers and any
receipts they could not save.
- When.
startedonce afterstart,aliveevery hour, andclosingonce when the server shuts down (fromgame:BindToClose, waiting at most 5 seconds). - What. The environment, universe, place, server JobId (in Studio, an id made for the session), SDK version, the
signal kind, the send time and this server's receipt counts by durability (
memory_only,stored_awaiting_delivery,not_durable). No PlayerId and nothing about players. - How.
POST {apiBaseUrl}/v1/roblox-sdk/heartbeatswith the same token. A signal runs in its own thread, never inside your receipt handler. A failed signal is not retried; the next one follows on schedule. If R3FTO refuses it (for example a wrong token or environment), one warning is printed per server. If the SDK token secret is not available on the server, nothing is sent and one warning per server says so (server signals are not sent); the warning at start names the secret and gives Roblox's own message. - Never affects purchases. The signal never changes a receipt, a purchase decision or anything R3FTO records about
purchases.
getDiagnostics().heartbeatshows the latest signal's kind, send time and result.
Limits you should know
- Your game server is the source. Receipts and DataStore records come from your own game server. They are not independent Roblox transaction records, so a correct and complete integration matters.
- Loss window. If both the DataStore copy and the R3FTO delivery fail and the server stops, the receipt and its first observation time are lost. Nothing reconstructs or estimates them. A missing record is not proof that no sale happened.
- Earliest time across servers. Roblox can run
ProcessReceiptfor one receipt on two servers at once. The DataStore keeps the first record that committed. R3FTO keeps the first delivery that committed and counts any later report that differs. During an outage, the time R3FTO keeps can be later than the true first observation on another server. - No automatic deletion. The SDK never deletes its DataStore records. Your existing data-deletion duties (including Roblox Right to Erasure) still apply; records carry the buyer's UserId to support them.
- Throughput. The SDK checks the server's DataStore budget before writing and sends at most one request per channel attempt, well within Roblox's per-server HTTP and DataStore limits.
Wire contract (for reference)
Roblox ids and Robux amounts are decimal strings. Times are ISO 8601 UTC with milliseconds.
POST /v1/roblox-sdk/receipts
{ "environment": "test", "universe_id": "123", "place_id": "456", "server_job_id": "…", "sdk_version": "0.4.0",
"simulated": false,
"receipt": { "purchase_id": "…", "player_id": "1", "product_id": "2", "currency_spent": "200",
"currency_type": "Robux", "place_id_where_purchased": "456", "purchase_channel": null },
"first_observed_at": "2026-11-11T10:30:45.123Z", "record_source": "sdk_direct" }
→ 200 { "outcome": "recorded" | "already_recorded", "receipt_id": "…", "first_observed_at": "…",
"matches_first_record": true }
POST /v1/roblox-sdk/referral-observations
{ "environment", "universe_id", "place_id", "server_job_id", "sdk_version",
"roblox_user_id": "1", "launch_reference": "r3f_KAEL", "observed_at": "…Z" }
→ 200 { "outcome": "recorded" | "already_recorded" | "unrecognized_reference" }
POST /v1/roblox-sdk/heartbeats
{ "environment", "universe_id", "place_id", "server_job_id", "sdk_version",
"kind": "started" | "alive" | "closing", "sent_at": "…Z",
"receipts": { "memory_only": 0, "stored_awaiting_delivery": 0, "not_durable": 0 } }
→ 200 { "outcome": "recorded" }
POST /v1/roblox-sdk/creator-selections
{ "environment", "universe_id", "place_id", "server_job_id", "sdk_version",
"roblox_user_id": "1", "action": "set", "creator_key": "KAEL" }
→ 200 { "outcome": "accepted" | "unknown_key" | "unavailable" }
Errors use the standard R3FTO error body. Codes:
400 VALIDATION_ERROR.401 AUTHENTICATION_REQUIREDand401 CREDENTIAL_REVOKED.403 ENVIRONMENT_MISMATCH,403 UNIVERSE_MISMATCHand403 SIMULATION_NOT_ALLOWED.413,415and503 SERVICE_UNAVAILABLE.429 RATE_LIMITED.
DataStore value (schema 1):
schema,purchaseId,playerId,productId,currencySpent,currencyType,placeIdWherePurchased.purchaseChannel,universeId,environment,firstObservedAtUtc,firstObservedServerJobId,sdkVersion,simulated.
Tests
luau tests/run.luauruns the SDK's real modules over fake Roblox services with a virtual clock. It checks:- retry offsets, a channel stopping after it succeeds, Retry-After and rejection;
- duplicate callbacks, the immutable and adopted first observation time;
- independent DataStore and transport failures, the no-I/O handler call;
- the pre-start queue, environment scopes, simulation marking and log hygiene;
- creator link values: the accepted format, one report per join, the arrival retry schedule and the warning;
- the server signal: its hourly schedule, no retry, the counts, the closing wait limit and the Studio id.
- CI runs these tests on every push, builds
R3FTO.rbxmwith Rojo and checks that the example place builds. - To check your own integration end to end, use your R3FTO Test token in a published Test experience, then look at Last SDK signal on your game's Roblox tab.
Package Details
Install command (Click to copy)
Version
0.4.0
License
MIT
Safe for commercial use
Automated license review — not legal advice.
