Sandbox & Non-Prod Testing

Always develop and test your integration against a non-prod tenant before
pointing it at a live venue. ROLLER's non-prod sandbox is the Playground
environment: same behaviour as Live, isolated data.

🔒

Never use live secrets in sandbox, or sandbox secrets in live. Credentials

are scoped to a single venue, per environment — a Playground key will not
work in Live and vice-versa. Keep the two credential sets separate and encrypted,
and never commit either to source control. All example values in these guides
are placeholders.

1. Playground: the non-prod sandbox

Base URLs may differ if you have a dedicated-domain agreement.

Why test in Playground first:

• Parity — Playground runs the same version as Live, so behaviour is an
  accurate representation of production.
• Scope safety — changes and tests in Playground do not affect live data,
  enabling isolated debugging without risk to real transactions or guests.

See Environments for the full detail.

2. Getting sandbox access

1. Log in to ROLLER Venue Manager.
2. Select the Your Account icon at the bottom of the left-side menu.
3. Select Switch to Playground venue — you are redirected to your Playground
   account.

To generate a test credential in Playground (for exploration before your app's
connect webhook is live), follow the manual key steps in
Getting API Access — they are identical in Playground.
The scope model and the OAuth2 token flow behave exactly as in
Vendor App Auth & Credentials; only the base
URL differs.

🚧

Do not click "Update Playground" in Venue Manager while you have API keys

generated and in use there. It irreversibly resets the Playground instance
and you will lose access to those keys.

3. Testing the connect/disconnect webhook contract

To exercise the integration-app lifecycle without a live
marketplace listing, ROLLER runs a canned-response webhook mock in non-prod.
It lets you drive each delivery outcome from ROLLER's side against a mock vendor
endpoint that returns a status keyed off the path:

Use these to confirm your handler is idempotent (repeat deliveries of the same
request_id resolve to 200/409) and that it validates the shared-secret header
correctly. Contact ROLLER for the current non-prod mock URL — see
Integration Apps §7.

4. A suggested sandbox checklist

• Obtain a Playground venue and a scoped test key.
• Complete the OAuth2 token exchange against https://api.play.roller.app/token
  and cache the token.
• Call each endpoint your app needs and confirm a 403 Invalid scope for any
  endpoint outside your declared scopes.
• Drive the connect/disconnect webhook mock through every response branch.
• Verify idempotency and shared-secret rejection (401) on your webhook
  handler.
• Confirm you tolerate unknown fields/enums (see the
  support policy).

Next

Once your app passes in the sandbox, move to
Submission & Review.