Skip to main content

ECR Interface Protocol

1. Encrypt the data of the protocol​

1.1 Get a 6-digit pair Pin Code​

When the Wonder terminal enters the pair page, a 6-digit pair Pin Code(pinCode1) or the QR code generated by it will be displayed. The client device can obtain this string by scanning a code or manually entering it

Example:​
const pinCode1 = '260880';

1.2 Encrypt the data of the protocol with AES256​


<!DOCTYPE html>
<html lang="zh-CN">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>浏览器端AES加解密演示</title>
  <style>
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
    }

    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      background-color: #f5f7fa;
      color: #333;
      line-height: 1.6;
      padding: 20px;
    }

    .container {
      max-width: 1200px;
      margin: 0 auto;
      background-color: #fff;
      border-radius: 8px;
      box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
      overflow: hidden;
    }

    .header {
      background-color: #4a90e2;
      color: white;
      padding: 20px;
      text-align: center;
    }

    .header h1 {
      font-size: 24px;
      font-weight: 500;
    }

    .content {
      padding: 30px;
    }

    .section {
      margin-bottom: 30px;
      padding: 20px;
      border-radius: 8px;
      border: 1px solid #e1e8ed;
      background-color: #fafbfc;
    }

    .section-title {
      font-size: 18px;
      font-weight: 500;
      margin-bottom: 15px;
      color: #4a90e2;
      border-bottom: 1px solid #e1e8ed;
      padding-bottom: 8px;
    }

    .form-group {
      margin-bottom: 15px;
    }

    .form-group label {
      display: block;
      margin-bottom: 5px;
      font-weight: 500;
      color: #555;
    }

    .form-group input,
    .form-group textarea {
      width: 100%;
      padding: 10px;
      border: 1px solid #ddd;
      border-radius: 4px;
      font-size: 14px;
      font-family: inherit;
    }

    .form-group textarea {
      resize: vertical;
      min-height: 100px;
    }

    .btn {
      background-color: #4a90e2;
      color: white;
      border: none;
      padding: 10px 20px;
      border-radius: 4px;
      cursor: pointer;
      font-size: 14px;
      font-weight: 500;
      margin-right: 10px;
      margin-bottom: 10px;
      transition: background-color 0.3s;
    }

    .btn:hover {
      background-color: #357abd;
    }

    .btn-secondary {
      background-color: #6c757d;
    }

    .btn-secondary:hover {
      background-color: #5a6268;
    }

    .result {
      margin-top: 20px;
      padding: 15px;
      border-radius: 4px;
      background-color: #e9ecef;
      font-family: 'Courier New', Courier, monospace;
      font-size: 14px;
      word-break: break-all;
    }

    .result.success {
      background-color: #d4edda;
      border: 1px solid #c3e6cb;
      color: #155724;
    }

    .result.error {
      background-color: #f8d7da;
      border: 1px solid #f5c6cb;
      color: #721c24;
    }

    .test-results {
      margin-top: 20px;
    }

    .test-item {
      margin-bottom: 20px;
      padding: 15px;
      border-radius: 4px;
      border: 1px solid #e1e8ed;
      background-color: #fff;
    }

    .test-title {
      font-weight: 500;
      margin-bottom: 10px;
      color: #4a90e2;
    }

    .test-details {
      font-family: 'Courier New', Courier, monospace;
      font-size: 13px;
      margin-bottom: 8px;
    }

    .test-status {
      font-weight: 500;
      padding: 4px 8px;
      border-radius: 4px;
      display: inline-block;
    }

    .test-status.passed {
      background-color: #d4edda;
      color: #155724;
    }

    .test-status.failed {
      background-color: #f8d7da;
      color: #721c24;
    }

    .copy-btn {
      background-color: #28a745;
      color: white;
      border: none;
      padding: 5px 10px;
      border-radius: 4px;
      cursor: pointer;
      font-size: 12px;
      margin-left: 10px;
      transition: background-color 0.3s;
    }

    .copy-btn:hover {
      background-color: #218838;
    }

    @media (max-width: 768px) {
      body {
        padding: 10px;
      }

      .content {
        padding: 20px;
      }

      .btn {
        width: 100%;
        margin-right: 0;
      }
    }
  </style>
</head>

<body>
  <div class="container">
    <div class="header">
      <h1>浏览器端AES-256-CBC加解密演示</h1>
    </div>
    
    <div class="content">
      <!-- 手动加密解密区域 -->
      <div class="section">
        <div class="section-title">手动加密解密</div>
        
        <div class="form-group">
          <label for="key">密钥 (Password/Key):</label>
          <input type="text" id="key" placeholder="请输入密钥" value="260880">
        </div>
        
        <div class="form-group">
          <label for="plaintext">明文数据:</label>
          <textarea id="plaintext" placeholder="请输入要加密的明文数据">123</textarea>
        </div>
        
        <div class="form-group">
          <label for="ciphertext">密文数据:</label>
          <textarea id="ciphertext" placeholder="请输入要解密的密文数据"></textarea>
        </div>
        
        <button class="btn" onclick="encryptData()">加密</button>
        <button class="btn btn-secondary" onclick="decryptData()">解密</button>
        
        <div id="manual-result" class="result"></div>
      </div>
      
      <!-- 自动测试区域 -->
      <div class="section">
        <div class="section-title">自动测试</div>
        <button class="btn" onclick="runTests()">运行所有测试</button>
        <div id="test-results" class="test-results"></div>
      </div>
    </div>
  </div>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>
  <script>
    /**
     * AES加密解密工具类
     * 使用CryptoJS实现AES-256-CBC加密解密
     * 包含PKCS7填充和PBKDF2密钥派生功能
     */
    const AESCrypto = {
      // 常量定义
      BLOCK_SIZE: 16, // AES块大小（字节）
      KEY_SIZE: 256 / 32, // 密钥大小（WordArray单位）
      ITERATIONS: 100, // PBKDF2迭代次数
      SALT_SIZE: 16, // 盐大小（字节）
      IV_SIZE: 16, // IV大小（字节）
      
      /**
       * PKCS7填充函数
       * @param {CryptoJS.lib.WordArray} wordArray - 要填充的数据
       * @param {number} [blockSize=16] - 块大小
       * @returns {CryptoJS.lib.WordArray} 填充后的数据
       */
      pkcs7Pad: function(wordArray, blockSize = this.BLOCK_SIZE) {
        if (!wordArray || typeof wordArray.sigBytes !== 'number') {
          throw new Error('Invalid input: wordArray must be a valid CryptoJS WordArray');
        }
        
        const padding = blockSize - (wordArray.sigBytes % blockSize);
        const paddingWords = [];
        const paddingWord = ((padding & 0xff) << 24) | ((padding & 0xff) << 16) | ((padding & 0xff) << 8) | (padding & 0xff);
        
        for (let i = 0; i < padding / 4; i++) {
          paddingWords.push(paddingWord);
        }
        
        return wordArray.clone().concat(CryptoJS.lib.WordArray.create(paddingWords, padding));
      },
      
      /**
       * PKCS7去填充函数
       * @param {CryptoJS.lib.WordArray} wordArray - 要去填充的数据
       * @returns {CryptoJS.lib.WordArray} 去填充后的数据
       */
      pkcs7Unpad: function(wordArray) {
        if (!wordArray || typeof wordArray.sigBytes !== 'number') {
          throw new Error('Invalid input: wordArray must be a valid CryptoJS WordArray');
        }
        
        const sigBytes = wordArray.sigBytes;
        if (sigBytes === 0) {
          throw new Error('Invalid input: wordArray is empty');
        }
        
        // 获取最后一个字节作为填充长度
        const lastWord = wordArray.words[Math.floor((sigBytes - 1) / 4)];
        const padding = lastWord & 0xff;
        
        // 验证填充长度
        if (padding < 1 || padding > this.BLOCK_SIZE) {
          throw new Error('Invalid PKCS7 padding: padding length out of range');
        }
        
        // 验证所有填充字节
        for (let i = sigBytes - padding; i < sigBytes; i++) {
          const currentWord = wordArray.words[Math.floor(i / 4)];
          const currentByte = (currentWord >> (24 - (i % 4) * 8)) & 0xff;
          if (currentByte !== padding) {
            throw new Error('Invalid PKCS7 padding: inconsistent padding bytes');
          }
        }
        
        // 创建去填充后的数据
        return CryptoJS.lib.WordArray.create(wordArray.words, sigBytes - padding);
      },
      
      /**
       * 使用PBKDF2派生密钥
       * @param {string} pinCode - 密码/密钥
       * @param {CryptoJS.lib.WordArray} salt - 盐值
       * @returns {CryptoJS.lib.WordArray} 派生的密钥
       */
      deriveKeySecure: function(pinCode, salt) {
        if (!pinCode || !salt) {
          throw new Error('Invalid input: pinCode and salt are required');
        }
        
        return CryptoJS.PBKDF2(pinCode, salt, {
          keySize: this.KEY_SIZE,
          iterations: this.ITERATIONS,
          hasher: CryptoJS.algo.SHA256
        });
      },
      
      /**
       * 加密数据
       * @param {string} pinCode - 密码/密钥
       * @param {string} data - 要加密的明文数据
       * @returns {string} Base64编码的加密结果
       */
      encrypt: function(pinCode, data) {
        try {
          if (!pinCode) {
            throw new Error('Invalid input: pinCode and data are required');
          }
          
          // 生成随机盐和IV
          const salt = CryptoJS.lib.WordArray.random(this.SALT_SIZE);
          const iv = CryptoJS.lib.WordArray.random(this.IV_SIZE);
          
          // 派生密钥
          const key = this.deriveKeySecure(pinCode, salt);
          
          // 转换数据并填充
          const dataWA = CryptoJS.enc.Utf8.parse(data);
          const paddedData = this.pkcs7Pad(dataWA);
          
          // 执行加密
          const encrypted = CryptoJS.AES.encrypt(paddedData, key, {
            iv: iv,
            mode: CryptoJS.mode.CBC,
            padding: CryptoJS.pad.NoPadding
          });
          
          // 拼接盐、IV和密文并Base64编码
          return CryptoJS.enc.Base64.stringify(
            salt.clone().concat(iv).concat(encrypted.ciphertext)
          );
        } catch (error) {
          console.error('Encryption failed:', error);
          throw error;
        }
      },
      
      /**
       * 解密数据
       * @param {string} pinCode - 密码/密钥
       * @param {string} encryptedBase64 - Base64编码的加密数据
       * @returns {string} 解密后的明文数据
       */
      decrypt: function(pinCode, encryptedBase64) {
        try {
          if (!pinCode || !encryptedBase64) {
            throw new Error('Invalid input: pinCode and encryptedBase64 are required');
          }
          
          // 解析Base64数据
          const encryptedData = CryptoJS.enc.Base64.parse(encryptedBase64);
          
          // 验证数据长度
          if (encryptedData.sigBytes < this.SALT_SIZE + this.IV_SIZE) {
            throw new Error('Invalid encrypted data: data too short');
          }
          
          // 提取盐、IV和密文
          const salt = CryptoJS.lib.WordArray.create(
            encryptedData.words.slice(0, this.SALT_SIZE / 4),
            this.SALT_SIZE
          );
          const iv = CryptoJS.lib.WordArray.create(
            encryptedData.words.slice(this.SALT_SIZE / 4, (this.SALT_SIZE + this.IV_SIZE) / 4),
            this.IV_SIZE
          );
          const ciphertext = CryptoJS.lib.WordArray.create(
            encryptedData.words.slice((this.SALT_SIZE + this.IV_SIZE) / 4),
            encryptedData.sigBytes - this.SALT_SIZE - this.IV_SIZE
          );
          
          // 派生密钥
          const key = this.deriveKeySecure(pinCode, salt);
          
          // 执行解密
          const decrypted = CryptoJS.AES.decrypt({ ciphertext: ciphertext }, key, {
            iv: iv,
            mode: CryptoJS.mode.CBC,
            padding: CryptoJS.pad.NoPadding
          });
          
          // 去填充并转换为字符串
          const unpaddedData = this.pkcs7Unpad(decrypted);
          return CryptoJS.enc.Utf8.stringify(unpaddedData);
        } catch (error) {
          console.error('Decryption failed:', error);
          throw error;
        }
      }
    };
    
    /**
     * 加密数据并显示结果
     */
    function encryptData() {
      const key = document.getElementById('key').value;
      const plaintext = document.getElementById('plaintext').value;
      const resultDiv = document.getElementById('manual-result');
      
      try {
        const encrypted = AESCrypto.encrypt(key, plaintext);
        document.getElementById('ciphertext').value = encrypted;
        resultDiv.innerHTML = `加密成功: <br><strong>密文:</strong> ${encrypted}`;
        resultDiv.className = 'result success';
      } catch (error) {
        resultDiv.innerHTML = `加密失败: ${error.message}`;
        resultDiv.className = 'result error';
      }
    }
    
    /**
     * 解密数据并显示结果
     */
    function decryptData() {
      const key = document.getElementById('key').value;
      const ciphertext = document.getElementById('ciphertext').value;
      const resultDiv = document.getElementById('manual-result');
      
      try {
        const decrypted = AESCrypto.decrypt(key, ciphertext);
        resultDiv.innerHTML = `解密成功: <br><strong>明文:</strong> ${decrypted}`;
        resultDiv.className = 'result success';
      } catch (error) {
        resultDiv.innerHTML = `解密失败: ${error.message}`;
        resultDiv.className = 'result error';
      }
    }
    
    /**
     * 添加测试结果到UI
     * @param {string} title - 测试标题
     * @param {string} details - 测试详细信息
     * @param {boolean} passed - 是否通过
     */
    function addTestResult(title, details, passed) {
      const testResultsDiv = document.getElementById('test-results');
      const testItem = document.createElement('div');
      testItem.className = 'test-item';
      
      const testTitle = document.createElement('div');
      testTitle.className = 'test-title';
      testTitle.innerHTML = title;
      
      const testDetails = document.createElement('div');
      testDetails.className = 'test-details';
      testDetails.innerHTML = details.replace(/\n/g, '<br>');
      
      const testStatus = document.createElement('div');
      testStatus.className = `test-status ${passed ? 'passed' : 'failed'}`;
      testStatus.textContent = passed ? '通过' : '失败';
      
      testItem.appendChild(testTitle);
      testItem.appendChild(testDetails);
      testItem.appendChild(testStatus);
      testResultsDiv.appendChild(testItem);
    }
    
    /**
     * 运行所有测试
     */
    function runTests() {
      // 清空之前的测试结果
      document.getElementById('test-results').innerHTML = '';
      
      console.log('=== AESCrypto 测试开始 ===');
      
      let testCount = 0;
      let passedCount = 0;
      
      // 测试1: 基本功能测试
      testCount++;
      try {
        const pinCode1 = '260880';
        const data1 = '123';
        
        const encrypted1 = AESCrypto.encrypt(pinCode1, data1);
        const decrypted1 = AESCrypto.decrypt(pinCode1, encrypted1);
        
        const passed = decrypted1 === data1;
        if (passed) passedCount++;
        
        const details = `密钥: ${pinCode1}\n明文: ${data1}\n密文: ${encrypted1}\n解密后: ${decrypted1}`;
        addTestResult(`测试${testCount} - 基本功能测试`, details, passed);
      } catch (error) {
        addTestResult(`测试${testCount} - 基本功能测试`, error.message, false);
      }
      
      // 测试2: 复杂密钥和中文数据测试
      testCount++;
      try {
        const pinCode2 = 'OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN';
        const data2 = '这是一段中文测试数据';
        
        const encrypted2 = AESCrypto.encrypt(pinCode2, data2);
        const decrypted2 = AESCrypto.decrypt(pinCode2, encrypted2);
        
        const passed = decrypted2 === data2;
        if (passed) passedCount++;
        
        const details = `密钥: ${pinCode2}\n明文: ${data2}\n密文: ${encrypted2}\n解密后: ${decrypted2}`;
        addTestResult(`测试${testCount} - 复杂密钥和中文数据测试`, details, passed);
      } catch (error) {
        addTestResult(`测试${testCount} - 复杂密钥和中文数据测试`, error.message, false);
      }
      
      // 测试3: 空数据测试
      testCount++;
      try {
        const pinCode3 = '260880';
        const data3 = '';
        
        const encrypted3 = AESCrypto.encrypt(pinCode3, data3);
        const decrypted3 = AESCrypto.decrypt(pinCode3, encrypted3);
        
        const passed = decrypted3 === data3;
        if (passed) passedCount++;
        
        const details = `密钥: ${pinCode3}\n明文: (空字符串)\n密文: ${encrypted3}\n解密后: (空字符串)`;
        addTestResult(`测试${testCount} - 空数据测试`, details, passed);
      } catch (error) {
        addTestResult(`测试${testCount} - 空数据测试`, error.message, false);
      }
      
      // 测试4: 特殊字符测试
      testCount++;
      try {
        const pinCode4 = '260880';
        const data4 = '!@#$%^&*()_+-=[]{}|;:,.<>?';
        
        const encrypted4 = AESCrypto.encrypt(pinCode4, data4);
        const decrypted4 = AESCrypto.decrypt(pinCode4, encrypted4);
        
        const passed = decrypted4 === data4;
        if (passed) passedCount++;
        
        const details = `密钥: ${pinCode4}\n明文: ${data4}\n密文: ${encrypted4}\n解密后: ${decrypted4}`;
        addTestResult(`测试${testCount} - 特殊字符测试`, details, passed);
      } catch (error) {
        addTestResult(`测试${testCount} - 特殊字符测试`, error.message, false);
      }
      
      // 测试5: 长文本测试
      testCount++;
      try {
        const pinCode5 = '260880';
        const data5 = '这是一段较长的测试文本，用于测试AES加密解密的性能和正确性。这段文本包含了多种字符，包括中文、英文、数字和特殊符号。';
        
        const encrypted5 = AESCrypto.encrypt(pinCode5, data5);
        const decrypted5 = AESCrypto.decrypt(pinCode5, encrypted5);
        
        const passed = decrypted5 === data5;
        if (passed) passedCount++;
        
        const details = `密钥: ${pinCode5}\n明文长度: ${data5.length} 字符\n密文长度: ${encrypted5.length} 字符\n解密后长度: ${decrypted5.length} 字符\n解密后与明文一致: ${passed}`;
        addTestResult(`测试${testCount} - 长文本测试`, details, passed);
      } catch (error) {
        addTestResult(`测试${testCount} - 长文本测试`, error.message, false);
      }
      
      // 测试6: 错误密钥测试
      testCount++;
      try {
        const pinCode6 = '260880';
        const wrongKey = 'wrongkey';
        const data6 = '123';
        
        const encrypted6 = AESCrypto.encrypt(pinCode6, data6);
        // 使用错误密钥解密，应该失败
        const decrypted6 = AESCrypto.decrypt(wrongKey, encrypted6);
        
        // 这里应该抛出错误，如果没有抛出则测试失败
        addTestResult(`测试${testCount} - 错误密钥测试`, '使用错误密钥解密时没有抛出预期的错误', false);
      } catch (error) {
        // 预期应该抛出错误，所以测试通过
        passedCount++;
        addTestResult(`测试${testCount} - 错误密钥测试`, `使用错误密钥解密时正确抛出错误: ${error.message}`, true);
      }
      
      // 显示测试总结
      const summary = document.createElement('div');
      summary.className = 'test-item';
      summary.innerHTML = `
        <div class="test-title">测试总结</div>
        <div class="test-details">
          总测试数: ${testCount}<br>
          通过测试: ${passedCount}<br>
          失败测试: ${testCount - passedCount}<br>
          通过率: ${((passedCount / testCount) * 100).toFixed(2)}%
        </div>
        <div class="test-status ${passedCount === testCount ? 'passed' : 'failed'}">
          ${passedCount === testCount ? '全部通过' : '部分失败'}
        </div>
      `;
      document.getElementById('test-results').appendChild(summary);
      
      console.log(`=== AESCrypto 测试结束 ===`);
      console.log(`总测试数: ${testCount}`);
      console.log(`通过测试: ${passedCount}`);
      console.log(`失败测试: ${testCount - passedCount}`);
      console.log(`通过率: ${((passedCount / testCount) * 100).toFixed(2)}%`);
    }
    
    // 页面加载完成后自动运行测试
    window.addEventListener('load', function() {
      runTests();
    });
  </script>
</body>

</html>

2. Request and Response Protocol Data Format​

2.1 Request header​

VariableTypeRequiredDescription
x-p-business-idStringYThe current business ID, Specify the ECR device to receive orders for a certain Business
x-device-snStringYThe serial number of the ecr terminal payment device
x-request-idStringYEvery time communication takes place, it is crucial to ensure that the Request ID is a unique UUID.

2.2 Request data structure​

Request JSON​
VariableTypeRequiredDescription
versionStringYCurrent communication protocol version number
actionenumYActions: Pair, DeviceInfo, Sale, ...
dataStringYEncrypted data
Request "data" structure​
VariableTypeRequiredDescription
headerObjectYProtocol header
bodyObjectNProtocol body
Request "data.header" structure​
VariableTypeRequiredDescription
requestIDUUIDYRequest ID: Every time communication takes place, it is crucial to ensure that the Request ID is a unique UUID. In the event of a response, the corresponding identifier will be returned in the response header as the "responseID".
clientDeviceSNStringYClient device serial number
timestampdatetimeYThe timestamp of the current request
businessIDStringNThe unique ID of the current merchant's business
Example:​

/*
Pin Code: pinCode1
Encrypt the original data:
{
  "header": {
    "requestID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b"
  }
}
*/

{
  "version": "2.0",
  "action": "Pair",
  "data": "pePKeo2urjKmSoah7AWb8d9JDqjqtJG781Yh8NxICIbJ72y4kgxuau+yX6bXF/M6gz9oyuIJC1Q/shNrwKP8Ev8qzoZ587LtPOaQrENU2W/p6ue7PRoY9C3pEo4M2bZeQlELOQj8ohKqmEdrlcntpJem3Q+yFeXTPxAwvpKfKTgYbpdHQSC//5WnoxNGnAHLaqRTaEDRr0wWYAcdb7mY0/h7yNkkSNffPjmvlMmDBTmWP/Dq+c7k8otszx5m0YBTyOFxOJipLQytMwoZIFzG/3m3H7jMH68VvWemhp+DPh5TFa+cgoZpASaoz/oLylv8"
}

2.3 Response data structure​

Request JSON​
VariableTypeRequiredDescription
versionStringYCurrent communication protocol version number
actionenumYActions: DeviceInfo, Sale, PreAuth, Abort, Void, Refund
dataStringYEncrypted data
Response "data" structure​
VariableTypeRequiredDescription
headerObjectYProtocol header
bodyObjectNProtocol body
Response "data.header" structure​
VariableTypeRequiredDescription
responseIDStringYThe response ID in the response Header is derived from the request ID in the request header.
serverDeviceSNStringYThe serial number of the terminal payment device
timestampdatetimeYThe timestamp of the current request
businessIDStringNThe unique ID of the current merchant's business
Example:​

/*
Pin Code: pinCode1
Encrypt the original data:
{
  "header": {
    "responseID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b",
    "ackUuid": "4d366618-49cf-4f93-bd23-25388a573b0c"
  }
}
*/

{
  "version": 2.0,
  "action": "Pair",
  "data": "id4/0hIX8IG0GJuuH4OeLqHy50LdXMoG96A4jPNhnpl37h+Y6z/tvkisdkJh2kfGBjLQtOJ/TptfeHkNT31mL+kEvzArOg0VxTTd2AksF1qShOQDvK6Xvqhk0MsT6Vx+McSA5HJGp+cvNODc64TmZ/Z9qH7Sg/rcrj2uPq28a1YfB19FNL5w0CmvIj8VfXvaNhaBSguFodQWqP5XazvsHtI/E6Nyk4qsNIHNFlb10IKWws2Kgzg6voFYuZMBqKcu18iHTZcMc+YV/4bShFA3QuTR9562U91bCgebTq9cdgV/Or0VDZbfcnCY4EGM1z7G5oE6IBsdPmDBAS45X/279gDd1lgoqSX8FOsRSfwCldjMUUfKFvsH0m7OKGopfjRW"
}

3. Interface Protocol​

3.1 Pair​

After the customer device acquires the 6-digit pairing code, it uses the "Pair" protocol for pairing. After the Wonder terminal receives a pairing request, it will return a UUID identifier, which will be used by the "Ack" protocol.

  • Action: Pair
  • Pin Code: pinCode1

Request "data.body" structure​

VariableTypeRequiredDescription
pairUuidUUIDYPair the uuid identifier
Example:​

/*
Pin Code: pinCode1
Encrypt the original data:
{
  "header": {
    "requestID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b"
  }
}
*/

{
  "version": "2.0",
  "action": "Pair",
  "data": "Hlf2xR22p3Mkc2Hvj0XrvlyZmb5vNk6MxzMDpfE86Y1w5jxK1HYqeWgMGzjlEFr3QZw3N7Czpm05NlBLfAyhrdCW/V5Wcf2QsfAvOQV4cNP6VyKR0XwQHXqydqJwzrDftJ+6uamLYQlJn1D4UbQtFz1oR9QCJlM/KJHLcup1IrqZ6U7WN+N/Qi0bxWYcVcEn4KVegSTDFUIUbabXlAJoYNQwP9AocaBVegm2orKbFgxUGlFJRxFrjm5I2JiAKSfi3cFOezyQ/2BB2jvfuGTLoEsujuEwLkfRzmn7cxRXfDhNncoVeOVqu+HcGYcmomrh"
}

Response "data.body" structure​

VariableTypeRequiredDescription
pairUuidUUIDYPair the uuid identifier
ackUuidUUIDYAck the uuid identifier
pinCodeStringYIn the test code, it is pinCode2, which is used in the Ack interface and the business interface
Example:​

/*
Pin Code: pinCode1
Encrypt the original data:
{
  "header": {
    "responseID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b",
    "ackUuid": "4d366618-49cf-4f93-bd23-25388a573b0c",
    "pinCode": "OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN"
  }
}
*/

{
  "version": 2.0,
  "action": "Pair",
  "data": "hvii5rlCFHUh1o91yfaNKDbnXIjpLOzF+rQ+D0/GVx7HjBU4oM/YRk41tMnkpFeagXXFNKgBrMNQzQC7ohU9R6OSbGKQMzQvgarrEY3cSHmGv1FuVL290jcEzD5bW99CJSi0bKeo/oTh/aPLadXp2gZNRWEkuP8sEZCM7w7pv0pQvwcnfJKBnD6tgkDgMIUPs1QaNIGPom0s12m9k4R/iQmB+8A6UWkscSd48g85ZJ77WWAeuQtmgRoW8/VNss5aRjIf6CBH0OYE3rYCACYl8fIrBMLsRBl24NmIhiTSt97bKOXFXMugoc+/jTWAz+YgVXadkUTUhG1QBxhJanS0EEMu2x5Q/Q2IMaX8kWmU4mZOFA1yrfXSNSzYdtS63P0SPaSw0uB0uObF5K7qEeYkhI8HDIu0dLJklXafbpWHBhAUFvUUNnbtW/WXvQd8xwzs"
}

3.2 Ack​

After the client terminal initiates the pairing, it will receive an "ackUuid" identifier. This protocol needs to carry the "ackUuid" identifier to confirm that the pairing has been successful.

  • Action: Ack
  • Pin Code: pinCode2

Request "data.body" structure​

VariableTypeRequiredDescription
ackUuidUUIDYThe Wonder device will use this UUID to confirm whether the pairing was successful
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "73a95cfe-b0f1-42b3-82d1-5a640f61e359",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "ackUuid": "4d366618-49cf-4f93-bd23-25388a573b0c"
  }
}
*/

{
  "version": "2.0",
  "action": "Ack",
  "data": "HyVyYTEFadRFQyO3ErhsscZbuwH2nmzt7WcqaX7zwOU2dYZ2kK1nkwKTxE7FDVR1Lcra0yfcOIZdxO/qdAv2NRDwUHkMiBvkIxZMVlaM+3CUdhpqG0Xtub28gt9Z5KI6HpeGdbSGHm1qDImHh+DEVEe55mUew4/czadIQ3kvpVv2vk1U4h2NVWjkw6C4EZMtGKnWyMZmraUxj/kE8LRvckRiYy9MF+v1Dq2goIwSHwa/skZjHJ8d5ZbGrssuWMJgXJCflvTh3TFqntcIrASYobNVWcPsUByQS9vYuZdpDU/PuQ7NyIvXSGp2vmJyUpfq"
}

Response "data.body" structure​

VariableTypeRequiredDescription
deviceStatusStringYPayment device transaction status: Free / Busy
Free: The current device is idle and available for new transactions;
Busy: The current device is occupied with an ongoing transaction and is not available for other transactions at the moment.
networkStatusStringYThe current network connection status of the payment device: Connected / Disconnected
softwareVersionStringYThe software version of the payment device
businessIDStringYThe response ID in the response Header is derived from the request ID in the request header.
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "73a95cfe-b0f1-42b3-82d1-5a640f61e359",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "deviceStatus": "Free",
    "networkStatus": "Connected",
    "softwareVersion": "1.0.0(188)",
    "businessID": "ff467f02-5b69-45f3-81aa-bffcca55fe8f"
  }
}
*/

{
  "version": 2.0,
  "action": "Ack",
  "data": "o8DusOr0hm/aEr3flPjUYZ2dIBztnOz/KbO+VL/9deQvsZvREYwn3Rks8N3B4+XuoKraTp6mlh2DsMTU7z/scvgy6jwnWFnVD8O1aOPE6yZn+nvlqohCwkxgqBRS0/fSqPE0oWu8d8BNBQAGgHzxmpPwogcNEoIUE9DmKnJ9ZXXskoG3SbPdUoBgtKsJiX3cDvS3jOK1FPPuOoSOt9pSf1Kt71/wQE5bLozJ7W3UhZuzQ9MqGa+PGKBPjGqUn9GXx4Pvp2sJBy/MasMIdIcPf/XTJNCXeXEAaa0A50cEbY+/1fYeS9GMD9RATln8mnjy/k+UBqCE9T6n41xCXcCyw6hKtcvfgmH28JXY4tSxpIKMGFityhMZvdFyccdR+RW3YqDYHm2g7vfyThIoAl/3pV2KfhzXc/Po+pg0Y3I6yoc="
}

3.3 Device Info​

  • Action: DeviceInfo
  • Pin Code: pinCode2

Request "data.body" structure​

This request has no body

Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "2c7f32e1-b9e4-4b34-96cc-15c51289f69b",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  }
}
*/

{
  "version": "2.0",
  "action": "DeviceInfo",
  "data": "LzskNnsYgifR+ZjuXVjPDfT2Nw3YhbA4OAmT2yBBFgR39Q5TjSrnaW44czmmBcVlr2GL327sHk62o5FMXsqyxUNJC0uq1hEgp1gTzxzLYNnkwqbb7NeSFfdscqReOPiOMbY7rWN6sjfoVpVbTKSEVYmhZAVx10TrzSPE7w63pHNZl6utlzkcZNVwZSQO6qqkXtAGbKtryxZ1J0VA8mIt80aDKqEpECYICV1twM6gHgw="
}

Response "data.body" structure​

VariableTypeRequiredDescription
deviceStatusStringYPayment device transaction status: Free / Busy
Free: The current device is idle and available for new transactions;
Busy: The current device is occupied with an ongoing transaction and is not available for other transactions at the moment.
networkStatusStringYThe current network connection status of the payment device: Connected / Disconnected
softwareVersionStringYThe software version of the payment device
businessIDStringYThe response ID in the response Header is derived from the request ID in the request header.
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "2c7f32e1-b9e4-4b34-96cc-15c51289f69b",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "deviceStatus": "Free",
    "networkStatus": "Connected",
    "softwareVersion": "1.0.0(188)",
    "businessID": "ff467f02-5b69-45f3-81aa-bffcca55fe8f"
  }
}
*/

{
  "version": "2.0",
  "action": "DeviceInfo",
  "data": "ZhnFiGfiT5Oir46CtHaQbVpegL5pRkNELxhOdN+XbqzIiaUmoimyxD3VYspmdNhyy2ZoOsrDZGvNhOxp/5/Cf21XBb2j8P8Gl/eMV7yHafjvqhoYGQY+m2PoYYAwBsWH0XDmbti+rfg7VQFFvHBoOqnfYmktcSJzHjm5hX4qyUMQdNWeTF4e+pkZ3jvTTLvdzMZlrMjwXOMxE1ikrbR6sgCV2cFx2Lrdvlh8gJdE6SM35CZna88X/s/tMPe2w32Lh0ou2eHKlARBuCG69KxEp7RpBQtw9+PDrzX7u4bL13V6b6LZJnejuwIsbxIz0yAPr6eApB41Vr6pELCXOyh1zRoxlF8RN5c8AhYE5NrSLCcvMOwZxvGjihrePAjO7vJFivowjoIwYMad1H31uLCIGrjOoD2JEycnpDWuGyRZcgU="
}

3.4 Sale​

  • Action: Sale
  • Pin Code: pinCode2

Request "data.body" structure​

VariableTypeRequiredDescription
referenceIDStringYReference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
paymentMethodenumNPayment methods:
-credit_card,
-fps,
-octopus.
-consumer_presented_qr_code,
-all,
If the payment method is transmitted, it will directly redirect to the target page
restrictedPaymentMethodsArrayNPayment Methods
currencyStringYExample: HKD / USD / RMB
amountStringYSale amount
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "referenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1",
    "currency": "HKD",
    "amount": "10.20"
  }
}
*/

{
  "version": "2.0",
  "action": "Sale",
  "data": "x0YiJ9xhtmSxU02TlNC1TVfFY1/QKuQYniemnpEakcEiVmEDuMWQgFmnjAQrnl16omCQkOWW0sQuC9RjZH67gCfWBpQAQlO10RWw/R5XBmGs1jeJlND0IEKz6BLhbCflbME+GkZLyQ45D2vZdtI9KTSfy/CRmHdzngI31wU2002WUeAwaZt/R9teYmkXqrqtQBVn8j0gGpm4lS20hDqqIOB4olb4QgjFINopRh2eKGSTKsCnFBBWcvYiXYYHw/tDeQTwMRrIKfYYKU9ASmYcy+vG84G4renwsieFLWbp9hSfBpozjUOxNl7C2ziOdOYnOlzABW9a1MCLFx6ZJFcuGWb1rsrvOB1i4PAEtIH/ar0="
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
currencyStringNExample: HKD / USD / RMB
amountStringNSale amount
paymentMethodStringNPayment method
paymentEntryTypeStringNPayment entries, Example: contactless
rrnStringNReceiver Reference Number
brnStringNBindo Reference Number
transactionTypeStringNTransaction type: Sale / PreAuth / Void / Refund
transactionTimeDatetimeNTransaction Time
creditCardObjectN
creditCard.panPrefix6DigitsStringYFirst 6 digits of the credit card number
creditCard.panLast4DigitsStringYLast 4 digits of the credit card number
creditCard.consumerIdentifyStringYConsumer identify, e.g. Card Number, Open ID, etc.
Example 1:​

When the status is Pending


/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Pending",
    "errorCode": "",
    "errorMessage": ""
  }
}
*/

{
  "version": "2.0",
  "action": "Sale",
  "data": "TOGegN7Gul4p+OeymxhD12sB2u6G50/SbhM+pEbY45IpW9gdVPWx7fxQSxvRK44lClO5+9y7vkaCfDksl4Ngq0fm1Uq/1v4rUhwKAt1VJS8f3lHgSWT0UaKu0qNY/7ynJmBRpjfSPaKgRH8lWTHMhbf364GE9N0Rd8CDsbPUEjSR1LTtXuXoKSOqQeywrADg+D+AAQpzz+iwq005HIzUic/L9PD/JiXRcER0Qv3ngvvmpUEB/V3ycvx1sFN/1Ja/3ne60LqYOBVRa1aEPyU0WbNGO4+Yu7GYc+XiOXgEyiBDtcPQcFOeDi+PanWLtp1k"
}

Example 2:​

When the status is Failed


/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Failed",
    "errorCode": "5xxxx",
    "errorMessage": "The equipment is being traded"
  }
}
*/

{
  "version": "2.0",
  "action": "Sale",
  "data": "s9j7u8roWhx/55iOwMIY6ePbKradiQGo/3gdzDcCJMEEIiGZVQ0g9C7fGR56tSqw2p4jdU0iIoZ9zOuZG0oUmsyqqUXvB40bMYLSpfrlBhqvGYAoSHuXBtqDKr/ithRvIj90y0apTv6ud0W7eAfb8YECGuniBaOFdooXI5CbdPzaDhJ84iaXF07KmBmjBuWPlM4wMMUWVghtFiIOEC08HFkEuPdRQamABD+yYUao/Nv1NuHG0+geN+CVHPZkEJQgQZDlJA0NdVkHI9qlwtr8V4E1Onw6/dJeXCXqSj351c0HzxMTWWSuGNSbxF48YrDIejeiV4VxTs5GokpKgSEHOaPvPhsAB+lRenv1JAtqZcM="
}

Example 3:​

When the status is Success


/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Success",
    "errorCode": "",
    "errorMessage": "",
    "currency": "HKD",
    "amount": "10.20",
    "paymentMethod": "visa",
    "paymentEntryType": "contactless",
    "rrn": "3263492852830699521",
    "brn": "3263492852495159296",
    "transactionType": "Success",
    "transactionTime": "2023-06-30T09:08:52+00:00",
    "creditCard": {
      "panPrefix6Digits": "555555",
      "panLast4Digits": "1234",
      "consumerIdentify": "xxxxxxx"
    }
  }
}
*/

{
  "version": "2.0",
  "action": "Sale",
  "data": "zqZex4ZAGwgB5NmBD3FH4FGZBqld/s1dqLltYfIf4TPljkvuy9BmK5Vq8Cs4dY/gFZO9dp8L3xEAT6TcnT1o8aGx5ffy8PWkrB4uXo1cQpoc8h534Ph8QTmqQ2LN9QUf0nOdAK2u164KUETHPFgMXY8J4Y2Z8S9fHJqp40XIHbUCo98bXJg/f+f4pslampeLCeAl56iKBTiKNy+Z/KHGj6SHzFfysJk9iCewWn9JZBh+Pts5e3o0fhw3VPVDVSKEgqceAyrIzUD834KpuZocO9Xk1XsxscC7FBB06GBJg8wUCqb0NqLGfMmmUdC5XAT+DOQ6q80U+jKjkY+m5rxTJEeQshzbP3Ulo/k1rCyk80czbH45GlhYPLNxiWPaJgVXm05GL6ClvjACx8ASBKbG2cyn3nmoI53s2/EsT3nLZ1rOf4SC3Di1pfWOZB2hEqCkaDmZTVFMEyYdGsMlO0nl2w3KEq6zf9LGLXrqDhORPq73u1ESckj4zNjHsLoTP8/ZyWc/1J2OLJRcxk4UfZ3C7vzkD0zIc8phOCZFbu4vRQZ+W4U0ZK9FZeDOby24z4NSHRut5zMLhERIWwW+A5ozXHkNp0JU+yjln0JkAemzy8BmPxWl5t8Y0Zih5rbcZbJj7j+xri9dz10KfdAvU7mAZVllrheCpt0eflbIHCSyMUUl4Km1nnNaeC2/z43tbvGhthEhqr64Yj5U4GSJWD84WVrwS/dzhC29d3TOsxlfC3M="
}

3.5 Abort​

  • Action: Abort
  • Pin Code: pinCode2

Request "data.body" structure​

This request has no body

Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "c5bf3cbe-a146-4f8c-bb8e-209c1e7b8437",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  }
}
*/

{
  "version": 2.0,
  "action": "Abort",
  "data": "AG1mb0IbA6EzpyvE6g6ySqemX3XiXLVm8wlGbPkOfsRNuxSCy1fz3/VlDqRd3PxDvy8FHCv6pvB0nhxysM+V85NNbQTC15+GgrnLeupS9IMSYYPYAmhyXtqae1DbXcqCj9F614QJIB0bWzRpqWmOgap/uzTIwFHf/qGMKCCCADouMiDxnirp1EunsRBeECyBLdlBoqPaWoNhhMISyZu5+9eul5E+eZMmKwNUDL4KJw0="
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "c5bf3cbe-a146-4f8c-bb8e-209c1e7b8437",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Success",
    "errorCode": "",
    "errorMessage": ""
  }
}
*/

{
  "version": 2.0,
  "action": "Abort",
  "data": "MPf0p+jMU+smn2s/S1so9c4x3YLmJeJ3TzXbtiniGAVFhjYJrCCOdC0wc32c738qd1D5F8WlaWXqz+uNtQzgkLgmx3wz/rDGBNRh11tNzY4AfZEra3JfWEWEsNDFpDco9FMjF4mO/AhD/KFYe5+1suMCtJdLYE5ka9XnJr3xoYd8YrHdkY3Bpq8/tveW8FHIwMOj67hyOvtjdtnemv/uD52QTcSZMVCF6vQFbK9VJb74tE2kbGWlWmYxtWwPRwrv5gTh6YSdMESoFxITjE29SkVXv+oNa85B/NqOMSFEc6AsgIKV0xCpebIPOM6Owz6G"
}

3.6 Void​

  • Action: Void
  • Pin Code: pinCode2

Request "data.body" structure​

VariableTypeRequiredDescription
orgReferenceIDStringYThe reference ID that was carried during the transaction made at that time.
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "8e2c77fb-ff49-4c49-82f5-ae741cb7d3d9",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "orgReferenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1"
  }
}
*/

{
  "version": 2.0,
  "action": "Void",
  "data": "p3Lowjj5f+OD2W2K2XeSrbpk31s+5jBe+5fG4XdqMU2JE+8jDN51akS1+sq5DvDL9vMKUSlHEO5868yNb7hbA/CHCB5xein9imTEaelM0BDpoTnew1mRkELIcWZYECyghXlev44oIhBEwMKHqQdUwfpKpPL3dr7CmLmBP7+Uiau1M3gai4V9Y3ClQqgCROqOegLZ9TKHHBtA9k5r7ArDlKShqjYmtXA0ASvkxc01tHFQbcrLAeW8yOA8NlQzO+oQrpafWE+5CSEqWP7OZlc5EJi69/X2Zw9x4H3p/fl8SFjEf3Og7RO15zIZTd708cju"
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "8e2c77fb-ff49-4c49-82f5-ae741cb7d3d9",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Success",
    "errorCode": "",
    "errorMessage": ""
  }
}
*/

{
  "version": 2.0,
  "action": "Void",
  "data": "hknIQAGtuz/m0wpmRK7ya22HBiS9jI84cu2KHlCHPbVgQj0urBKWKEXopqnLESWTvyezR5XOwMTFSzTc0vb9/qySDYVXJqyHsynPrI3Ad6NswcBbkwKWVjT+vmQWX6IWqGqQyMDGjxKX8AgZf+3f0xyJTgOEvUPRC2+6sNaMfNR7szcfMxhZ5ji6GrL8xT6j/b/8CxYSsA/9f5rC/bQehxSHf/iUS3cLXABMfZn4wUqmfuCCfSXtgdlNSa3IT6K860sOJfnn6LLKqdT937vNqjeF/mOgrZnjdwxFGokgZNKdPdHbmc1TDwAw/QHxk1+E"
}

3.7 Refund​

  • Action: Refund
  • Pin Code: pinCode2

Request "data.body" structure​

VariableTypeRequiredDescription
referenceIDStringYReference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
orgReferenceIDStringYThe reference ID that was carried during the transaction made at that time.
currencyStringYExample: HKD / USD / RMB
amountStringYRefund amount
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "0f7d24de-76fc-46f8-861b-2d0d31a2dd9e",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "referenceID": "97cc8c76-65e0-4bd2-9e16-9b9e09f65c42",
    "orgReferenceID": "4b02c099-4dc9-4b30-bd2c-27bf3223df6b",
    "currency": "HKD",
    "amount": "10.20"
  }
}
*/

{
  "version": 2.0,
  "action": "Refund",
  "data": "y7D+Argj9zj7/+Z2shQY35DvhruwzC3IMLyM01HL6dlE6CFTPOgJuxv9aHb0VaoMu4b9jRaTjaCHu5BPjUYS+XbzYlDngkuiAloWpAgB2Z6Z+VzDqPK/MV0rKTwdCrcYcIpgnDCzI7G8w5Q/0ey8C7scx/fvsHlYmCG1DOjYA88jmJam10vm2Y4fVTsz4jR4Nh9a1qjsf/JgsaPyqf/F3nnmH2Fxov2fc8xTf7Zvexk0ShotgG7hdQ4Ifj31Tyqr36pM5bIQa70eKuq/SuFp4O2IGpfugb/9ztMRp7jjZ3qm2cVpxJG5IcpMfdDZGWFJFb9jz0Pu5iN0BKDA+CibBnb4wUCZK1A7nNA94fbpPJX8ehuTOoTiKbR92Gihq/KXtpRDwGzKvatOy2xdND1KE9fH83d6pmaAoiYrUaQiH9Y="
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "0f7d24de-76fc-46f8-861b-2d0d31a2dd9e",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Success",
    "errorCode": "",
    "errorMessage": ""
  }
}
*/

{
  "version": 2.0,
  "action": "Refund",
  "data": "L13PVs3Bj9CCqFHboha1OLUdQZ8/BNP9ZX0pCtp7bl5Uvy+8xhUoohBxyZR1pwMMf61Uwpdm+ivQ11dcVK8X3NjB+AWkF6R4dIW+n+jooZ5RFf1dpDB3EJS4BRhACf9lq9htJPnIqjvWchBLSq/AGEClCF6C1rTNn5hF/p2pxFPqIAJHpxEMV/VjIsCoZGZ3vh02MD+EvIl7DFYmvcHprsnyw4kJ6oy4QfUqmbttBkeDocYl9w2ofuXh119aUYoqflazUUWPvclyoh/tanwvMk2zoD6zBFhQBdXIrG9ONqEpIWTMF87Uw/SMnQ0PCmwx"
}

3.8 Query Transaction Status​

  • Action: TransactionStatus
  • Pin Code: pinCode2

Request "data.body" structure​

VariableTypeRequiredDescription
targetReferenceIDStringYThe reference ID that was carried during the transaction made at that time.
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "18fd2b62-6f65-40f2-8b94-88ef32f07a3f",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "targetReferenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1"
  }
}
*/

{
  "version": 2.0,
  "action": "TransactionStatus",
  "data": "PFR7QydsxUlVYXFh9g7n1DKLUx5DtPLNOnSCCYIvZPAg9aZHx1rt6rNmW1BheI2MQO+Sq6G3LC4DlLxSQxTwOmN7mJREzckYVcnze9GhbENDP4tMmbLErjlU5lgctk9rkRYs/hNTZThfEd340c5JAM5JSPGSGyNZVs9Yf4FQa6hGxUcfW7RXu9dVntrHfPwuwg1A2vTSeh6QdQEgNJO+9jHygoD45RxiiMbPVFYkCMq5gve8Pcwwu950ADhTwK4kzKm2yyuZGjl7okuhAtnY3ADJ6nZzED94Q8fKRHs1VN7vnHyxIDVd9B0hNqLOacn3"
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
...AnyYIt is consistent with the returned information of the current query transaction type
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "responseID": "18fd2b62-6f65-40f2-8b94-88ef32f07a3f",
    "serverDeviceSN": "NEXGO-N96-1170270945",
    "timestamp": "2025-11-12T10:12:04+00:00"
  },
  "body": {
    "status": "Success",
    "errorCode": "",
    "errorMessage": "",
    "currency": "HKD",
    "amount": "10.20",
    "paymentMethod": "visa",
    "paymentEntryType": "contactless",
    "rrn": "3263492852830699521",
    "brn": "3263492852495159296",
    "transactionType": "Success",
    "transactionTime": "2023-06-30T09:08:52+00:00",
    "creditCard": {
      "panPrefix6Digits": "555555",
      "panLast4Digits": "1234",
      "consumerIdentify": "xxxxxxx"
    }
  }
}
*/

{
  "version": 2.0,
  "action": "VOSss8buM+a+5PbdwyLeAsAckCpeJX494TT5i3KZpApAft7cfLFPkaQJesUK+vnRQQKfmRCKfg2Bm3iKRe1Tj/E1OvkuS7qpP18ZVXu1Z4kouiyvJLayyUqw5Qodg8IB2xK9giFmrvm3Ss9EUbBUnyjSDcVw1jUxHqy4q59fxJ/LRKKNya+19YuqcXlKlpiHrAdsdjODiHTXVv0cDR3QSvGGmm3ZQPpK2DBnPuuUym39Gb5B9sgEn8Sv49GyYdx9l/RBBL6XSNDMKBMMQZ7xcj4LTDP2ksZxF1alhuugSCXWnxBiNpQb3HIa+lyQtT/TXt5miFPDG+EvYHKVrAqeEbLbKY3QUqPFr3AlX7QW06xsPdOrsFrafwMgasZaTLd4TFtAYDpuTxFrfpJbN/LLGMSjFq/uyn/NLDXGwPerKGSdjurdmQv6eJ5lBKcpLGePXmIKBkynSeC63iGUK3MI1gv0wqwNezcN/BtQM5t2yyv0FbxL3I+133x+VKV0uP1xYf5rZ8gpeKaRXUYEoBtb+LM7VhlDp5ZWumxzfHr8mVt4Z/ikvTmaEEAdpTdvllNDIw3YaBbRIjK1/y2qhZhx8ohULIg5aom0NjgVS9YWvp0G9sayeqYd+coQa9knBT7KHgOv/hJNQWZs6CZ1YIhjbpC9qhkbaCr8PNbRJHnJbrFMVO9QrSGXnD7Tjr5pXMVYeg+R3C/zicbKKcs7ZyWzp00x2/FdtvtzbPmYcXIRyG0="
}

3.9 Sale Directly​

  • Action: SaleDirectly
  • Pin Code: pinCode2
  • CMD: 0101

Request "data.body" structure​

VariableTypeRequiredDescription
referenceIDStringYReference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
qrCodeStringYThe QR code string
currencyStringYExample: HKD / USD / RMB
amountStringYSale amount
timeoutNumberNThe timeout in seconds. The default is 0, indicating that it will never time out
Example:​

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
  "header": {
    "requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
    "clientDeviceSN": "126498561093",
    "timestamp": "2025-11-12T10:11:04+00:00"
  },
  "body": {
    "referenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1",
    "qrCode": "22349671249672146346",
    "currency": "HKD",
    "amount": "10.20",
    "timeout": 120
  }
}
*/

{
  "version": "2.0",
  "action": "SaleDirectly",
  "data": "z/IjDI8eUlFKCTrCbtt4U1EbW77HfYZYglG6HApsR7xMJnhLVJF8BlyxQMjhR8ALMMLCu+HAGAL/WMrHo0BZPdwdCHyLQnqeEJX4F3wshkiBkw44XOrjk9H2UxYGwammnJF1WX5qFpHBqEsvc8TsDQ1tcpL/Xsb7Z8NyUYG4M/kIQDRXLwXHs1tohf6Xop4jhXOP+3VWJIkovUJo7pZi+voj0AwjpRofjUk9I/J5pgazU7UCX2Q8ag7j+rhj7XoNDj8GvhkL0OPFcWeEbjeunZBt0xAeOThYDV4B3v/+ycUIQ9u3vFbwnIcbzfX89hRkEmgtY1clCUv2xBFlbh1v25tx80/2tsycHYziWjct3TzW84SM80POcCso68rcQo8xqJokgt/kn/bZb2t8pxs4gviN0LK+324VDT5AzHJxhF4="
}

Response "data.body" structure​

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed
errorCodeStringN
errorMessageStringN
currencyStringYExample: HKD / USD / RMB
amountStringYSale amount
consumer_identify_hashStringY
acquirer_typeStringYAcquirer type