API Documentation

Authentication

All PayDirect API requests require authentication via a Bearer token in the Authorization header. Keys are scoped to a workspace and an environment (sandbox or live).

Making Authenticated Requests

Include your API key as a Bearer token in every request

curl https://www.paydirect.com/api/v1/payments \
  -H "Authorization: Bearer pd_test_abc123def456..." \
  -H "Content-Type: application/json"

If the key is missing or invalid, the API returns 401 Unauthorized.

Important: Use www.paydirect.com

Always use https://www.paydirect.com as the base URL. Requests to paydirect.com (without www) will redirect with a 307, and HTTP clients drop the Authorization header on redirects, causing 401 errors.

API Key Formats

Keys are prefixed by environment to prevent accidental misuse

Prefix	Environment	Behavior
`pd_test_`	Sandbox	Payments are simulated. The full lifecycle (pending → detected → confirmed → forwarded) completes instantly with no real on-chain transactions.
`pd_live_`	Live	Real Base mainnet transactions. Fees are deducted on-chain and the net amount is forwarded to the merchant wallet.

Getting Your API Keys

Via Dashboard

Go to Dashboard → Settings → API Keys to view, create, and revoke keys for your workspace.

Via API

Programmatically manage keys using the Keys API.

# Create a new sandbox key
curl -X POST https://www.paydirect.com/api/v1/keys \
  -H "Authorization: Bearer pd_test_existing_key..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend Server", "environment": "sandbox"}'

# Response
{
  "apiKey": {
    "id": "key-uuid-...",
    "name": "Backend Server",
    "environment": "sandbox",
    "is_active": true,
    "key": "pd_test_newly_generated_key..."
  }
}

The full key is only returned once at creation. Store it securely.

Key Management API

Method	Endpoint	Description
GET	/api/v1/keys	List all keys for the workspace (key values are masked)
POST	/api/v1/keys	Create a new key (returns full key once)
DELETE	/api/v1/keys/:id	Revoke a key (soft delete, sets is_active = false)

See the full Keys & Usage API reference.

Security Best Practices

Never expose API keys in client-side code or public repositories.
Use environment variables to store keys. Example: PAYDIRECT_API_KEY=pd_test_...
Use sandbox keys (pd_test_) during development and testing.
Rotate keys periodically and revoke any compromised keys immediately via the dashboard or API.
Each key is scoped to a single workspace. Create separate workspaces for different projects.