Guide d'Intégration ZoneCoin — SDK de Paiement Universel | ZoneCoin

ZoneNations

Intégrez ZoneCoin Partout

Un SDK JavaScript universel pour accepter les paiements ZoneCoin sur n'importe quel site web, CMS ou marketplace. Copiez, collez, c'est fait.

🔵 WordPress

🟣 WooCommerce

🟠 Magento 2

🟢 Shopify

🔴 PrestaShop

🟡 VirtueMart

🔶 HikaShop

🟤 J2Store

🩵 PhocaCart

🌐 N'importe Quel Site Web

⚡ Démarrage Rapide

Mettez en place les paiements ZoneCoin en trois étapes simples — aucun code côté serveur requis.

1

Obtenir la Clé API

Inscrivez-vous en tant que marchand et générez votre clé API depuis le tableau de bord ZoneCoin.

2

Ajouter le SDK

Incluez le script du SDK ZoneCoin sur votre site web — une seule ligne de HTML.

3

Accepter les Paiements

Initialisez le SDK et commencez à accepter les paiements ZoneCoin instantanément.

📦 SDK Universel

Le SDK ZoneCoin fonctionne sur n'importe quel site web quelle que soit la technologie sous-jacente. Incluez le script, initialisez avec vos identifiants et créez des formulaires ou boutons de paiement.

1. Charger le SDK

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

2. Initialiser

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. Créer un Paiement

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. Bouton de Paiement

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. Événements

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

Chargez le SDK dans votre thème et créez éventuellement une passerelle de paiement WooCommerce pour une intégration complète du panier.

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

Ajoutez le script du SDK via le layout XML et créez un module de rendu de paiement RequireJS personnalisé.

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

Utilisez les modèles Liquid et les extensions de checkout Shopify pour intégrer les paiements 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

Créez un module de paiement PrestaShop avec le point d'intégration 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

Créez un plugin de paiement VirtueMart (vmpayment) qui charge le SDK ZoneCoin et traite les paiements lors du 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

Construisez un plugin de paiement HikaShop qui intègre ZoneCoin avec l'événement onAfterOrderConfirm et les notifications 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

Développez un plugin de paiement J2Store en utilisant le hook _prePayment pour intégrer le flux de 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

Créez un plugin de paiement PhocaCart qui se connecte à onPCPafterCheckoutConfirm pour des paiements ZoneCoin transparents.

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 Points d'Accès

Tous les appels du SDK communiquent avec l'API REST. Vous pouvez également appeler ces points d'accès directement depuis n'importe quel langage côté serveur.

Authentification

HTTP

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

GET/rateTaux de change ZoneCoin actuel

GET/balance/{wallet}Solde du wallet

POST/payCréer une demande de paiement

POST/transferTransfert de wallet à wallet

GET/tx/{id}Détails de la transaction

POST/webhook/registerEnregistrer une URL de webhook

GET/tokenomicsOffre de tokens et données de marché

GET/nft/{id}Métadonnées et propriété des NFT

Charge utile du 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"
}

🛡️ Sécurité

🔐

HMAC-SHA256

Chaque requête est signée avec HMAC-SHA256 pour empêcher toute falsification.

⏱️

Nonce + Horodatage

Protection contre les rejeux avec nonce unique et fenêtre d'horodatage de 5 minutes.

🚦

Limitation du Débit

Algorithme token-bucket : 60 requêtes/min par clé API, rafale jusqu'à 120.

📦 Plugins Prêts à l'Emploi

Téléchargez des plugins de paiement préconstruits pour les plateformes e-commerce les plus populaires. Installez, configurez vos clés API et acceptez ZoneCoin immédiatement.

📋

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

🎮 SDKs Plateformes & Métavers

SDKs prêts à l'emploi pour moteurs de jeu, mondes virtuels et plateformes métavers. Intégrez dans votre projet et acceptez les paiements ZoneCoin immédiatement.

🎮

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