Suzaa API - Complete Documentation

Production: https://api.suzaa.com

Current Version: v1 (included in base URL path)

Merchant System → Suzaa API → Payment Request Created
                                       ↓
                           Customer Shown Payment Link
                                       ↓
                           QR Code with Wallet Address
                                       ↓
                    Customer Sends Payment on Blockchain
                                       ↓
                           Customer Clicks "I Paid"
                                       ↓
                         Redirects Back to Merchant
                                       ↓
              Merchant Verifies Transaction on Blockchain
                                       ↓
                            Fulfills Order if Valid

{
  "success": true | false,
  "data": {
    // Response data here
  },
  "error": {
    // Only present if success: false
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Authorization: Bearer sza_live_b20a7aa260a229853af02fd73fffdcd8a71ede41eaf775f5228fda2f265ef506

curl -X POST https://api.suzaa.com/payments/requests \
  -H "Authorization: Bearer sza_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "description": "Order #123"}'

POST /payments/requests

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "amount": "100.00",              // Required: Amount in USD (string or number)
  "description": "Order #12345",   // Required: Description/reference (max 500 chars)
  "expiryTime": 60,                // Required: Expiration in minutes (1-1440)
  "redirectUrl": "https://..."     // Optional: Where to redirect after payment
}

{
  "success": true,
  "data": {
    "success": true,
    "paymentRequestId": "fd74f812-268c-43bc-9e42-924ce36ce1ff",
    "linkId": "825757/20251213/0007",
    "paymentUrl": "https://app.suzaa.com/recipient/825757/20251213/0007",
    "expiresAt": "2025-12-13T15:52:28.353Z",
    "message": "Payment request created successfully"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be a positive number"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

const axios = require('axios');
 
async function createPaymentRequest() {
  try {
    const response = await axios.post('https://api.suzaa.com/payments/requests', {
      amount: '150.00',
      description: 'Premium Subscription - 1 Year',
      expiryTime: 120,
      redirectUrl: 'https://mysite.com/payment-return'
    }, {
      headers: {
        'Authorization': 'Bearer sza_live_YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Payment URL:', response.data.data.paymentUrl);
    console.log('Link ID:', response.data.data.linkId);
    
    return response.data.data;
  } catch (error) {
    console.error('Error:', error.response.data);
    throw error;
  }
}

<?php
 
function createPaymentRequest($apiKey, $amount, $description, $expiryTime = 60, $redirectUrl = null) {
    $data = [
        'amount' => $amount,
        'description' => $description,
        'expiryTime' => $expiryTime
    ];
    
    if ($redirectUrl) {
        $data['redirectUrl'] = $redirectUrl;
    }
    
    $ch = curl_init('https://api.suzaa.com/payments/requests');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 201) {
        throw new Exception('API Error: ' . $response);
    }
    
    $result = json_decode($response, true);
    return $result['data'];
}
 
// Usage
try {
    $payment = createPaymentRequest(
        'sza_live_YOUR_API_KEY',
        '100.00',
        'Order #12345',
        60,
        'https://mysite.com/return'
    );
    
    echo "Payment URL: " . $payment['paymentUrl'] . "\n";
    echo "Link ID: " . $payment['linkId'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

import requests
import json
 
def create_payment_request(api_key, amount, description, expiry_time=60, redirect_url=None):
    url = 'https://api.suzaa.com/payments/requests'
    
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    data = {
        'amount': str(amount),
        'description': description,
        'expiryTime': expiry_time
    }
    
    if redirect_url:
        data['redirectUrl'] = redirect_url
    
    response = requests.post(url, headers=headers, json=data)
    
    if response.status_code != 201:
        raise Exception(f'API Error: {response.text}')
    
    result = response.json()
    return result['data']
 
# Usage
try:
    payment = create_payment_request(
        api_key='sza_live_YOUR_API_KEY',
        amount=100.00,
        description='Order #12345',
        expiry_time=60,
        redirect_url='https://mysite.com/return'
    )
    
    print(f"Payment URL: {payment['paymentUrl']}")
    print(f"Link ID: {payment['linkId']}")
except Exception as e:
    print(f"Error: {e}")

GET /payments/requests/{paymentRequestId}

Authorization: Bearer YOUR_API_KEY

{
  "success": true,
  "data": {
    "paymentRequestId": "fd74f812-268c-43bc-9e42-924ce36ce1ff",
    "linkId": "825757/20251213/0007",
    "amount": "100.00",
    "description": "Order #12345",
    "status": "pending",
    "paymentUrl": "https://app.suzaa.com/recipient/825757/20251213/0007",
    "redirectUrl": "https://mysite.com/return",
    "expiryTime": 60,
    "expiresAt": "2025-12-13T15:52:28.353Z",
    "createdAt": "2025-12-13T14:52:28.353Z",
    "claimedAt": null
  }
}

curl -X GET https://api.suzaa.com/payments/requests/fd74f812-268c-43bc-9e42-924ce36ce1ff \
  -H "Authorization: Bearer sza_live_YOUR_API_KEY"

GET /payments/requests

Authorization: Bearer YOUR_API_KEY

{
  "success": true,
  "data": {
    "requests": [
      {
        "paymentRequestId": "fd74f812-268c-43bc-9e42-924ce36ce1ff",
        "linkId": "825757/20251213/0007",
        "amount": "100.00",
        "description": "Order #12345",
        "status": "claimed_paid",
        "createdAt": "2025-12-13T14:52:28.353Z",
        "expiresAt": "2025-12-13T15:52:28.353Z"
      }
      // ... more requests
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

curl -X GET "https://api.suzaa.com/payments/requests?page=1&limit=10&status=claimed_paid" \
  -H "Authorization: Bearer sza_live_YOUR_API_KEY"

DELETE /payments/requests/{paymentRequestId}

Authorization: Bearer YOUR_API_KEY

{
  "success": true,
  "data": {
    "message": "Payment request cancelled successfully",
    "paymentRequestId": "fd74f812-268c-43bc-9e42-924ce36ce1ff",
    "status": "canceled"
  }
}

curl -X DELETE https://api.suzaa.com/payments/requests/fd74f812-268c-43bc-9e42-924ce36ce1ff \
  -H "Authorization: Bearer sza_live_YOUR_API_KEY"

GET /public/payment/{linkId}

{
  "success": true,
  "data": {
    "linkId": "825757/20251213/0007",
    "amount": "100.00",
    "amountCrypto": "0.00234567",
    "cryptocurrency": "BTC",
    "walletAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "description": "Order #12345",
    "qrCodeUrl": "https://app.suzaa.com/qr/825757/20251213/0007.png",
    "status": "pending",
    "expiresAt": "2025-12-13T15:52:28.353Z",
    "redirectUrl": "https://mysite.com/return",
    "merchantName": "My Store"
  }
}

        CREATE
          ↓
      [PENDING] ──────────────────→ [EXPIRED]
          ↓                              ↑
    Customer Action                  Timeout
          ↓                              
   ┌──────┴──────┐
   ↓             ↓
[CLAIMED_PAID] [CANCELED]
   ↓
Merchant Verifies
on Blockchain

// 1. Customer clicks "Pay with Crypto"
app.post('/checkout', async (req, res) => {
  const order = await createOrder(req.body);
  
  // 2. Create Suzaa payment request
  const payment = await suzaa.createPaymentRequest({
    amount: order.total,
    description: `Order #${order.id}`,
    expiryTime: 60,
    redirectUrl: `https://mystore.com/order/${order.id}/confirm`
  });
  
  // 3. Store payment link ID with order
  await updateOrder(order.id, {
    suzaa_link_id: payment.linkId,
    suzaa_payment_url: payment.paymentUrl
  });
  
  // 4. Redirect customer to Suzaa payment page
  res.redirect(payment.paymentUrl);
});
 
// 5. Customer returns after clicking "I Paid"
app.get('/order/:id/confirm', async (req, res) => {
  const status = req.query.status; // claimed_paid or canceled
  const paymentId = req.query.paymentId;
  
  if (status === 'claimed_paid') {
    // Mark order as "pending verification"
    await updateOrder(req.params.id, {
      status: 'pending_verification',
      suzaa_payment_id: paymentId
    });
    
    res.render('thank-you', {
      message: 'Payment claimed! We will verify and process your order soon.'
    });
  } else {
    res.render('cancelled', {
      message: 'Payment cancelled. Please try again or choose another method.'
    });
  }
});
 
// 6. Admin manually verifies blockchain transaction
app.post('/admin/orders/:id/verify-payment', async (req, res) => {
  const order = await getOrder(req.params.id);
  
  // Admin checks blockchain and confirms transaction exists
  // Then marks order as paid
  await updateOrder(req.params.id, {
    status: 'paid',
    verified_at: new Date()
  });
  
  // Ship the order
  await shipOrder(req.params.id);
});

# Create recurring payment request
def create_subscription_payment(user_id, plan):
    payment = suzaa_api.create_payment_request(
        amount=plan.price,
        description=f"Subscription: {plan.name} - Month {get_current_month()}",
        expiry_time=1440,  # 24 hours
        redirect_url=f"https://myapp.com/subscription/callback/{user_id}"
    )
    
    # Store payment details
    db.subscriptions.update(user_id, {
        'payment_link_id': payment['linkId'],
        'payment_url': payment['paymentUrl'],
        'status': 'awaiting_payment'
    })
    
    # Email payment link to user
    send_email(
        to=user.email,
        subject="Your Monthly Subscription Payment",
        body=f"Please complete your payment: {payment['paymentUrl']}"
    )
    
    return payment

<?php
// Generate invoice and payment request
function createInvoice($customerId, $items) {
    $total = calculateTotal($items);
    
    // Create payment request
    $payment = SuzaaAPI::createPaymentRequest([
        'amount' => $total,
        'description' => "Invoice #" . generateInvoiceNumber(),
        'expiryTime' => 2880, // 48 hours
        'redirectUrl' => "https://myapp.com/invoices/paid"
    ]);
    
    // Create invoice record
    $invoice = Invoice::create([
        'customer_id' => $customerId,
        'items' => json_encode($items),
        'total' => $total,
        'suzaa_link_id' => $payment['linkId'],
        'suzaa_payment_url' => $payment['paymentUrl'],
        'status' => 'unpaid'
    ]);
    
    // Send invoice email with payment link
    sendInvoiceEmail($customerId, $invoice, $payment['paymentUrl']);
    
    return $invoice;
}

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "field": "fieldName" // Optional: which field caused the error
  }
}

async function createPaymentWithRetry(data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await suzaaAPI.createPaymentRequest(data);
      return response.data;
    } catch (error) {
      if (error.response) {
        const status = error.response.status;
        const errorCode = error.response.data.error?.code;
        
        // Don't retry client errors (4xx)
        if (status >= 400 && status < 500) {
          if (errorCode === 'RATE_LIMIT_EXCEEDED' && attempt < maxRetries) {
            // Wait before retry
            await sleep(2000 * attempt);
            continue;
          }
          
          // Other 4xx errors - don't retry
          throw new Error(`API Error: ${error.response.data.error.message}`);
        }
        
        // Retry server errors (5xx)
        if (status >= 500 && attempt < maxRetries) {
          await sleep(1000 * Math.pow(2, attempt)); // Exponential backoff
          continue;
        }
      }
      
      // Network error or max retries reached
      if (attempt === maxRetries) {
        throw error;
      }
      
      await sleep(1000 * attempt);
    }
  }
}

{
  paymentRequestId: "fd74f812...",  // For API queries
  linkId: "825757/20251213/0007",   // Human-readable reference
  paymentUrl: "https://app.suzaa.com/...",  // For customer
  expiresAt: "2025-12-13T15:52:28.353Z"  // To check expiration
}

// Check if payment request expired
function isExpired(expiresAt) {
  return new Date(expiresAt) < new Date();
}
 
// If expired, create new payment request
if (isExpired(payment.expiresAt)) {
  payment = await createNewPaymentRequest(order);
}

// Example verification workflow
async function verifyPayment(order, linkId) {
  // 1. Check your wallet for incoming transactions
  const wallet = await getWalletTransactions(YOUR_WALLET_ADDRESS);
  
  // 2. Find transaction matching:
  //    - Amount (within acceptable range due to fees)
  //    - Timestamp (around when customer claimed payment)
  const payment = wallet.transactions.find(tx => {
    const amountMatch = Math.abs(tx.amount - order.total_crypto) < 0.0001;
    const timeMatch = Math.abs(tx.timestamp - order.claimed_at) < 3600; // 1 hour
    return amountMatch && timeMatch;
  });
  
  // 3. Verify confirmations
  if (payment && payment.confirmations >= REQUIRED_CONFIRMATIONS) {
    // Payment verified!
    return { verified: true, txHash: payment.hash };
  }
  
  return { verified: false };
}

// Build complete redirect URL with all necessary info
const redirectUrl = new URL('https://mysite.com/payment-callback');
redirectUrl.searchParams.set('order_id', order.id);
redirectUrl.searchParams.set('session', session.id);
// Don't add payment status here - Suzaa will add it
 
const payment = await suzaa.createPaymentRequest({
  amount: order.total,
  description: `Order #${order.id}`,
  expiryTime: 60,
  redirectUrl: redirectUrl.toString()
});

// After customer claims payment
async function handlePaymentClaimed(order) {
  // Update order status
  order.status = 'pending_verification';
  await order.save();
  
  // Send confirmation email
  await sendEmail(order.customer.email, {
    subject: 'Payment Received - Awaiting Confirmation',
    body: `
      Thank you for your payment!
      
      We've received notification that you sent payment for Order #${order.id}.
      
      We're now verifying your transaction on the blockchain. This usually 
      takes a few minutes to a few hours depending on network conditions.
      
      Once verified, we'll send you a shipping confirmation.
      
      Payment Details:
      - Amount: ${order.total} USD
      - Suzaa Payment ID: ${order.suzaa_link_id}
    `
  });
}

// Set timeout for blockchain verification
setTimeout(async () => {
  const order = await getOrder(orderId);
  
  if (order.status === 'pending_verification') {
    // Still not verified after X hours
    await sendEmail(order.customer.email, {
      subject: 'Payment Verification Delayed',
      body: `
        We're still waiting to see your payment on the blockchain.
        
        Please ensure you:
        1. Sent the correct amount
        2. Sent to the correct address
        3. Paid the network fee
        
        If you need assistance, please reply to this email with your 
        transaction hash.
      `
    });
  }
}, 6 * 60 * 60 * 1000); // 6 hours

// Prevent duplicate payment requests for same order
async function getOrCreatePaymentRequest(order) {
  // Check if payment request already exists
  if (order.suzaa_link_id) {
    const existing = await suzaa.getPaymentRequest(order.suzaa_payment_request_id);
    
    // Reuse if not expired
    if (new Date(existing.expiresAt) > new Date()) {
      return existing;
    }
  }
  
  // Create new payment request
  const payment = await suzaa.createPaymentRequest({
    amount: order.total,
    description: `Order #${order.id}`,
    expiryTime: 60,
    redirectUrl: getRedirectUrl(order.id)
  });
  
  // Store with order
  order.suzaa_payment_request_id = payment.paymentRequestId;
  order.suzaa_link_id = payment.linkId;
  order.suzaa_payment_url = payment.paymentUrl;
  await order.save();
  
  return payment;
}

// When customer claims payment
{
  "event": "payment.claimed",
  "paymentRequestId": "fd74f812...",
  "linkId": "825757/20251213/0007",
  "timestamp": "2025-12-13T15:52:28.353Z"
}
 
// When payment request expires
{
  "event": "payment.expired",
  "paymentRequestId": "fd74f812...",
  "linkId": "825757/20251213/0007",
  "timestamp": "2025-12-13T16:52:28.353Z"
}

# Good: Environment variable
export SUZAA_API_KEY="sza_live_YOUR_KEY"
 
# Bad: Hardcoded
const apiKey = "sza_live_YOUR_KEY"; // DON'T DO THIS
 
# Good: Use in code
const apiKey = process.env.SUZAA_API_KEY;

// Validate amounts
function validateAmount(amount) {
  const num = parseFloat(amount);
  if (isNaN(num) || num <= 0 || num > 1000000) {
    throw new Error('Invalid amount');
  }
  return num.toFixed(2);
}
 
// Validate redirect URLs
function validateRedirectUrl(url) {
  try {
    const parsed = new URL(url);
    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
      throw new Error('Invalid protocol');
    }
    return url;
  } catch (e) {
    throw new Error('Invalid URL');
  }
}

// Track which payment links have been used
async function checkPaymentNotUsed(linkId) {
  const existingOrder = await Order.findOne({ suzaa_link_id: linkId });
  
  if (existingOrder && existingOrder.status !== 'cancelled') {
    throw new Error('Payment link already used');
  }
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702468800

async function createPaymentWithRateLimit(data) {
  try {
    return await suzaa.createPaymentRequest(data);
  } catch (error) {
    if (error.response?.status === 429) {
      const resetTime = error.response.headers['x-ratelimit-reset'];
      const waitTime = (resetTime * 1000) - Date.now();
      
      console.log(`Rate limited. Waiting ${waitTime}ms`);
      await sleep(waitTime);
      
      // Retry
      return await suzaa.createPaymentRequest(data);
    }
    throw error;
  }
}

const apiKey = process.env.NODE_ENV === 'production' 
  ? process.env.SUZAA_LIVE_KEY 
  : process.env.SUZAA_TEST_KEY;

describe('Suzaa Payment Integration', () => {
  it('should create payment request', async () => {
    const payment = await suzaa.createPaymentRequest({
      amount: '100.00',
      description: 'Test Order',
      expiryTime: 60
    });
    
    expect(payment).toHaveProperty('paymentUrl');
    expect(payment).toHaveProperty('linkId');
    expect(payment.paymentUrl).toContain('app.suzaa.com');
  });
  
  it('should handle expired payment', async () => {
    const payment = await suzaa.createPaymentRequest({
      amount: '50.00',
      description: 'Test',
      expiryTime: 1 // 1 minute
    });
    
    // Wait for expiration
    await sleep(65000); // 65 seconds
    
    const details = await suzaa.getPaymentRequest(payment.paymentRequestId);
    expect(details.status).toBe('expired');
  });
});

// Request Types
interface CreatePaymentRequest {
  amount: string | number;
  description: string;
  expiryTime: number;
  redirectUrl?: string;
}
 
// Response Types
interface PaymentRequestResponse {
  success: true;
  data: {
    success: true;
    paymentRequestId: string;
    linkId: string;
    paymentUrl: string;
    expiresAt: string;
    message: string;
  };
}
 
interface PaymentRequestDetails {
  paymentRequestId: string;
  linkId: string;
  amount: string;
  description: string;
  status: 'pending' | 'claimed_paid' | 'canceled' | 'expired';
  paymentUrl: string;
  redirectUrl: string | null;
  expiryTime: number;
  expiresAt: string;
  createdAt: string;
  claimedAt: string | null;
}
 
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    field?: string;
  };
}
 
// API Client
class SuzaaAPI {
  constructor(private apiKey: string, private baseUrl: string = 'https://api.suzaa.com') {}
  
  async createPaymentRequest(data: CreatePaymentRequest): Promise<PaymentRequestResponse['data']> {
    const response = await fetch(`${this.baseUrl}/payments/requests`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    if (!result.success) {
      throw new Error(result.error.message);
    }
    
    return result.data;
  }
  
  async getPaymentRequest(id: string): Promise<PaymentRequestDetails> {
    const response = await fetch(`${this.baseUrl}/payments/requests/${id}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`
      }
    });
    
    const result = await response.json();
    
    if (!result.success) {
      throw new Error(result.error.message);
    }
    
    return result.data;
  }
}