ZoneCoin Integration Guide — Universal Payment SDK | ZoneCoin

ZoneNations

Integrate ZoneCoin Everywhere

One universal JavaScript SDK to accept ZoneCoin payments on any website, CMS, or marketplace. Copy, paste, done.

🔵 WordPress

🟣 WooCommerce

🟠 Magento 2

🟢 Shopify

🔴 PrestaShop

🟡 VirtueMart

🔶 HikaShop

🟤 J2Store

🩵 PhocaCart

🌐 Any Website

⚡ Quick Start

Get ZoneCoin payments running in three simple steps — no server-side code required.

1

Get API Key

Register as a merchant and generate your API key from the ZoneCoin dashboard.

2

Add SDK

Include the ZoneCoin SDK script on your website — one line of HTML.

3

Accept Payments

Initialize the SDK and start accepting ZoneCoin payments instantly.

📦 Universal SDK

The ZoneCoin SDK works on any website regardless of the underlying technology. Include the script, initialize with your credentials, and create payment forms or buttons.

1. Load the SDK

HTML<script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>

2. Initialize

JavaScript

ZoneCoinSDK.init({
    apiUrl:   'https://zonecoin.zonenations.com/api/index.php/v1/zonecoin',
    apiKey:   'YOUR_PUBLIC_API_KEY',
    merchant: 'your-merchant-id',
    currency: 'EUR',
    theme:    'dark',
    sandbox:  true
});

3. Create a Payment

JavaScript

ZoneCoinSDK.pay({
    amount:      100,
    description: 'Premium subscription',
    ref:         'order_12345',
    isFiat:      true,
    callback:    'https://your-site.com/webhook/zonecoin'
}).then(result => {
    console.log('Payment TX:', result.txId);
});

4. Pay Button

HTML + JS

<div id="zc-pay-btn"></div>
<script>
ZoneCoinSDK.createPayButton('#zc-pay-btn', {
    amount: 49.99,
    description: 'Digital artwork',
    label: 'Pay with ZoneCoin ⚡'
});
</script>

5. Events

JavaScript

ZoneCoinSDK.on('success', (data) => {
    // { txId, amount, ref, amountFiat, rate }
    window.location.href = '/thank-you?tx=' + data.txId;
});
ZoneCoinSDK.on('error', (err) => alert(err.message));
ZoneCoinSDK.on('cancel', () => console.log('Cancelled'));

🔵 WordPress / WooCommerce

Enqueue the SDK in your theme and optionally create a WooCommerce payment gateway for full cart integration.

functions.php

PHP

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('zonecoin-sdk',
        'https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js',
        [], '1.0.0', true
    );
    wp_add_inline_script('zonecoin-sdk', "
        ZoneCoinSDK.init({
            apiUrl:   '" . esc_js(get_option('zc_api_url'))  . "',
            apiKey:   '" . esc_js(get_option('zc_api_key'))  . "',
            merchant: '" . esc_js(get_option('zc_merchant')) . "',
            currency: 'EUR', sandbox: false
        });
    ");
});

WooCommerce Gateway

PHP

class WC_ZoneCoin_Gateway extends WC_Payment_Gateway {
    public function __construct() {
        $this->id          = 'zonecoin';
        $this->method_title = 'ZoneCoin';
        $this->has_fields   = false;
        $this->init_form_fields();
        $this->init_settings();
    }
    public function process_payment($order_id) {
        $order = wc_get_order($order_id);
        return ['result' => 'success',
                'redirect' => $order->get_checkout_payment_url(true)];
    }
}

🟠 Magento 2

Add the SDK script via layout XML and create a custom RequireJS payment renderer module.

checkout_index_index.xml

XML

<head>
    <script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js" src_type="url" />
</head>

view/frontend/web/js/view/payment/method-renderer/zonecoin.js

JavaScript

define(['ZoneCoinSDK', 'Magento_Checkout/js/model/quote'],
function(ZC, quote) {
    return Component.extend({
        placeOrder: function() {
            ZoneCoinSDK.pay({
                amount: quote.totals().grand_total,
                ref:    quote.getQuoteId(),
                isFiat: true
            }).then(r => this.afterPlaceOrder(r));
        }
    });
});

🟢 Shopify

Use Liquid templates and Shopify checkout extensions to embed ZoneCoin payments.

Liquid + JS

<script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>
<script>
ZoneCoinSDK.init({
    apiUrl:   'https://your-joomla.com/api/index.php/v1/zonecoin',
    apiKey:   '{{ settings.zc_api_key }}',
    merchant: '{{ settings.zc_merchant }}',
    currency: '{{ shop.currency }}'
});
ZoneCoinSDK.createPayButton('#zc-pay', {
    amount: {{ checkout.total_price | money_without_currency }},
    ref:    '{{ checkout.order_id }}'
});
</script>
<div id="zc-pay"></div>

🔴 PrestaShop

Create a PrestaShop payment module with the hookPaymentOptions integration point.

PHP (Module)

class ZoneCoinPayment extends PaymentModule {
    public function hookPaymentOptions($params) {
        $option = new PaymentOption();
        $option->setModuleName($this->name)
               ->setCallToActionText('Pay with ZoneCoin ⚡')
               ->setAdditionalInformation(
                   '<div id="zc-presta-pay"></div>
                    <script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>'
               );
        return [$option];
    }
}

🟡 VirtueMart

Create a VirtueMart payment plugin (vmpayment) that loads the ZoneCoin SDK and processes payments at checkout.

Plugin: vmpayment_zonecoin.php

PHP

class plgVmPaymentZonecoin extends vmPSPlugin {

    public function __construct(&$subject, $config) {
        parent::__construct($subject, $config);
        $this->_loggable   = true;
        $this->tableFields = array_keys($this->getTableSQLFields());
    }

    function plgVmConfirmedOrder($cart, $order) {
        $method = $this->getVmPluginMethod($order['details']['BT']->virtuemart_paymentmethod_id);
        if (!$method) return null;

        $doc = \Joomla\CMS\Factory::getApplication()->getDocument();
        $doc->addScript('https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js');
        $doc->addScriptDeclaration("
            ZoneCoinSDK.init({
                apiUrl:   '" . $method->zc_api_url   . "',
                apiKey:   '" . $method->zc_api_key   . "',
                merchant: '" . $method->zc_merchant   . "',
                currency: '" . $method->payment_currency . "'
            });
            ZoneCoinSDK.pay({
                amount: " . $order['details']['BT']->order_total . ",
                ref:    'VM-" . $order['details']['BT']->order_number . "',
                isFiat: true
            }).then(data => { window.location.href = 'index.php?option=com_virtuemart&view=pluginresponse&task=pluginResponseReceived&pm=" . $order['details']['BT']->virtuemart_paymentmethod_id . "'; });
        ");
    }

    function plgVmOnPaymentResponseReceived(&$html) {
        // Verify webhook callback, update order status
        return true;
    }
}

🔶 HikaShop

Build a HikaShop payment plugin that integrates ZoneCoin with the onAfterOrderConfirm event and webhook notifications.

Plugin: hikashoppayment_zonecoin.php

PHP

class plgHikashoppaymentZonecoin extends hikashopPaymentPlugin {

    var $accepted_currencies = array('EUR','USD','GBP','CHF');
    var $multiple  = true;
    var $name      = 'zonecoin';

    function onAfterOrderConfirm(&$order, &$methods, $method_id) {
        parent::onAfterOrderConfirm($order, $methods, $method_id);
        $method = $this->getPaymentMethod($method_id);
        if (!$method) return false;

        $amount   = round($order->order_full_price, 2);
        $orderRef = $order->order_number;
        $apiUrl   = $method->payment_params->zc_api_url;
        $apiKey   = $method->payment_params->zc_api_key;
        $merchant = $method->payment_params->zc_merchant;

        $html = '<div id="zc-hika-pay"></div>
        <script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>
        <script>
            ZoneCoinSDK.init({ apiUrl:"' . $apiUrl . '", apiKey:"' . $apiKey . '", merchant:"' . $merchant . '" });
            ZoneCoinSDK.createPayButton("#zc-hika-pay", { amount:' . $amount . ', ref:"HIKA-' . $orderRef . '", isFiat:true });
        </script>';

        $this->showPage('end', $html);
        return true;
    }

    function onPaymentNotification(&$statuses) {
        // Webhook handler: verify HMAC, update order status
        $this->modifyOrder($order_id, 'confirmed');
        return true;
    }
}

🟤 J2Store

Develop a J2Store payment plugin using the _prePayment hook to embed the ZoneCoin SDK checkout flow.

Plugin: j2store_payment_zonecoin.php

PHP

class plgJ2StorePayment_zonecoin extends J2StorePaymentPlugin {

    var $_element = 'payment_zonecoin';

    function _prePayment($data) {
        $vars   = new \stdClass();
        $order  = F0FTable::getAnInstance('Order', 'J2StoreTable');
        $order->load(array('order_id' => $data['order_id']));

        $vars->order_id = $data['order_id'];
        $vars->amount   = $order->order_total;
        $vars->currency = $order->currency_code;

        $html = '<div id="zc-j2-pay"></div>
        <script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>
        <script>
            ZoneCoinSDK.init({
                apiUrl:   "' . $this->params->get('zc_api_url') . '",
                apiKey:   "' . $this->params->get('zc_api_key') . '",
                merchant: "' . $this->params->get('zc_merchant') . '"
            });
            ZoneCoinSDK.pay({
                amount: ' . $vars->amount . ',
                ref:    "J2-' . $vars->order_id . '",
                isFiat: true
            }).then(data => {
                window.location.href = "index.php?option=com_j2store&view=checkout&task=confirmPayment&orderpayment_type=payment_zonecoin&paction=process";
            });
        </script>';

        return $html;
    }

    function _postPayment($data) {
        // Verify webhook + update order to "Confirmed"
        $order  = F0FTable::getAnInstance('Order', 'J2StoreTable');
        $order->load(array('order_id' => $data['order_id']));
        $order->order_state_id = 1; // Confirmed
        $order->store();
    }
}

🩵 PhocaCart

Create a PhocaCart payment plugin that hooks into onPCPafterCheckoutConfirm for seamless ZoneCoin payments.

Plugin: phocacartpayment_zonecoin.php

PHP

class plgPhocacartpaymentZonecoin extends \JPlugin {

    public function onPCPafterCheckoutConfirm($order, $params) {
        $amount   = $order->total->brutto;
        $orderId  = $order->id;
        $apiUrl   = $this->params->get('zc_api_url');
        $apiKey   = $this->params->get('zc_api_key');
        $merchant = $this->params->get('zc_merchant');

        $html = '<div id="zc-phoca-pay"></div>
        <script src="https://zonecoin.zonenations.com/media/com_zonecoin/js/zonecoin-sdk.js"></script>
        <script>
            ZoneCoinSDK.init({ apiUrl:"' . $apiUrl . '", apiKey:"' . $apiKey . '", merchant:"' . $merchant . '" });
            ZoneCoinSDK.createPayButton("#zc-phoca-pay", {
                amount: ' . $amount . ',
                ref:    "PHOCA-' . $orderId . '",
                isFiat: true
            });
        </script>';

        return $html;
    }

    public function onPCPafterPaymentNotification($order, $params) {
        // Verify HMAC webhook signature, mark order paid
        $order->status_id = 1; // Confirmed
        return true;
    }
}

🔌 REST API Endpoints

All SDK calls communicate with the REST API. You can also call these endpoints directly from any server-side language.

Authentication

HTTP

Authorization: Bearer YOUR_API_KEY
X-ZoneCoin-Timestamp: 1719500000
X-ZoneCoin-Nonce: a1b2c3d4e5f6
X-ZoneCoin-Signature: HMAC-SHA256(timestamp+nonce+body, secret)

GET/rateCurrent ZoneCoin exchange rate

GET/balance/{wallet}Wallet balance

POST/payCreate a payment request

POST/transferWallet-to-wallet transfer

GET/tx/{id}Transaction details

POST/webhook/registerRegister a webhook URL

GET/tokenomicsToken supply and market data

GET/nft/{id}NFT metadata and ownership

Webhook Payload

JSON

{
    "event":        "payment.completed",
    "txId":         "zc_tx_a1b2c3d4e5",
    "amount":       100.00,
    "currency":     "ZC",
    "amountFiat":   35.50,
    "fiatCurrency": "EUR",
    "ref":          "order_12345",
    "merchant":     "your-merchant-id",
    "timestamp":    1719500123,
    "signature":    "hmac_sha256_of_payload"
}