flintDocs

Sandboxes

Sandboxes are isolated test environments on the public API. There is no separate sandbox hostname: normal /v1/... requests go to https://api.withflintpay.com, and the sandbox-bound flint_test_... key you authenticate with decides which sandbox handles the request. Every developer merchant gets one default sandbox automatically; create additional sandboxes for CI, partner QA, or pre-release testing.

The default sandbox is prepared for test card payments automatically at sign-up. For a short time after, its accept_card_payments capability can be pending. If an earlier attempt to set up a sandbox's test payments failed, the next attempt starts a fresh setup instead of staying stuck, and the sandbox doesn't need a reset. Before relying on a sandbox for card payments, check GET /v1/capabilities?capability=accept_card_payments and wait for ready.

Test keys are permanently bound to one sandbox environment at creation, so there is no per-request sandbox header to manage. Resetting a sandbox archives that environment, clears its data, and returns a replacement with a new sandbox ID. The replacement retains the stable provider-account lineage, but you must issue new test keys because keys for the archived environment stop authorizing requests. The default sandbox cannot be archived or reset.

Note:

See the Testing guide for the runtime testing loop, including test cards and simulating payment outcomes.

List sandboxes#

GET/v1/developer/sandboxes

Requires scope developer.sandboxes.read or developer.sandboxes.write

Returns the merchant's sandboxes, including archived sandboxes. Flint guarantees a default test sandbox for every merchant. Use an onboarding session token during setup or a normal external API key afterward.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Page token returned by the previous list response.

statusenum

Filter sandboxes by status.

  • active
  • archived
  • all

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/developer/sandboxes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "created_at": "2026-03-18T19:45:00Z",
      "is_default": true,
      "name": "Default Test",
      "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
      "status": "active",
      "updated_at": "2026-03-18T19:45:00Z"
    },
    {
      "created_at": "2026-03-18T20:00:00Z",
      "is_default": false,
      "name": "Partner Demo",
      "sandbox_id": "test_01JQEXAMPLEPARTNER1234567",
      "status": "active",
      "updated_at": "2026-03-18T20:00:00Z"
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create sandbox#

POST/v1/developer/sandboxesIdempotent

Requires scope developer.sandboxes.write

Creates a new test sandbox for the current merchant. Optionally seeds the new empty sandbox with the merchant's live defaults and issues a sandbox-bound test key as part of creation.

Request body

issue_test_keyboolean
namestringRequired
scopesarray of string
test_key_namestring

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/developer/sandboxes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "issue_test_key": true,
    "name": "QA",
    "scopes": [
      "commerce.orders.read",
      "commerce.orders.write"
    ],
    "test_key_name": "QA integration key"
  }'

Get sandbox#

GET/v1/developer/sandboxes/{sandbox_id}

Requires scope developer.sandboxes.read or developer.sandboxes.write

Returns a single sandbox by ID.

Path parameters

sandbox_idstringRequired

Flint sandbox ID.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/developer/sandboxes/test_01JQEXAMPLEDEFAULT12345678 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "created_at": "2026-03-18T19:45:00Z",
    "is_default": true,
    "name": "Default Test",
    "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "status": "active",
    "updated_at": "2026-03-18T19:45:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Retire sandbox#

DELETE/v1/developer/sandboxes/{sandbox_id}Idempotent

Requires scope developer.sandboxes.write

Retires a non-default sandbox and frees its original name for reuse.

Path parameters

sandbox_idstringRequired

Flint sandbox ID.

Response · 200

Same response as Get sandbox.

curl -X DELETE https://api.withflintpay.com/v1/developer/sandboxes/test_01JQEXAMPLEDEFAULT12345678 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Reset sandbox#

POST/v1/developer/sandboxes/{sandbox_id}/resetIdempotent

Requires scope developer.sandboxes.write

Clears a non-default sandbox and returns its replacement environment. The replacement has a new sandbox ID, retains the stable provider-account lineage, and requires newly issued test keys.

Path parameters

sandbox_idstringRequired

Flint sandbox ID.

Response · 200

Same response as Get sandbox.

curl -X POST https://api.withflintpay.com/v1/developer/sandboxes/test_01JQEXAMPLEDEFAULT12345678/reset \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Issue sandbox test key#

POST/v1/developer/sandboxes/{sandbox_id}/test-keyIdempotent

Requires scopes accounts.api_keys.write and developer.sandboxes.write

Creates a new test API key that is bound to the target sandbox.

Path parameters

sandbox_idstringRequired

Flint sandbox ID.

Request body

namestringRequired
scopesarray of string

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/developer/sandboxes/test_01JQEXAMPLEDEFAULT12345678/test-key \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Partner demo key",
    "scopes": [
      "commerce.orders.read",
      "customers.read"
    ]
  }'

Was this helpful?