API Overview

CryptoPay provides a comprehensive RESTful API for managing blockchain payments. Our API is designed to be developer-friendly with consistent patterns, detailed error messages, and comprehensive documentation.

Base URL

Authentication

All API requests require authentication using Bearer tokens. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

1. Register an account at our platform
2. Login to get your access token
3. Use the token for all subsequent API calls

# Login to get your token
curl -X POST /api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

Request Format

• Content-Type: application/json
• Method: Standard HTTP methods (GET, POST, PUT, DELETE)
• Body: JSON formatted data for POST/PUT requests

Response Format

All API responses follow a consistent JSON structure:

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Success message",
  "timestamp": "2024-01-01T12:00:00Z"
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": ["This field is required"]
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Rate Limiting

API requests are rate limited to ensure fair usage:

• Standard Plan: 1000 requests per hour
• Premium Plan: 5000 requests per hour
• Enterprise Plan: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination using query parameters:

GET /api/payment-orders/?page=2&page_size=50

Response includes pagination metadata:

{
  "count": 150,
  "next": "/api/payment-orders/?page=3",
  "previous": "/api/payment-orders/?page=1",
  "results": [
    // Payment orders here
  ]
}

Core Resources

Payment Orders

Create and manage payment requests for your customers.

• POST /api/payment-orders/ - Create payment order
• GET /api/payment-orders/ - List payment orders
• GET /api/payment-orders/{id}/ - Get payment order details

Transactions

View blockchain transaction details and confirmations.

• GET /api/transactions/ - List transactions
• GET /api/transactions/{hash}/ - Get transaction details

Merchant Wallets

Configure blockchain-specific wallet addresses.

• GET /api/merchant-wallets/ - List wallet addresses
• POST /api/merchant-wallets/ - Add wallet address
• PUT /api/merchant-wallets/{id}/ - Update wallet address

Webhooks

Configure webhook endpoints for real-time notifications.

• GET /api/webhook-endpoints/ - List webhook endpoints
• POST /api/webhook-endpoints/ - Create webhook endpoint
• PUT /api/webhook-endpoints/{id}/ - Update webhook endpoint

HTTP Client Libraries

You can use any HTTP client library in your preferred programming language to interact with our REST API:

• JavaScript/Node.js: fetch(), axios, node-fetch
• Python: requests, httpx, urllib
• PHP: cURL, Guzzle, file_get_contents
• Go: net/http, resty

JavaScript Example

// Using fetch() - available in modern browsers and Node.js 18+
const response = await fetch('/api/payment-orders/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '100.00',
    currency: 'USDC',
    blockchain: 'base',
    order_info: JSON.stringify({
      product: 'Premium Plan'
    }),
    nonce: Date.now() + Math.floor(Math.random() * 1000000)
  })
});

const order = await response.json();

Testing

Use our sandbox environment for testing:

https://sandbox-api.cryptopay.com

Sandbox features:

• Test API keys that don't process real payments
• Simulated blockchain confirmations
• Webhook testing tools
• Test cryptocurrency tokens

Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Internal Server Error

Next Steps

• Payment Orders API - Create and manage payments
• Webhooks API - Real-time notifications
• Transactions API - View payment details
• Authentication - Detailed auth guide