Guía de Integración ZoneCoin — SDK de Pago Universal | ZoneCoin

ZoneNations

Integra ZoneCoin En Todas Partes

Un SDK JavaScript universal para aceptar pagos ZoneCoin en cualquier sitio web, CMS o marketplace. Copia, pega, listo.

🔵 WordPress

🟣 WooCommerce

🟠 Magento 2

🟢 Shopify

🔴 PrestaShop

🟡 VirtueMart

🔶 HikaShop

🟤 J2Store

🩵 PhocaCart

🌐 Cualquier Sitio Web

⚡ Inicio Rápido

Pon en marcha los pagos ZoneCoin en tres simples pasos — sin código del lado del servidor.

1

Obtener Clave API

Regístrate como comerciante y genera tu clave API desde el panel de ZoneCoin.

2

Agregar SDK

Incluye el script del SDK ZoneCoin en tu sitio web — una sola línea de HTML.

3

Aceptar Pagos

Inicializa el SDK y comienza a aceptar pagos ZoneCoin al instante.

📦 SDK Universal

El SDK de ZoneCoin funciona en cualquier sitio web independientemente de la tecnología subyacente. Incluye el script, inicializa con tus credenciales y crea formularios o botones de pago.

1. Cargar el SDK

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

2. Inicializar

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. Crear un Pago

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. Botón de Pago

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

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

Encola el SDK en tu tema y, opcionalmente, crea una pasarela de pago WooCommerce para la integración completa del carrito.

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

Agrega el script del SDK mediante layout XML y crea un módulo de renderizado de pagos RequireJS personalizado.

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 plantillas Liquid y extensiones de checkout de Shopify para integrar los pagos 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 módulo de pago PrestaShop con el punto de integración 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 de pago VirtueMart (vmpayment) que carga el SDK ZoneCoin y procesa pagos en el 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

Construye un plugin de pago HikaShop que integra ZoneCoin con el evento onAfterOrderConfirm y notificaciones 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

Desarrolla un plugin de pago J2Store usando el hook _prePayment para integrar el flujo 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

Crea un plugin de pago PhocaCart que se conecta a onPCPafterCheckoutConfirm para pagos ZoneCoin sin interrupciones.

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

Todas las llamadas del SDK se comunican con la API REST. También puedes llamar a estos endpoints directamente desde cualquier lenguaje del lado del servidor.

Autenticación

HTTP

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

GET/rateTasa de cambio actual de ZoneCoin

GET/balance/{wallet}Saldo del wallet

POST/payCrear una solicitud de pago

POST/transferTransferencia entre wallets

GET/tx/{id}Detalles de la transacción

POST/webhook/registerRegistrar una URL de webhook

GET/tokenomicsSuministro de tokens y datos de mercado

GET/nft/{id}Metadatos y propiedad de 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"
}

🛡️ Seguridad

🔐

HMAC-SHA256

Cada solicitud se firma con HMAC-SHA256 para prevenir manipulaciones.

⏱️

Nonce + Marca de Tiempo

Protección contra repeticiones con nonce único y ventana de marca de tiempo de 5 minutos.

🚦

Limitación de Tasa

Algoritmo token-bucket: 60 solicitudes/min por clave API, ráfaga de hasta 120.

📦 Plugins Listos para Usar

Descarga plugins de pago preconstruidos para las plataformas de e-commerce más populares. Instala, configura tus claves API y acepta ZoneCoin inmediatamente.

📋

WooCommerce

WordPress 6+ / WooCommerce 8+

⬇ Download

📋

PrestaShop

PrestaShop 8+

⬇ Download

📋

VirtueMart

Joomla 6+ / VirtueMart 4+

⬇ Download