API Documentation

API Reference

Complete reference for the PayDirect v1 REST API. All settlement happens on Base mainnet.

Base URL

https://www.paydirect.com/api/v1

Local development: http://localhost:3000/api/v1

Important: Always use www.paydirect.com (with www). Requests to paydirect.com redirect with a 307, which strips the Authorization header.

Authentication

All requests require a Bearer token in the Authorization header

Authorization: Bearer pd_test_abc123...

Key Prefix	Environment	Behavior
`pd_test_`	Sandbox	Simulated settlement, instant lifecycle completion
`pd_live_`	Live	Real Base mainnet transactions with on-chain fee deduction

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes (POST)	application/json
`Idempotency-Key`	No	Unique key to prevent duplicate payment creation

Rate Limiting

Sliding window rate limits per API key

Plan	Limit	Window
Free	100 requests	Per minute
Pro	1,000 requests	Per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
Retry-After: 42        (only on 429 responses)

Fee Model

Tiered fee rates — automatic deduction on every settlement

Token	Fee Rate	Example (100 USDC, Free tier)
USDC	1.5% (Free) / 1.0% (Pro) / 0.5% (Enterprise)	Fee: 1.50 USDC, Merchant receives: 98.50 USDC
ETH	1.5% (Free) / 1.0% (Pro) / 0.5% (Enterprise)	Fee: 0.015 ETH, Merchant receives: 0.985 ETH
ADAO	0.75% (Free) / 0.5% (Pro) / 0.25% (Enterprise)	Fee: 0.75 ADAO, Merchant receives: 99.25 ADAO

Fees are deducted automatically during settlement. The merchant receives the net amount. See Settlement & Fees for tiered rates and details.

All Endpoints

Complete list of v1 API endpoints