Guida all'Integrazione ZoneCoin — SDK di Pagamento Universale | ZoneCoin

ZoneNations

Integra ZoneCoin Ovunque

Un unico SDK JavaScript universale per accettare pagamenti ZoneCoin su qualsiasi sito web, CMS o marketplace. Copia, incolla, fatto.

🔵 WordPress

🟣 WooCommerce

🟠 Magento 2

🟢 Shopify

🔴 PrestaShop

🟡 VirtueMart

🔶 HikaShop

🟤 J2Store

🩵 PhocaCart

🌐 Qualsiasi Sito Web

⚡ Avvio Rapido

Attiva i pagamenti ZoneCoin in tre semplici passaggi — nessun codice lato server richiesto.

1

Ottieni la Chiave API

Registrati come commerciante e genera la tua chiave API dalla dashboard ZoneCoin.

2

Aggiungi l'SDK

Includi lo script dell'SDK ZoneCoin nel tuo sito web — una sola riga di HTML.

3

Accetta Pagamenti

Inizializza l'SDK e inizia ad accettare pagamenti ZoneCoin all'istante.

📦 SDK Universale

L'SDK ZoneCoin funziona su qualsiasi sito web indipendentemente dalla tecnologia sottostante. Includi lo script, inizializza con le tue credenziali e crea moduli o pulsanti di pagamento.

1. Carica l'SDK

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

2. Inizializza

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. Crea un Pagamento

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. Pulsante di Pagamento

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. Eventi

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

Accoda l'SDK nel tuo tema e, opzionalmente, crea un gateway di pagamento WooCommerce per l'integrazione completa del carrello.

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

Aggiungi lo script dell'SDK tramite layout XML e crea un modulo renderer di pagamento RequireJS personalizzato.

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

Usa i template Liquid e le estensioni checkout di Shopify per integrare i pagamenti ZoneCoin.

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

Crea un modulo di pagamento PrestaShop con il punto di integrazione hookPaymentOptions.

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

Crea un plugin di pagamento VirtueMart (vmpayment) che carica l'SDK ZoneCoin ed elabora i pagamenti al 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

Costruisci un plugin di pagamento HikaShop che integra ZoneCoin con l'evento onAfterOrderConfirm e le notifiche webhook.

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

Sviluppa un plugin di pagamento J2Store utilizzando l'hook _prePayment per integrare il flusso di checkout ZoneCoin.

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

Crea un plugin di pagamento PhocaCart che si aggancia a onPCPafterCheckoutConfirm per pagamenti ZoneCoin senza interruzioni.

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 Endpoint

Tutte le chiamate dell'SDK comunicano con l'API REST. Puoi anche chiamare questi endpoint direttamente da qualsiasi linguaggio lato server.

Autenticazione

HTTP

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

GET/rateTasso di cambio ZoneCoin attuale

GET/balance/{wallet}Saldo del wallet

POST/payCrea una richiesta di pagamento

POST/transferTrasferimento tra wallet

GET/tx/{id}Dettagli della transazione

POST/webhook/registerRegistra un URL webhook

GET/tokenomicsOfferta di token e dati di mercato

GET/nft/{id}Metadati e proprietà NFT

Payload del Webhook

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"
}

🛡️ Sicurezza

🔐

HMAC-SHA256

Ogni richiesta è firmata con HMAC-SHA256 per prevenire manomissioni.

⏱️

Nonce + Timestamp

Protezione da replay con nonce univoco e finestra temporale di 5 minuti.

🚦

Limitazione delle Richieste

Algoritmo token-bucket: 60 richieste/min per chiave API, burst fino a 120.

📦 Plugin Pronti all'Uso

Scarica i plugin di pagamento preconfezionati per le piattaforme e-commerce più popolari. Installa, configura le tue chiavi API e accetta ZoneCoin immediatamente.

📋

WooCommerce

WordPress 6+ / WooCommerce 8+

⬇ Download

📋

PrestaShop

PrestaShop 8+

⬇ Download

📋

VirtueMart

Joomla 6+ / VirtueMart 4+

⬇ Download

📋

HikaShop

Joomla 6+ / HikaShop 5+

⬇ Download

📋

J2Store

Joomla 6+ / J2Store 4+

⬇ Download

📋

PhocaCart

Joomla 6+ / PhocaCart 4+

⬇ Download

📋

Magento 2

Magento 2.4+

⬇ Download

📋

Shopify

Shopify / Custom Storefront

⬇ Download

🎮 SDK Piattaforme & Metaverso

SDK pronti all'uso per motori di gioco, mondi virtuali e piattaforme metaverso. Inserisci nel tuo progetto e inizia subito ad accettare pagamenti ZoneCoin.

🎮

OpenSimulator

OpenSim 0.9.2+ / .NET 6+

⬇ Download SDK

🎮

Second Life

Second Life LSL

⬇ Download SDK

🎮

Unity

Unity 2021.3+ / .NET Std 2.1

⬇ Download SDK