Widget SDK

Display Modes

The widget can be shown in two modes:

• Modal: Overlay modal on top of the current page (recommended)
• Window: Open in a new tab or popup window

Step 1: Load the SDK

<script src="https://widget.cryptoments.cc/sdk/widget.cryptoments.js" type="module"></script>
<script type="module">
  window.CryptoPaymentsWidget = CryptoPaymentsWidget;
</script>

Step 2: Initialize

const widget = new CryptoPaymentsWidget({
  mode: 'window',        // 'window' | 'modal'
  widgetType: 'deposit', // 'deposit' | 'withdrawal' | 'connect'
  debug: false,
  onSuccess: (result) => console.log('Done:', result),
  onError: (error) => console.error('Error:', error),
  onClose: () => console.log('Widget closed')
});

Step 3: Open the Widget

// Open deposit widget
await widget.openDeposit('user_001');

// Open withdrawal widget
await widget.openWithdrawal('user_001');

// Connect wallet
await widget.openConnect('user_001');

Client-Side

The SDK exposes a global window.CryptoPaymentsWidget object. No additional install step is required.

Server-Side — Generate Widget Tokens

For security, generate the widget auth token on your server and pass it to the client.

Node.js Example

const crypto = require('crypto');

const PARTNER_CONFIG = {
  apiKey: 'your_api_key',
  apiSecret: 'your_api_secret'
};

// Widget token issuance endpoint
app.post('/api/get-widget-token', async (req, res) => {
  const { partnerUserId, permissions } = req.body;
  // Timestamp (seconds)
  const timestamp = Math.floor(Date.now() / 1000).toString();

  // Signature: METHOD + PATH + TIMESTAMP
  const message = 'POST' + '/widgets/auth/token' + timestamp;
  const signature = crypto.createHmac('sha256', PARTNER_CONFIG.apiSecret)
    .update(message).digest('hex');

  const response = await fetch('https://api.cryptoments.cc/widgets/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': PARTNER_CONFIG.apiKey,
      'X-TIMESTAMP': timestamp,
      'X-SIGNATURE': signature
    },
    body: JSON.stringify({
      partnerUserId,
      permissions: permissions || ['DEPOSIT_READ', 'WITHDRAWAL_REQUEST', 'BALANCE_READ']
    })
  });

  const tokenData = await response.json();
  res.json(tokenData);
});

Java/Spring Example

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

@RestController
@RequestMapping("/api")
public class WidgetController {

    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_api_secret";

    @PostMapping("/get-widget-token")
    public ResponseEntity<?> generateWidgetToken(@RequestBody WidgetTokenRequest req) throws Exception {
        // Timestamp (seconds)
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);

        // Signature: METHOD + PATH + TIMESTAMP
        String message = "POST" + "/widgets/auth/token" + timestamp;
        String signature = hmacSha256Hex(message, API_SECRET);

        String requestBody = "{\"partnerUserId\":\"" + req.getPartnerUserId() +
                            "\",\"permissions\":" + req.getPermissions() + "}";

        HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://api.cryptoments.cc/widgets/auth/token"))
            .header("Content-Type", "application/json")
            .header("X-API-KEY", API_KEY)
            .header("X-TIMESTAMP", timestamp)
            .header("X-SIGNATURE", signature)
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(httpRequest, HttpResponse.BodyHandlers.ofString());

        return ResponseEntity.ok(response.body());
    }

    private String hmacSha256Hex(String message, String secret) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
            byte[] bytes = mac.doFinal(message.getBytes());
            StringBuilder sb = new StringBuilder();
            for (byte b : bytes) sb.append(String.format("%02x", b));
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

Using the Token in the Client

The SDK automatically requests the token from partnerApiUrl. You don't need to manage tokens yourself.

// SDK auto-issues the token when openDeposit/openWithdrawal/openConnect is called
const widget = new CryptoPaymentsWidget({
  partnerApiUrl: '/api/get-widget-token', // Server endpoint (default)
  mode: 'window',
  onSuccess: (result) => console.log('Done:', result)
});

// Token issuance + widget open handled automatically
await widget.openDeposit('user_001');

Configuration Example

const widget = new CryptoPaymentsWidget({
  // Basic settings
  mode: 'modal',
  widgetType: 'deposit',
  partnerApiUrl: '/api/get-widget-token',
  debug: false,

  // Common options
  language: 'ko',             // 'ko' | 'en' (default 'ko')
  chainType: 'BSC',
  presetAmount: 50000,
  presetAmountCurrency: 'KRW',
  minAmount: 10000,
  maxAmount: 500000,
  allowAmountEdit: true,
  skipInput: false,

  // Deposit only
  amountOptions: [10000, 50000, 100000, 500000],
  orderId: 'ORDER-20260721-001',  // Partner order ID (returned in onSuccess & webhook)

  // Callbacks
  onSuccess: (result) => {
    if (result.type === 'deposit') {
      console.log(`Deposit complete: ${result.address} (${result.chainType}) order=${result.orderId}`);
    } else if (result.type === 'withdrawal') {
      console.log(`Withdrawal complete: TX ${result.transactionId}`);
    } else if (result.type === 'connect') {
      console.log(`Wallet connected: ${result.address}`);
    } else if (result.type === 'axim_payment') {
      console.log('Axim payment complete:', result);
    } else if (result.type === 'p2p') {
      console.log(`KRW top-up (P2P) complete: ${result.usdtAmount} USDT (orderCode: ${result.orderCode}, matches: ${result.matchCount})`);
    } else if (result.type === 'torq') {
      console.log(`KRW top-up (TORQ fallback) complete: ${result.usdtAmount} USDT (escrowId: ${result.escrowId})`);
    }
  },
  onError: (error) => console.error('Error:', error.message),
  onClose: () => console.log('Widget closed')
});

Method Usage Example

// Open deposit widget
await widget.openDeposit('user_001', {
  chainType: 'BSC',
  presetAmount: 50000,
  amountOptions: [10000, 50000, 100000]
});

// Open withdrawal widget
await widget.openWithdrawal('user_001', {
  showBalance: true,
  reqWithdraw: async (data) => {
    const res = await fetch('/api/process-withdrawal', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ withdrawalData: data })
    });
    return res.json();
  }
});

// Wallet-connect widget
await widget.openConnect('user_001');

// Close widget
widget.close();

How to Use Events

Register events via addEventListener.

// Register an event listener
const listenerId = widget.addEventListener('depositCompleted', (event) => {
  console.log('Deposit complete:', event.data);
});

// Remove the listener
widget.removeEventListener('depositCompleted', listenerId);

Event Flow

iframe (widget UI)
    ↓ postMessage
SDK (handleWidgetMessage)
    ↓
emit(event)
    ↓
addEventListener callback fires

Key Events

Real-world Example

// Handle deposit completion
widget.addEventListener('depositCompleted', (e) => {
  console.log('Deposit complete:', e.data);

  // Persist on server
  fetch('/api/deposit-complete', {
    method: 'POST',
    body: JSON.stringify(e.data)
  });
});

// Withdrawal complete
widget.addEventListener('withdrawalCompleted', (e) => {
  console.log('Withdrawal complete:', e.data);
});

// KRW top-up complete (P2P matching)
widget.addEventListener('p2pTopupCompleted', (e) => {
  console.log('KRW top-up complete:', e.data.usdtAmount, 'USDT');
});

// Axim payment success
widget.addEventListener('aximPaymentSuccess', (e) => {
  console.log('Axim payment success:', e.data);
});

// Error handling
widget.addEventListener('error', (e) => {
  console.error('Error:', e.data);
});

Deposit

The widget where users deposit USDT. The user picks a payment method (Axim Pay / Direct crypto deposit / KRW top-up payment), receives a deposit address, and sends.

await widget.openDeposit('user_001', {
  // Amount
  presetAmount: 50000,              // Preset amount
  presetAmountCurrency: 'KRW',      // preset unit: 'KRW' | 'USD' (default 'USD')
  minAmount: 10,                    // Minimum amount (USDT basis, default 10)
  maxAmount: 100000,               // Maximum amount (USDT basis, default 100000)
  allowAmountEdit: true,           // Allow manual amount edit (default true)
  amountOptions: [10000, 50000, 100000], // Quick amount buttons (KRW)
  fixedRateKrw: 1400,              // Fixed FX rate (defaults to live rate if unset)

  // Network
  chainType: 'BSC',               // Pin network (defaults to user choice if unset)

  // UX
  skipInput: false,               // true: skip the amount-input screen (presetAmount required)


});

Deposit Flow Overview:

When no P2P counterpart is available, the flow automatically falls back to a TORQ LP full-amount top-up (single LP).

Axim Pay

Direct Crypto Payment

KRW Top-up Payment

The deposit branch entered when the user picks KRW top-up payment on the payment method screen. After wallet connect and eKYC, the request is routed through P2P cross-site matching: the user is matched with one or more sellers (LPs) and sends KRW by bank transfer to each matched account, then the USDT is credited. This card is shown by default (no option needed).

Withdrawal

The widget where the user requests a USDT withdrawal to an external wallet. Withdrawals are processed after partner-side approval.

await widget.openWithdrawal('user_001', {
  // Amount
  presetAmount: 50000,              // Preset amount
  presetAmountCurrency: 'KRW',      // preset unit: 'KRW' | 'USD' (default 'USD')
  minAmount: 10,                    // Minimum amount (USDT basis, default 10)
  maxAmount: 100000,               // Maximum amount (USDT basis, default 100000)
  allowAmountEdit: true,           // Allow manual amount edit (default true)
  fixedRateKrw: 1400,              // Fixed FX rate (defaults to live rate if unset)

  // Network
  chainType: 'BSC',               // Pin network (defaults to user choice if unset)

  // UX
  skipInput: false,               // true: skip the amount input (presetAmount required)
  showBalance: true,              // Show available balance (default true)

  // Withdrawal request callback (required)
  reqWithdraw: async (data) => {
    // data: { userId, chainType, currencyType, toAddress, amountCrypto, amountKrw, exchangeRate }
    const res = await fetch('/api/withdraw', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    const result = await res.json();
    return result.success === true;  // return true on success, false/throw to show the failure screen
  }
});

Screen Flow:

Wallet Connect

The widget for connecting Axim Wallet to the partner account. Once connected, Axim Pay/Wallet payments and withdrawals become available.

await widget.openConnect('user_001');

Screen Flow:

Events: the following events are emitted by the Axim SDK.

• aximConnectionRequested: connection request sent
• aximConnectionSuccess: connection succeeded (after which checkAximConnectionStatus updates automatically)
• aximConnectionFailed: connection failed

How to Receive Errors

Errors can be received in two ways.

• onError callback
• error event listener

// 1. onError callback
const widget = new CryptoPaymentsWidget({
  ...config,
  onError: (error) => {
    console.error('Widget Error:', error);
  }
});

// 2. Event listener
widget.addEventListener('error', (event) => {
  console.error('Widget Error:', event.data);
});

Error Object Shape

Errors are delivered with the following shape.

{
  "message": "Error message"
}

Common Error Codes

Basic Error Handling Example

const widget = new CryptoPaymentsWidget({
  ...config,

  onError: (error) => {
    const message = error?.message || 'An error occurred.';
    console.log(message);
  }
});

Retry Handling

Transient issues like network errors can be resolved with retries.

async function openDepositWithRetry(userId, retry = 2) {
  try {
    await widget.openDeposit(userId);
  } catch (error) {
    if (retry > 0) {
      console.log('Retrying...', retry);
      setTimeout(() => {
        openDepositWithRetry(userId, retry - 1);
      }, 2000);
    } else {
      console.error('Final failure:', error);
    }
  }
}

The widget doesn't open

1. Verify the SDK loaded successfully
2. Verify the CryptoPaymentsWidget object exists
3. Check the browser console (F12) for errors
4. Verify the partnerApiUrl server is responding normally

Events don't fire

1. Verify the listener is registered via addEventListener
2. Verify the event name is correct (case-sensitive)
3. Verify the listener is registered before opening the widget
4. Inspect the full flow via the message event

// For debugging (see all events)
widget.addEventListener('message', (e) => {
  console.log('EVENT:', e);
});

Token-related errors

1. Verify the server's partnerApiUrl endpoint is operating correctly
2. Verify the API Key / Secret are correct
3. Verify the server time is accurate (to avoid timestamp errors)

CORS errors

1. Verify the current domain is in the allowed Whitelist
2. Verify the protocol is included (https://)
3. After configuration changes, allow some propagation time

Deposits aren't being detected

1. Verify you sent on the correct network (chain)
2. Verify the deposit address is correct
3. Verify the amount meets the minimum
4. Allow on-chain confirmation time (typically 1–5 minutes)

Withdrawals fail

1. Verify reqWithdraw is implemented
2. Verify your server API is responding normally
3. Verify the balance is sufficient
4. Verify the wallet address is correct

KRW top-up payment doesn't proceed

1. The "KRW top-up payment" card is shown by default. If it's disabled (un-clickable), verify a KRW amount has been entered — the card requires an amount to be active
2. KRW top-up requires wallet connect + eKYC first. If the flow is stuck on the connect / eKYC screen, complete connection and verification in the Axim Wallet app (both are polled and advance automatically)
3. When the pre-match step looks like a "CORS error": it's usually not actually CORS but a 502 from upstream because the amount is below the 10,000 KRW minimum. Enter 10,000 KRW or more.
4. If it lands on a failure screen with NO_LP (no liquidity), no P2P counterpart was available and the TORQ LP fallback also had no liquidity — retry later
5. If "Verifying" persists after a transfer, you're waiting for the seller (LP) to confirm the deposit (test transfers don't actually arrive and won't complete)