PayXor Backend API

Backend API for PayXor payment and entitlement system. Public endpoints do not require authentication. Admin endpoints under /api/admin require a Bearer access token.

Public Endpoints

POST /api/quote

Generate a signed quote for a payment. Returns a quote object and backend signature for EIP-712 signing.

Request Body:
{
  "appId": "0x...",        // App ID (hex string)
  "productId": "0x...",    // Product ID (hex string)
  "chainId": 8453,         // Chain ID (number)
  "payer": "0x...",        // Payer address (hex string)
  "tokenAddress": "0x..."  // Optional: Specific token address
}

Response:
{
  "quote": {
    "quoteId": "...",
    "appId": "0x...",
    "productId": "0x...",
    "payer": "0x...",
    "amount": "1000000000",
    "token": "0x...",
    "payee": "0x...",
    "chainId": 8453,
    "mode": "session" | "feature" | "pass",
    "entitlementId": "0x...",
    "duration": 3600,
    "expiresAt": 1234567890,
    "deadline": 1234567890
  },
  "sigBackend": "0x..."
}

Note: If tokenAddress is provided, it must be one of the app's supported stablecoins for the specified chain. Otherwise, the default stablecoin for the chain will be used.

GET /api/apps/[appId]/stablecoins

Get an app's supported stablecoins for a specific chain. Returns enriched token metadata including symbol, name, address, and decimals.

Query Parameters:
  chainId: number (required) - Chain ID to get stablecoins for

Example:
GET /api/apps/0x.../stablecoins?chainId=8453

Response:
{
  "stablecoins": [
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "decimals": 6
    },
    {
      "symbol": "USDT",
      "name": "Tether USD",
      "address": "0x...",
      "decimals": 6
    }
  ]
}

Note: Only returns stablecoins configured for the app on the specified chain. Returns empty array if no tokens are configured. The appId must be a bytes32 hex string (0x...).

POST /api/confirm-tx

Confirm a transaction after payment execution. Used to track successful payments and update entitlements.

Request Body:
{
  "txHash": "0x...",      // Transaction hash
  "quoteId": "..."       // Quote ID from quote response
}

GET /api/products/[appId]/[productId]

Fetch public product information for UI display and approval checks.

Example:
GET /api/products/0x.../0x...

Response:
{
  "appId": "0x...",
  "productId": "0x...",
  "name": "Pro Plan",
  "mode": "session" | "feature" | "pass",
  "price": "1000000000",
  "duration": 3600,
  "entitlementId": "0x..." | null
}

Note: Both appId and productId must be bytes32 hex strings (0x...).

Authentication

Admin API requests require authentication using a Bearer access token. Include it in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Use the same access token issued by the dashboard session. Keep it secure and never expose it in client-side code.

Error Responses

All endpoints return standard error responses:

{
  "error": "Error message describing what went wrong"
}

Common HTTP status codes: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 500 (Internal Server Error)