Authentication

All Genius Checkout API requests authenticate with a Bearer token. The token is your API key.

POST /api/v1/checkout-sessions HTTP/1.1
Host: app.geniuscheckout.com
Authorization: Bearer gc_test_your_api_key_here
Content-Type: application/json

Modes

The key prefix determines which environment the request runs against:

• gc_test_ — test transactions. Uses the staging gateway. No real money moves.
• gc_live_ — live transactions. Real charges, real settlement.

A single account can have both keys active. Pick the right one for the environment you're integrating from.

Test and live keys are strictly partitioned

A gc_test_ key can never touch live data, and a gc_live_ key can never touch test data. This is enforced server-side on every endpoint — list, retrieve, charge, refund, tokenize, subscribe, deactivate. A cross-mode request returns 403 Forbidden (no leakage of resource existence). Picking the wrong key for the environment is the usual cause; verify your Authorization header before debugging deeper.

Base URL

https://app.geniuscheckout.com/api/v1

All endpoints in this documentation are relative to this base.

Common request headers

Header	Value
Authorization	Bearer <api_key>
Content-Type	application/json
Accept	application/json
Idempotency-Key (optional)	A UUID you generate per logical request

Idempotency

Send an Idempotency-Key header on POST requests that mutate state (creating sessions, charging tokens, refunds). Replays with the same key return the original response — safe to retry on network failure without double-charging.

Errors

A missing or invalid key returns 401 Unauthorized. See Error Handling for the full table.