API Overview

PayWarden exposes a REST API for creating and managing payment orders.

Base URL

http://localhost:3000/api/v1     # local development
https://pay.yourdomain.com/api/v1  # production

Authentication

All API requests (except the checkout status endpoint) require an X-API-Key header:

curl -H "X-API-Key: your-api-key" https://pay.yourdomain.com/api/v1/payments

API keys are configured in your .env file. For multi-merchant setups, each merchant has their own API key issued by the admin dashboard.

Response format

All responses are JSON. Errors follow this structure:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

Endpoints

Method	Path	Description
POST	/payments	Create a payment order
GET	/payments/:id	Get order details
GET	/payments	List orders (paginated)
GET	/health	Health check
POST	/wallet/init	Initialize HD wallet (first time only)
GET	/checkout/:id/status	Public order status (no auth)

See individual pages for full request/response schemas.