API Authentication

All API requests require authentication using your merchant API key.

API Key

Include your API key in the X-API-Key header:

curl https://api.zkp2p-pay.xyz/api/merchants/me \
  -H "X-API-Key: your_api_key"

Getting Your API Key

When you create a merchant account, you receive an API key:

curl -X POST https://api.zkp2p-pay.xyz/api/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-store",
    "displayName": "My Store"
  }'

Response:

{
  "success": true,
  "responseObject": {
    "id": "merch_abc123",
    "name": "my-store",
    "displayName": "My Store",
    "apiKey": "zkp_live_a1b2c3d4e5f6..."
  }
}

caution

The apiKey is only returned once. Store it securely immediately.

Security Best Practices

1. Never expose in client-side code - Only use API keys on your backend
2. Use environment variables - Don't hardcode keys
3. Rotate if compromised - Contact support to rotate your key

Request Example

const response = await fetch('https://api.zkp2p-pay.xyz/api/checkout/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.ZKPAY_API_KEY!,
  },
  body: JSON.stringify({
    merchantId: 'merch_abc123',
    amountUsdc: '50.00',
    // ...
  }),
});

Response Format

All API responses follow this structure:

interface ApiResponse<T> {
  success: boolean;
  message: string;
  responseObject: T;
  statusCode: number;
}

Success Response

{
  "success": true,
  "message": "Session created successfully",
  "responseObject": { ... },
  "statusCode": 201
}

Error Response

{
  "success": false,
  "message": "Invalid API key",
  "responseObject": null,
  "statusCode": 401
}

Error Codes

Status	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key doesn't have access
404	Not Found - Resource doesn't exist
500	Server Error - Something went wrong

Rate Limits

API rate limits apply per merchant:

Endpoint	Limit
POST /api/checkout/sessions	100/min
GET /api/checkout/sessions/:id	300/min
POST /api/orders/fulfill	50/min

Exceeding limits returns 429 Too Many Requests.