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 at creation, so there is no per-request sandbox header to manage. Resetting a sandbox clears its data in place while keeping the same sandbox ID and key bindings, which is the fastest way to return a disposable QA environment to a clean state. 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/sandboxes

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
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/sandboxesIdempotent

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
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}

Returns a single sandbox by ID.

Path parameters
sandbox_idstringrequired

Flint sandbox ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
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}/archiveIdempotent

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
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}/resetIdempotent

Clears a non-default sandbox in place while preserving the same sandbox ID and test payment configuration.

Path parameters
sandbox_idstringrequired

Flint sandbox ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
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-keyIdempotent

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
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.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