Nexzoneo Payment System - Complete Developer Integration Guide

📋 Table of Contents

- Overview
- Integration Options
- API Integration Guide
- WooCommerce Plugin Guide
- Testing & Development
- Security Best Practices
- Support & Resources

---

🎯 Overview

Nexzoneo is a comprehensive payment processing platform with intelligent routing, advanced fraud protection, and comprehensive merchant tools.

Key Features

- ✅ Multi-Provider Support: Multiple integrated payment processors for maximum reliability
- ✅ Intelligent Routing: Automatic provider selection and failover
- ✅ Advanced Security: HMAC signature validation, fraud detection
- ✅ Comprehensive APIs: Full payment lifecycle management
- ✅ Real-time Webhooks: Instant payment status notifications
- ✅ Merchant Dashboard: Complete payment management interface
- ✅ WooCommerce Plugin: Seamless WordPress/WooCommerce integration

Supported Payment Methods

- Credit/Debit Cards (Visa, MasterCard, American Express, Discover)
- ACH/Bank Transfers
- Digital Wallets (Apple Pay, Google Pay)
- International Cards (multi-currency support)

---

🚀 Integration Options

Choose the integration method that best fits your platform:

1. 🔗 Direct API Integration

Best for: Custom applications, mobile apps, advanced integrations

- Full control over payment flow and UI
- Access to all advanced features
- Custom webhook handling
- Complete transaction management

2. 🛒 WooCommerce Plugin

Best for: WordPress/WooCommerce stores

- One-click installation
- Automatic order completion
- Built-in webhook handling
- No coding required

---

🔗 API Integration Guide

Getting Started

#### 1. Prerequisites

- Active Nexzoneo merchant account
- Server-side implementation capability
- SSL certificate for webhook endpoints
- Development environment for testing

#### 2. Obtain API Credentials

1. Log into your Nexzoneo merchant dashboard
2. Navigate to Sites and create or select a site
3. Copy your Site Key and Security Token

#### 3. Base Configuration

API Base URL: https://payment.nexzoneo.com/api/merchant/

Important: The URL remains the same for both test and production modes. Test mode is controlled by enabling "Test Mode" in your merchant account settings.

Authentication

All API requests require these headers:

X-Site-Key: your_site_key_here
Authorization: your_security_token_here
Content-Type: application/json

⚠️ Security Warning: Never expose credentials in client-side code. All API calls must be made from your server.

Core API Endpoints

#### 1. Create Payment Session

POST /api/merchant/create_payment_session

Request:

{
  "order_id": "ORDER-12345",
  "total": 29.99,
  "currency": "USD",
  "customer_email": "customer@example.com",
  "items": [
    {
      "name": "Product Name",
      "quantity": 1,
      "unit_price": 29.99
    }
  ],
  "return_url": "https://yoursite.com/payment/success",
  "cancel_url": "https://yoursite.com/payment/cancel",
  "callback_url": "https://yoursite.com/webhooks/nexzoneo"
}

Response:

{
  "status": "success",
  "data": {
    "success": true,
    "session_id": 12345,
    "session_token": "sess_abc123def456...",
    "payment_url": "https://payment.nexzoneo.com/session/sess_abc123def456...",
    "reused": false
  },
  "request_id": "req_abc123",
  "duration_ms": 45.2
}

Implementation Example (PHP):

<?php
function createPaymentSession($orderData) {
    $ch = curl_init('https://payment.nexzoneo.com/api/merchant/create_payment_session');

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'X-Site-Key: ' . YOUR_SITE_KEY,
            'Authorization: ' . YOUR_SECURITY_TOKEN,
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($orderData),
        CURLOPT_SSL_VERIFYPEER => true
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        $result = json_decode($response, true);
        // Redirect customer to $result['data']['payment_url']
        return $result;
    } else {
        // Handle error
        throw new Exception('Payment session creation failed');
    }
}
?>

#### 2. Get Payment Status

GET /api/merchant/get_session?token=sess_abc123def456

Response:

{
  "status": "success",
  "data": {
    "success": true,
    "session": {
      "id": 12345,
      "status": "completed",
      "amount": 29.99,
      "currency": "USD",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:32:15Z"
    }
  }
}

Status Values:

- created - Payment session created, awaiting customer
- processing - Customer is completing payment
- completed - Payment successful
- failed - Payment failed or declined
- expired - Session expired without payment
- cancelled - Payment cancelled by customer

#### 3. Create Refund

POST /api/merchant/create_refund

Request:

{
  "session_id": 12345,
  "amount": 15.0,
  "reason": "Customer requested partial refund"
}

Response:

{
  "status": "success",
  "data": {
    "success": true,
    "refund_id": 67890,
    "status": "succeeded",
    "amount": 15.0,
    "currency": "USD"
  }
}

#### 4. List Refunds

GET /api/merchant/list_refunds?session_id=12345

#### 5. Get Refund Status

GET /api/merchant/get_refund_status?refund_id=67890

🆕 Advanced Chargeback Management

#### 6. Create Chargeback Record

POST /api/merchant/create_chargeback

Request:

{
  "session_id": 12345,
  "amount": 29.99,
  "reason": "fraudulent",
  "dispute_reason": "Customer claims unauthorized transaction",
  "evidence_due_by": "2024-02-15",
  "admin_comment": "Investigating with customer service logs"
}

#### 7. Submit Chargeback Evidence

POST /api/merchant/submit_chargeback_evidence

Request:

{
  "chargeback_id": 789,
  "evidence": {
    "customer_communication": "Email thread showing customer satisfaction",
    "shipping_documentation": "Tracking number and delivery confirmation",
    "service_documentation": "Screenshots of service usage"
  }
}

#### 8. Get Chargeback History

GET /api/merchant/get_chargeback_history?session_id=12345

#### 9. Accept Chargeback

POST /api/merchant/accept_chargeback

Webhook Integration

#### Webhook Endpoint Setup

Your webhook endpoint should:

1. Accept POST requests
2. Validate HMAC signatures
3. Return HTTP 200 for successful processing
4. Handle idempotency (duplicate webhooks)

Example Webhook Handler (PHP):

<?php
function handleWebhook() {
    $payload = file_get_contents('php://input');
    $signature = $_SERVER['HTTP_X_NEXZONEO_SIGNATURE'] ?? '';

    // Validate signature
    $expectedSignature = hash_hmac('sha256', $payload, YOUR_WEBHOOK_SECRET);
    if (!hash_equals($signature, $expectedSignature)) {
        http_response_code(401);
        exit('Invalid signature');
    }

    $data = json_decode($payload, true);

    switch ($data['event_type']) {
        case 'payment.completed':
            handlePaymentCompleted($data);
            break;
        case 'payment.failed':
            handlePaymentFailed($data);
            break;
        case 'refund.completed':
            handleRefundCompleted($data);
            break;
        // Handle other event types
    }

    http_response_code(200);
    echo 'OK';
}

function handlePaymentCompleted($data) {
    $sessionId = $data['session_id'];
    $amount = $data['amount'];

    // Update your order status
    // Send confirmation emails
    // Update inventory
}
?>

#### Webhook Event Types

- payment.created - Payment session created
- payment.completed - Payment successful
- payment.failed - Payment failed or declined
- payment.expired - Payment session expired
- refund.created - Refund initiated
- refund.completed - Refund processed
- refund.failed - Refund failed
- chargeback.created - Chargeback received
- chargeback.won - Chargeback disputed successfully
- chargeback.lost - Chargeback lost

---

🛒 WooCommerce Plugin Guide

Installation

#### Method 1: WordPress Admin (Recommended)

1. Download the latest plugin from your merchant dashboard
2. Go to WordPress Admin > Plugins > Add New > Upload Plugin
3. Upload the .zip file and activate

#### Method 2: Manual Installation

1. Extract plugin files to /wp-content/plugins/woocommerce-gateway-nexzoneo/
2. Activate in WordPress Admin > Plugins

Configuration

#### 1. Basic Setup

1. Go to WooCommerce > Settings > Payments
2. Enable Nexzoneo Payment Gateway
3. Click Manage to configure

#### 2. Required Settings

Site Key: [Your site key from merchant dashboard]
Security Token: [Your security token from merchant dashboard]
Webhook Secret: [Your webhook secret from Sites page - click site name to view]
Test Mode: Enable for testing (uses test site credentials)

#### 3. Advanced Settings

Payment Page Style: Hosted (recommended) or Embedded
Auto-capture: Yes (immediate payment) or No (authorize only)
Debug Mode: Enable for troubleshooting (disable in production)
Order Status Mapping:
  - Successful Payment → Processing
  - Failed Payment → Failed
  - Cancelled Payment → Cancelled

Testing WooCommerce Integration

#### 1. Test Mode Setup

1. Enable "Test Mode" in WooCommerce plugin settings
2. Use site credentials from a test site in your merchant dashboard
3. Enable Debug Mode for detailed logging

#### 2. Test Scenarios

- ✅ Successful payment flow
- ✅ Failed/declined payment
- ✅ Customer cancellation
- ✅ Webhook delivery and order completion
- ✅ Refund processing from WooCommerce admin

#### 3. Debug Information

- Check WooCommerce > Status > Logs
- Look for "nexzoneo-gateway" log files
- Monitor webhook delivery in merchant dashboard

#### Automatic Order Management

- Orders automatically marked as "Processing" on successful payment
- Failed payments marked as "Failed" with customer notification
- Partial refunds supported from WooCommerce order admin
- Full transaction history visible in order notes

#### Customer Experience

- Seamless checkout integration
- Hosted payment page (secure, PCI-compliant)
- Automatic return to store after payment
- Order confirmation emails sent automatically

---

---

🧪 Testing & Development

Test Environment

#### 1. Test Mode Setup

To use test mode:

1. Enable Test Mode in your merchant account settings:
- Log in to: https://payment.nexzoneo.com/cp/
- Go to Settings → Account Settings
- Enable "Test Mode"

2. Use Site Credentials:
- Site Key: Starts with site_
- Security Token: Starts with sec_

3. API Base URL (same for test and production):

https://payment.nexzoneo.com/api/merchant/

Important: Test mode is determined by the "Test Mode" setting in your merchant account, not by the API credentials format.

#### Test Card Numbers

Visa Success:           4242424242424242
Visa Decline:           4000000000000002
Mastercard Success:     5555555555554444
Amex Success:           378282246310005
Insufficient Funds:     4000000000009995
Expired Card:           4000000000000069
CVC Failure:            4000000000000127

#### Test Scenarios

1. Successful Payment Flow
2. Declined Payment Handling
3. Webhook Delivery and Retry
4. Refund Processing
5. Chargeback Simulation
6. Multi-currency Transactions

Development Best Practices

#### Error Handling

try {
    $result = createPaymentSession($orderData);
    // Handle success
} catch (Exception $e) {
    // Log error details
    error_log('Payment creation failed: ' . $e->getMessage());

    // Show user-friendly error
    showErrorMessage('Payment processing is temporarily unavailable. Please try again.');
}

#### Logging and Monitoring

- Log all API requests and responses (excluding sensitive data)
- Monitor webhook delivery success rates
- Set up alerts for payment failures
- Track conversion rates and abandonment

#### Performance Optimization

- Cache payment session tokens appropriately
- Implement proper timeout handling
- Use asynchronous webhook processing
- Optimize database queries for payment data

---

🔒 Security Best Practices

API Security

#### Credential Management

- ✅ Store credentials in environment variables
- ✅ Never commit credentials to version control
- ✅ Use different sites for test/production
- ✅ Rotate credentials regularly

#### Request Security

- ✅ Always use HTTPS for API calls
- ✅ Validate SSL certificates
- ✅ Implement request timeouts
- ✅ Use proper error handling

#### Data Protection

- ✅ Never log sensitive payment data
- ✅ Implement PCI DSS compliance measures
- ✅ Use secure session management
- ✅ Encrypt sensitive data at rest

Webhook Security

#### Signature Validation

function validateWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($signature, $expectedSignature);
}

#### Additional Security Measures

- ✅ Validate webhook source IP addresses
- ✅ Implement idempotency checks
- ✅ Use HTTPS for webhook endpoints
- ✅ Set appropriate timeout values

---

📞 Support & Resources

Documentation

- API Reference: /api/merchant/docs/
- Webhook Guide: Available in merchant dashboard
- Integration Examples: GitHub repository (coming soon)

Support Channels

- Technical Support: https://support.nexzoneo.com
- Integration Help: it@nexzoneo.com
- Emergency Support: Available 24/7 for production issues

Developer Resources

- Postman Collection: Available for API testing
- SDK Libraries: PHP, Node.js, Python (in development)
- Code Examples: Available in multiple languages
- Webhook Testing Tool: Built into merchant dashboard

Status & Monitoring

- System Status: https://status.nexzoneo.com
- API Health: Real-time monitoring available
- Maintenance Windows: Announced 48 hours in advance
- Incident Reports: Detailed post-mortems published

---

📊 Advanced Features

Multi-Currency Support

- Support for 100+ currencies
- Real-time exchange rate conversion
- Automatic currency detection
- Settlement in merchant's preferred currency

Fraud Protection

- Machine learning-based fraud detection
- Customizable risk rules
- Real-time transaction scoring
- Automatic high-risk transaction blocking

Analytics & Reporting

- Real-time transaction monitoring
- Detailed payment analytics
- Conversion rate optimization tools
- Custom report generation

Enterprise Features

- Multi-merchant management
- Advanced user permissions
- Custom branding options
- Dedicated account management

---

_Last Updated: 2025-08-30_
_Version: 2.0_
_For the latest updates, visit your merchant dashboard or contact support._