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 Settings > API Credentials
3. Generate or retrieve your:
- Site Key (public identifier)
- Security Token (private authentication)
- Webhook Secret (for signature validation)

#### 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:
- Using test API keys (pk_test_* and sk_test_*)
- 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

Title: Nexzoneo Payment Gateway
Description: Pay securely with credit card, debit card, or bank transfer
Site Key: [Your site key from merchant dashboard]
Security Token: [Your security token from merchant dashboard]
Webhook Secret: [Your webhook secret from merchant dashboard]
Test Mode: Enable for testing (uses test API keys)

#### 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 test API keys from merchant dashboard (pk_test_* / sk_test_*)
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

WooCommerce-Specific Features

#### 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

#### 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 Test API Keys:
- Public Key: pk_test_* (starts with pk_test_)
- Secret Key: sk_test_* (starts with sk_test_)

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

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

Important: Test mode is determined by:
- ✅ Test API keys (pk_test_* / sk_test_*)
- ✅ "Test Mode" enabled in merchant settings
- ❌ NOT by changing the API URL

#### 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 credentials for test/production (pk_test_* vs pk_live_*)
- ✅ 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._