API Overview

Base URL

All API requests should be made to:

https://payzo.cc/api/v1

Authentication

Payzo uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Or alternatively, use the X-API-Key header:

X-API-Key: YOUR_API_KEY

Request Format

All requests must:

Use HTTPS
Send JSON payloads with Content-Type: application/json
Include authentication headers

Response Format

All responses are returned in JSON format:

{
  "data": { ... },
  "error": null
}

Success Response

{
  "id": "pay_abc123",
  "status": "pending",
  "amount": 5000,
  "currency": "usd",
  "checkout_url": "https://payzo.cc/checkout/my-shop/pay_abc123",
  "created_at": "2025-01-12T10:30:00Z"
}

Error Response

{
  "error": "Amount must be at least 50 cents"
}

HTTP Status Codes

Code	Meaning
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Account inactive or insufficient permissions
`404`	Not Found - Resource doesn't exist
`500`	Server Error - Something went wrong on our end

Rate Limits

Currently, there are no strict rate limits enforced. However, we recommend:

Maximum 100 requests per minute per shop
Use webhooks instead of polling for payment status

Excessive usage may result in temporary throttling.

CORS (Browser Integration)

If you're calling our API directly from a browser/frontend (JavaScript, React, Vue, etc.), CORS is enabled:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Important: For better security, we recommend calling our API from your backend/server instead of directly from the browser. This prevents exposing your API key in client-side code.

CORS is primarily useful for:

Testing/prototyping with frontend-only code
Single-page applications where backend integration isn't possible

For production shops, use server-side integration (Node.js, Python, PHP, Lua/SellHub).

API Endpoints

Payments

POST /api/v1/payments - Create a payment
GET /api/v1/payments - List payments
GET /api/v1/payments/{id} - Get payment details

Testing

Test Mode

Currently, Payzo operates in live mode only. All payments are real transactions.

Important: Use small amounts (minimum $0.50) for testing purposes.

Test Webhook

Use the Test Webhook button in your dashboard to send a test payload to your webhook endpoint without creating a real payment.

Best Practices

1. Use Webhooks

Don't poll the API for payment status. Use webhooks to receive real-time notifications.

//  Bad: Polling
setInterval(async () => {
  const payment = await fetch(`/api/v1/payments/${id}`);
  if (payment.status === 'completed') {
    // Process...
  }
}, 5000);
 
//  Good: Webhooks
app.post('/webhook', (req, res) => {
  const { event, payment } = req.body;
  if (event === 'payment.completed') {
    // Process immediately
  }
});

2. Handle Errors Gracefully

try {
  const response = await fetch('https://payzo.cc/api/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({...})
  });
 
  if (!response.ok) {
    const error = await response.json();
    console.error('Payment creation failed:', error.error);
    return;
  }
 
  const payment = await response.json();
  // Redirect to checkout_url
} catch (error) {
  console.error('Network error:', error);
}

3. Store Payment IDs

Always store the payment.id returned from the API to track payments in your database.

// Save to your database
await db.orders.update({
  orderId: orderId,
  payzoPaymentId: payment.id,
  checkoutUrl: payment.checkout_url
});