FlintflintDocs

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.

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.

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

Endpoints

List sandboxes#

GET/v1/developer/sandboxesRequires 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.

activearchivedall
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

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

Create sandbox#

POST/v1/developer/sandboxesIdempotentRequires 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

Error codes

AUTH_REQUIREDINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl -X POST https://api.withflintpay.com/v1/developer/sandboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "QA",
    "issue_test_key": true,
    "test_key_name": "QA integration key",
    "scopes": [
      "commerce.orders.read",
      "commerce.orders.write"
    ]
  }'
JSON
{
  "data": {
    "sandbox_id": "test_01JQEXAMPLEQASANDBOX123456",
    "name": "QA",
    "status": "active",
    "is_default": false,
    "created_at": "2026-03-18T20:10:00Z",
    "updated_at": "2026-03-18T20:10:00Z",
    "secret_key": "flint_test_51QAsampleSecret",
    "api_key": {
      "api_key_id": "key_123",
      "name": "QA integration key",
      "sandbox_id": "test_01JQEXAMPLEQASANDBOX123456",
      "key_prefix": "flint_test_x7Yk",
      "scopes": [
        "commerce.orders.read",
        "commerce.orders.write"
      ],
      "key_type": "external",
      "status": "active",
      "created_at": "2026-03-18T20:10:00Z",
      "updated_at": "2026-03-18T20:10:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

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

Error codes

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

Archive sandbox#

POST/v1/developer/sandboxes/{sandbox_id}/archiveIdempotentRequires scope: developer.sandboxes.write

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

Path parameters
sandbox_idstringrequired

Flint sandbox ID.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

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

Reset sandbox#

POST/v1/developer/sandboxes/{sandbox_id}/resetIdempotentRequires 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
dataobjectrequired
metaobject
request_idstring

Error codes

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

Issue sandbox test key#

POST/v1/developer/sandboxes/{sandbox_id}/test-keyIdempotentRequires scope: accounts.api_keys.write + 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

Error codes

AUTH_REQUIREDINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/developer/sandboxes/test_01JQEXAMPLEDEFAULT12345678/test-key \
  -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"
    ]
  }'
JSON
{
  "data": {
    "api_key_id": "key_123",
    "merchant_id": "mer_123",
    "name": "Sandbox orders integration",
    "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "key_prefix": "flint_test_abcd1234",
    "scopes": [
      "accounts.api_keys.read",
      "accounts.api_keys.write",
      "commerce.orders.read",
      "commerce.orders.write"
    ],
    "key_type": "external",
    "status": "active",
    "last_used_at": "2026-03-17T15:00:00Z",
    "expires_at": "2027-03-17T14:30:00Z",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "secret_key": "flint_test_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc