Docs
Powered by

# Merchants API

Register and manage merchant accounts using the SDK.

# Register Merchant

Create a new merchant account (no API key required):

import { HivePay } from '@hivepay/client';

// No API key needed for registration
const publicClient = new HivePay();

const result = await publicClient.merchants.register({
  name: 'My Store',
  hiveAccount: 'mystore',
  iconUrl: 'https://example.com/logo.png'  // Optional
});

// IMPORTANT: Save this API key securely!
console.log('API Key:', result.apiKey);
console.log('Merchant ID:', result.merchant.id);
console.log('Name:', result.merchant.name);

// Create authenticated client
const hivepay = publicClient.withApiKey(result.apiKey);

# Parameters

Parameter Type Required Description
name string Yes Business name (displayed to customers)
hiveAccount string Yes Hive username for receiving payments
iconUrl string No URL to logo image

# Response

Field Type Description
apiKey string New API key (save immediately!)
merchant Merchant Created merchant object

# Get Current Merchant

Get the merchant associated with the current API key:

const merchant = await hivepay.merchants.getCurrent();

console.log(merchant.id);          // Merchant ID
console.log(merchant.name);        // Business name
console.log(merchant.hiveAccount); // Hive username
console.log(merchant.iconUrl);     // Logo URL
console.log(merchant.webhookUrl);  // Webhook endpoint
console.log(merchant.isActive);    // Active status
console.log(merchant.createdAt);   // Registration date

# Get Merchant by ID

Retrieve a specific merchant's public information:

const merchant = await hivepay.merchants.get('merchant_id');

console.log(merchant.name);
console.log(merchant.isActive);

# Update Merchant

Update merchant settings:

const updated = await hivepay.merchants.update('merchant_id', {
  iconUrl: 'https://example.com/new-logo.png',
  webhookUrl: 'https://example.com/webhooks/hivepay',
  hiveAccount: 'newaccount'
});

console.log('Updated:', updated.name);

# Updatable Fields

Field Type Description
iconUrl string Logo/icon URL
webhookUrl string Webhook endpoint URL
hiveAccount string Hive account for payments

# Using withApiKey

Create a new client with a different API key:

const publicClient = new HivePay();

// After registration
const result = await publicClient.merchants.register({
  name: 'My Store',
  hiveAccount: 'mystore'
});

// Create authenticated client
const authClient = publicClient.withApiKey(result.apiKey);

// Now use the authenticated client
const payment = await authClient.payments.create({
  amount: '10500',
  currency: 'HBD',
  description: 'Order #123'
});

# Admin Operations

Admin endpoints require elevated privileges:

# List All Merchants 

// Paginated list
const result = await hivepay.admin.listMerchants({
  page: 1,
  limit: 50,
  query: 'store'  // Optional search
});

console.log(result.data);        // Merchant[]
console.log(result.pagination);  // Pagination info

# Iterate All Merchants 

// Iterate through all merchants
for await (const merchant of hivepay.admin.iterateMerchants()) {
  console.log(merchant.id, merchant.name, merchant.isActive);
}

// With search and custom page size
for await (const merchant of hivepay.admin.iterateMerchants({
  query: 'store',
  pageSize: 50
})) {
  // Process merchant
}

# Activate/Deactivate Merchant 

// Activate a merchant
await hivepay.admin.setActive('merchant_id', true);

// Deactivate a merchant
await hivepay.admin.setActive('merchant_id', false);

# Type Definitions

# Merchant 

interface Merchant {
  id: string;
  name: string;
  hiveAccount: string;
  iconUrl: string | null;
  webhookUrl: string | null;
  isActive: boolean;
  createdAt: Date;
}

# RegisterResult 

interface RegisterResult {
  apiKey: string;
  merchant: Merchant;
}

# Examples

# Complete Registration Flow 

import { HivePay, isHivePayError } from '@hivepay/client';

async function registerMerchant(data: {
  name: string;
  hiveAccount: string;
  iconUrl?: string;
}) {
  const publicClient = new HivePay();

  try {
    const result = await publicClient.merchants.register(data);

    // Store API key securely (e.g., in database)
    await saveApiKeyToDatabase(result.merchant.id, result.apiKey);

    // Return client for immediate use
    return {
      merchant: result.merchant,
      client: publicClient.withApiKey(result.apiKey)
    };
  } catch (error) {
    if (isHivePayError(error) && error.isValidation()) {
      throw new Error(`Invalid data: ${error.message}`);
    }
    throw error;
  }
}

# Configure Webhooks After Registration 

async function setupMerchant(apiKey: string, webhookUrl: string) {
  const hivepay = new HivePay({ apiKey });

  // Get current merchant
  const merchant = await hivepay.merchants.getCurrent();

  // Configure webhook
  await hivepay.merchants.update(merchant.id, {
    webhookUrl
  });

  console.log('Webhook configured for', merchant.name);
}

HivePay © 2026