Forest Logo
search
package_2

r3fto-roblox-sdk

By @mrcha0s

Roblox

Mirrored from Wally

R3FTO 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

  1. Download R3FTO.rbxm from the latest release.
  2. 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_TOKEN with domain r3f.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:

OptionDefaultNotes
environmentnone (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.
quietfalseHides 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

  1. observeReceipt takes the first observation time (DateTime.now(), UTC, milliseconds) before anything that can yield, and checks the receipt fields.
  2. DataStore copy. UpdateAsync on DataStore R3FTO_Receipts_v1, scope test|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 its firstObservedAtUtc becomes the one this server reports. The transform makes no network call.
  3. Direct delivery. POST {apiBaseUrl}/v1/roblox-sdk/receipts with Authorization: Bearer <secret>. R3FTO answers 200 only after its PostgreSQL commit. A repeat of the same PurchaseId answers already_recorded and is never counted twice.
  4. 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-After can 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):

ValueMeaning
deliveredR3FTO committed it to PostgreSQL.
stored_awaiting_deliveryThe DataStore copy exists; R3FTO has not acknowledged it yet.
memory_onlyNo durable copy yet. Attempts remain.
not_durableEvery 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-observations with 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, TSTB and TSTC; 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().referralObservations counts this server's arrivals, and getDiagnostics().referralOutcomes counts R3FTO's answers (recorded, already_recorded, unrecognized_reference) and failed (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-selections with 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, TSTB and TSTC. A Production token in Studio records real keys that count in public numbers.
  • Diagnostics. getDiagnostics().keyPanelOutcomes counts 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. started once after start, alive every hour, and closing once when the server shuts down (from game: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/heartbeats with 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().heartbeat shows 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 ProcessReceipt for 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_REQUIRED and 401 CREDENTIAL_REVOKED.
  • 403 ENVIRONMENT_MISMATCH, 403 UNIVERSE_MISMATCH and 403 SIMULATION_NOT_ALLOWED.
  • 413, 415 and 503 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.luau runs 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.rbxm with 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

check_circle

Safe for commercial use

Automated license review — not legal advice.