Skip to Content
Getting Started

Getting Started

Go from zero to your first payment in 5 minutes. This guide walks you through creating API keys, tokenizing a test card, authorizing a payment, and capturing funds.

Local Development

To run the gateway locally for testing, start the full stack with one command:

# Start PostgreSQL, Redis, vault, connectors, and gateway
make dev
 
# Or include the dashboard and docs site
make dev-all

This starts all services in DEV_MODE — authentication is bypassed and a sandbox connector is seeded. The API is available at http://localhost:4000/v1/.

See the README  for detailed setup instructions.

1. Get Your API Keys

Sign up for a Gatelithix account to receive your API keys. You will get two types of keys:

Key PrefixTypeUsage
sk_test_Secret (test)Server-side sandbox requests
sk_live_Secret (live)Server-side production requests
pk_test_Publishable (test)Client-side tokenization in sandbox
pk_live_Publishable (live)Client-side tokenization in production

Secret keys authenticate all server-to-server API calls. Never expose secret keys in client-side code. Publishable keys are safe for browser use and are limited to tokenization operations.

Creating your first connector account

Before your merchant can settle a charge, it needs at least one connector account — a per-merchant, per-mode binding to the processor credentials the gateway will use. Connector accounts replace the platform-wide credential env vars used in v2.2.x and earlier. See Connector Accounts for the full model.

Create one through the admin API:

curl -X POST https://sandbox.api.gatelithix.com/admin/merchants/{merchantId}/connector-accounts \
  -H "Authorization: Bearer sk_test_your_admin_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ca_create_$(uuidgen)" \
  -d '{
    "connector_id": "stripe",
    "mode": "test",
    "key_kind": "api_key",
    "label": "sandbox_default",
    "is_default": true,
    "credential_ref": "projects/gatelithix-core/secrets/merchant-mrc_xyz789abc0-stripe-test"
  }'

Response — 201 Created:

{
  "id": "aa0e8400-e29b-41d4-a716-446655440aaa",
  "short_id": "ca_abc123def4",
  "merchant_id": "22b1e200-c29b-41d4-a716-446655440000",
  "merchant_short_id": "mrc_xyz789abc0",
  "connector_id": "stripe",
  "mode": "test",
  "key_kind": "api_key",
  "label": "sandbox_default",
  "is_default": true,
  "is_active": true,
  "created_at": "2026-04-24T12:00:00Z"
}

The short_id (ca_abc123def4) is the public-facing identifier. You do not need to pass it on every charge when the account is is_default=true — the gateway picks it automatically. Multi-account merchants can override per-request via the connector_account body field; see Authentication.

2. Install an SDK

3. Tokenize a Test Card

Before creating a payment, tokenize the card number. This returns a gateway_token that you use in place of the raw card number for all subsequent operations.

Response:

{
  "token": "tok_test_aBcDeFgHiJkLmNoPqRsTuVwX",
  "bin_prefix": "4242",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2028,
  "card_brand": "visa",
  "created_at": "2026-03-18T12:00:00Z"
}

4. Authorize a Payment

Use the gateway token to authorize a payment. The amount is specified in cents (e.g., 5000 = $50.00).

5. Capture the Payment

Once the authorization succeeds, capture it to settle the funds.

6. Check the Result

Retrieve the PaymentIntent to confirm the final state.

Next Steps

IntroductionAuthentication