VOLTXT Plugin API Documentation

Integrate external e-commerce platforms with VOLTXT payment system

Supported Platforms

WooCommerce
OpenCart
Shopify
PrestaShop
Magento
Custom

Base URL

Base URL 
https://api.voltxt.io/api/plugin

Authentication

All requests require a valid store API key passed in the request body.

Important: Keep your API key secure and never expose it in client-side code.

Create Invoice

Creates a new invoice for payment processing.

POST /invoice/create

Request Headers

Content-Type: application/json
Accept: application/json

Request Body

JSON 
{
  "api_key": "your_32_character_api_key",
  "platform": "woocommerce",
  "external_invoice_id": "order_12345",
  "amount_type": "fiat",
  "amount": 99.99,
  "fiat_currency": "USD",
  "expiry_hours": 24,
  "description": "Order #12345 - Premium Subscription",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "callback_url": "https://yourstore.com/webhook/voltxt",
  "success_url": "https://yourstore.com/payment/success",
  "cancel_url": "https://yourstore.com/payment/cancel",
  "metadata": {
    "order_id": 12345,
    "product_ids": [1, 2, 3],
    "custom_field": "value"
  }
}

Success Response

JSON Response 
{
  "success": true,
  "invoice_number": "ABCD1234",
  "payment_url": "https://app.voltxt.io/pay/ABCD1234",
  "deposit_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "sol_deposit_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "usdc_deposit_address": "9vZYk8p3H2m5Qr6Wt7L9Nx4Jd8Fg3Km1Bs5Vt6Ck3Hm",
  "amount_crypto": 0.666666667,
  "crypto_currency": "SOL"
}

Response Fields

Field Type Description
success boolean Whether the invoice was created successfully
invoice_number string Unique VOLTXT invoice number
payment_url string URL where customer can pay the invoice
deposit_address string Primary payment address (SOL)
sol_deposit_address string SOL payment address
usdc_deposit_address string USDC payment address
amount_crypto number Invoice amount in cryptocurrency
crypto_currency string Cryptocurrency type (e.g., "SOL")

Multi-Currency Support

Note: Invoices support payments in both SOL and USDC. Customers choose their preferred currency on the payment page.

Get Invoice Status

Retrieves the current status of an invoice.

GET /invoice/{invoiceNumber}/status

Webhook Types

VOLTXT supports two types of webhook notifications to accommodate different integration needs:

Invoice Webhooks

Per-invoice webhooks sent to the callback_url specified when creating each invoice.

  • Invoice-specific notifications
  • Perfect for plugin integrations
  • Custom callback URL per invoice
  • Includes invoice-specific metadata

Store Webhooks

Store-level webhooks configured in your store settings, sent for all invoices in that store.

  • Centralized notifications for all invoices
  • Configure once in store settings
  • Email notifications included
  • Advanced statistics and monitoring

Which Type Should I Use?

Use Invoice Webhooks when:
  • Building plugins for e-commerce platforms
  • Each invoice needs different callback handling
  • You want invoice-specific webhook URLs
  • You need the per-invoice metadata
Use Store Webhooks when:
  • Building a unified payment dashboard
  • You want centralized notification handling
  • You need email notifications for merchants
  • You want webhook reliability monitoring

Invoice Webhooks

Invoice webhooks are sent to the callback_url specified when creating each invoice. These are perfect for plugin integrations where each invoice may have different handling requirements.

Webhook Events

payment_received
Full payment received, processing automatically
partial_payment_received
Partial payment received (underpaid)
payment_completed
Payment fully processed and funds distributed
invoice_expired
Invoice expired without payment

Invoice Webhook Payload

JSON Payload 
{
  "event_type": "payment_completed",
  "invoice_number": "ABCD1234",
  "external_invoice_id": "order_12345",
  "platform": "woocommerce",
  "network": "devnet",
  "status": "auto_processed",
  "paid_currency": "USDC",
  "amount_crypto": 0.666666667,
  "amount_fiat": 99.99,
  "fiat_currency": "USD",
  "amount_received_crypto": 0.666666667,
  "initial_rent_sol": 0.00203928,
  "remaining_amount_crypto": 0,
  "payment_progress_percentage": 100.00,
  "payment_tx_id": "5j7...abc",
  "auto_process_tx_id": "2k8...def",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "explorer_urls": {
    "payment_tx": "https://explorer.solana.com/tx/5j7...abc?cluster=devnet",
    "auto_process_tx": "https://explorer.solana.com/tx/2k8...def?cluster=devnet",
    "deposit_address": "https://explorer.solana.com/address/EPj...v?cluster=devnet"
  },
  "timestamp": "2024-01-31T12:05:00.000Z",
  "signature": "sha256_hmac_signature"
}

Invoice Webhook Headers

Content-Type: application/json
User-Agent: VOLTXT-Webhook/1.0
X-VOLTXT-Event: payment_completed
X-VOLTXT-Invoice: ABCD1234
X-VOLTXT-Network: devnet

Key Webhook Fields

Field Type Description
paid_currency string Currency customer used for payment: "SOL" or "USDC"
status string Invoice status (e.g., "auto_processed", "paid", "underpaid")
amount_crypto number Total crypto amount received

Store Webhooks

Store webhooks provide centralized notifications for all invoices in a store. Configure once in your store settings and receive notifications for all payment events.

Configuration

Store webhooks are configured in your VOLTXT dashboard under Store Settings → Notifications. You can:

  • Set a single webhook URL for all store invoices
  • Choose which events trigger notifications
  • Monitor webhook reliability and statistics
  • Test your webhook endpoint directly
  • Enable email notifications alongside webhooks

Store Webhook Events

payment_received
Payment received and invoice marked as paid
payment_completed
Payment completed and auto-processed
partial_payment_received
Partial payment received (invoice underpaid)
payment_auto_processed
Payment automatically processed by smart contract
invoice_expired
Invoice expired without sufficient payment

Store Webhook Payload

JSON Payload 
{
  "event_type": "payment_received",
  "timestamp": "2024-01-31T12:05:00.000Z",
  "webhook_version": "1.0",
  "invoice": {
    "invoice_number": "ABCD1234",
    "external_invoice_id": "order_12345",
    "status": "paid",
    "network": "devnet",
    "platform": "woocommerce",
    "platform_display": "WooCommerce",
    "amount_crypto": 0.666666667,
    "amount_fiat": 99.99,
    "fiat_currency": "USD",
    "amount_received_crypto": 0.666666667,
    "remaining_amount_crypto": 0,
    "payment_progress_percentage": 100.00,
    "is_overpaid": false,
    "payment_breakdown": {
      "type": "pda_based",
      "customer_payment_sol": 0.666666667,
      "customer_payment_lamports": 666666667,
      "rent_sol": 0.00203928,
      "rent_lamports": 2039280,
      "total_sol": 0.668705947,
      "total_lamports": 668705947
    },
    "platform_fee_percentage": 1.0,
    "platform_fee_amount": 0.006666667,
    "customer_name": "John Doe",
    "customer_email": "customer@example.com",
    "description": "Order #12345 - Premium Subscription",
    "created_at": "2024-01-31T12:00:00.000Z",
    "updated_at": "2024-01-31T12:05:00.000Z",
    "expiry_date": "2024-02-01T12:00:00.000Z",
    "is_expired": false,
    "deposit_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payment_tx_id": "5j7...abc",
    "auto_process_tx_id": "2k8...def",
    "explorer_urls": {
      "payment_tx": "https://explorer.solana.com/tx/5j7...abc?cluster=devnet",
      "auto_process_tx": "https://explorer.solana.com/tx/2k8...def?cluster=devnet",
      "deposit_address": "https://explorer.solana.com/address/EPj...v?cluster=devnet"
    }
  },
  "store": {
    "id": 123,
    "name": "My Online Store",
    "network": "devnet",
    "website_url": "https://mystore.com",
    "support_email": "support@mystore.com"
  },
  "merchant": {
    "id": 456,
    "name": "John Smith",
    "email": "john@mystore.com"
  },
  "network_info": {
    "network": "devnet",
    "cluster_param": "devnet",
    "explorer_base_url": "https://explorer.solana.com"
  },
  "metadata": {
    "order_id": 12345,
    "product_ids": [1, 2, 3]
  }
}

Store Webhook Headers

Content-Type: application/json
User-Agent: VOLTXT-Store-Webhook/1.0
X-VOLTXT-Event: payment_received
X-VOLTXT-Invoice: ABCD1234
X-VOLTXT-Store: 123
X-VOLTXT-Network: devnet
X-VOLTXT-Signature: sha256_hmac_signature

Payment Breakdown Details

Store webhooks include detailed payment breakdown information, especially important for PDA-based payments:

{
  "payment_breakdown": {
    "type": "pda_based",
    "customer_payment_sol": 0.666666667,
    "customer_payment_lamports": 666666667,
    "rent_sol": 0.00203928,
    "rent_lamports": 2039280,
    "total_sol": 0.668705947,
    "total_lamports": 668705947
  }
}
  • customer_payment_sol/lamports: The actual payment from the customer (excluding Solana rent)
  • rent_sol/lamports: The Solana account rent that was automatically deducted
  • total_sol/lamports: The total PDA balance (customer payment + rent)
  • type: Either "pda_based" or "direct_wallet" depending on payment method

Email Notifications

When store webhooks are configured, merchants also receive professional email notifications for payment events. These emails include:

  • Payment summary with amounts and progress
  • Invoice details and customer information
  • Blockchain explorer links for transactions
  • Payment breakdown showing customer payment vs rent
  • Mobile-responsive design with your branding

Webhook Security

All VOLTXT webhooks include HMAC-SHA256 signatures for verification to ensure the authenticity of webhook requests.

Invoice Webhook Signatures

Invoice webhooks use the following signing method:

  1. Concatenate: invoice_number + external_invoice_id + event_type + status + network
  2. Generate HMAC-SHA256 using your application's secret key
  3. Compare with the provided signature in the signature field
PHP Example - Invoice Webhook Verification 
function verifyInvoiceWebhook($payload, $signature, $secret) {
    $expectedPayload = $payload['invoice_number'] . 
                      $payload['external_invoice_id'] . 
                      $payload['event_type'] . 
                      $payload['status'] .
                      $payload['network'];
    
    $expectedSignature = hash_hmac('sha256', $expectedPayload, $secret);
    
    return hash_equals($expectedSignature, $signature);
}

Store Webhook Signatures

Store webhooks use your store's API key as the signing secret:

  1. Get the complete JSON payload as a string
  2. Generate HMAC-SHA256 using your store's API key
  3. Compare with the signature in the X-VOLTXT-Signature header
PHP Example - Store Webhook Verification 
function verifyStoreWebhook($payloadJson, $signature, $storeApiKey) {
    $expectedSignature = hash_hmac('sha256', $payloadJson, $storeApiKey);
    
    return hash_equals($expectedSignature, $signature);
}

// Usage:
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_VOLTXT_SIGNATURE'] ?? '';
$storeApiKey = 'your_store_api_key';

if (verifyStoreWebhook($payload, $signature, $storeApiKey)) {
    $data = json_decode($payload, true);
    // Process webhook safely
} else {
    http_response_code(401);
    exit('Invalid signature');
}

Best Practices

Always verify signatures

Never process webhook data without verifying the HMAC signature first.

Implement idempotency

Use the invoice_number or a combination of invoice_number + event_type to prevent duplicate processing.

Use HTTPS endpoints

Always use HTTPS URLs for webhook endpoints to protect data in transit.

Respond quickly

Return a 200 status code within 30 seconds. For longer processing, return 200 immediately and process asynchronously.

Retry Mechanism

VOLTXT automatically retries failed webhook deliveries with exponential backoff:

  • Retry intervals: 10 seconds, 30 seconds, 60 seconds
  • Success criteria: HTTP status codes 200-299
  • Failure criteria: Timeouts (30s), HTTP 4xx/5xx errors, connection failures
  • Maximum attempts: 3 retries per webhook

Webhook Monitoring

Store webhooks include built-in monitoring and statistics:

  • Success/failure rates and reliability percentages
  • Response time tracking
  • Last success/failure timestamps
  • Health status indicators
  • Manual webhook testing from the dashboard

Invoice Status Flow

pending
Invoice created, awaiting payment
↓
underpaid
Partial payment received
↓
Full payment received, auto-processing in progress
↓
auto_processed
Payment completed, funds distributed
expired
Invoice expired without sufficient payment

Rate Limits

Create Invoice
100 requests/minute
Get Status
200 requests/minute
Webhooks
50 requests/minute
Store Notifications
60 requests/minute

Error Codes

Code Description
INVALID_API_KEY The provided API key is invalid
NO_DESTINATION_WALLET Store doesn't have a destination wallet configured
DUPLICATE_EXTERNAL_ID External invoice ID already exists for this store
VALIDATION_ERROR Request validation failed
INVOICE_NOT_FOUND Invoice with given number not found
INTERNAL_ERROR Server error occurred
VAULT_INITIALIZATION_FAILED Failed to create on-chain payment address
WEBHOOK_NOT_CONFIGURED Store webhook settings not configured
EMAIL_NOT_ENABLED Email notifications not enabled for store

WooCommerce Integration Example

Example implementation for integrating VOLTXT with WooCommerce, including both invoice and store webhook handling.

Creating an Invoice

PHP - WooCommerce Order Creation 
// Create invoice when order is placed
$response = wp_remote_post('https://api.voltxt.io/api/plugin/invoice/create', [
    'headers' => ['Content-Type' => 'application/json'],
    'body' => json_encode([
        'api_key' => get_option('voltxt_api_key'),
        'platform' => 'woocommerce',
        'external_invoice_id' => 'order_' . $order->get_id(),
        'amount_type' => 'fiat',
        'amount' => $order->get_total(),
        'fiat_currency' => $order->get_currency(),
        'customer_email' => $order->get_billing_email(),
        'customer_name' => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
        'callback_url' => home_url('/wp-json/voltxt/v1/webhook'),
        'success_url' => $order->get_checkout_order_received_url(),
        'cancel_url' => wc_get_checkout_url(),
        'metadata' => [
            'order_id' => $order->get_id(),
            'customer_id' => $order->get_customer_id()
        ]
    ])
]);

Handling Invoice Webhooks

PHP - WooCommerce Invoice Webhook Handler 
// Handle invoice webhook
function handle_voltxt_invoice_webhook(WP_REST_Request $request) {
    $payload = $request->get_json_params();
    
    // Verify signature for security
    $signature = $request->get_header('signature') ?? $payload['signature'];
    if (!verify_invoice_webhook($payload, $signature, get_option('voltxt_secret'))) {
        return new WP_Error('invalid_signature', 'Invalid webhook signature', ['status' => 401]);
    }
    
    $external_id = $payload['external_invoice_id'];
    $order_id = str_replace('order_', '', $external_id);
    $order = wc_get_order($order_id);
    
    if (!$order) {
        return new WP_Error('order_not_found', 'Order not found', ['status' => 404]);
    }
    
    switch ($payload['event_type']) {
        case 'payment_received':
            $order->update_status('processing', 'VOLTXT payment received');
            break;
            
        case 'payment_completed':
            $order->update_status('completed', 'VOLTXT payment completed');
            break;
            
        case 'partial_payment_received':
            $order->add_order_note('Partial payment received via VOLTXT');
            break;
            
        case 'invoice_expired':
            $order->update_status('failed', 'VOLTXT payment expired');
            break;
    }
    
    return ['status' => 'success'];
}

Store Webhook Benefits

In addition to invoice webhooks, store webhooks provide additional benefits for WooCommerce stores:

  • Centralized monitoring: View all payment notifications in one place
  • Email alerts: Store owners receive email notifications for all payments
  • Analytics: Track webhook reliability and payment patterns
  • Backup notifications: Redundant notification system for critical payments

Support

For integration support, please contact:

Email

support@voltxt.com

Documentation

docs.voltxt.com