Merchants API
Multi-merchant management endpoints for creating and managing merchant accounts. All endpoints require admin authentication.
See Admin API for authentication details.
Merchant object
json
{
"id": "merch_abc123",
"name": "My Shop",
"api_key_prefix": "pw_live_xxxx",
"webhook_url": "https://myshop.com/webhooks/paywarden",
"webhook_secret": "whsec_xxx...",
"orders_count": 142,
"revenue_total": "14200.00",
"active": true,
"created_at": "2025-01-01T00:00:00Z"
}Endpoints
| Method | Path | Description |
|---|---|---|
GET | /admin/merchants | List all merchants |
POST | /admin/merchants | Create a merchant |
GET | /admin/merchants/:id | Get merchant details |
PATCH | /admin/merchants/:id | Update merchant |
POST | /admin/merchants/:id/rotate-key | Rotate API key |
DELETE | /admin/merchants/:id | Delete merchant |
See Admin API for full request/response schemas.
Multi-merchant setup
In multi-merchant mode, each merchant:
- Has a unique API key — orders created with a key are scoped to that merchant
- Sees only their own orders in the dashboard
- Has their own webhook URL and secret
- Shares the global address pool (address indices are globally unique)
Webhook secrets per merchant
Each merchant has a webhook_secret used to sign webhook deliveries to their webhook_url. This is separate from the admin-level API_KEY.
bash
# Merchant verifies their webhook
X-PayWarden-Signature: sha256=<hmac-sha256(body, merchant.webhook_secret)>Isolation guarantees
| Resource | Isolated per merchant? |
|---|---|
| Orders | ✅ Yes |
| Payment addresses | ✅ Yes (by ownership) |
| Webhook events | ✅ Yes |
| HD wallet seed | ❌ Shared (single vault) |
| Address index pool | ❌ Shared (globally sequential) |
Cloud version
In PayWarden Cloud (coming soon), each merchant has a completely isolated vault with their own encrypted seed. See Cloud for details.