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 these credentials securely!
console.log('API Key:', result.apiKey);
console.log('Webhook Secret:', result.webhookSecret);
console.log('Merchant ID:', result.merchant.id);
console.log('Name:', result.merchant.name);

// Create authenticated client with webhook secret
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!)
webhookSecret string Webhook signing secret (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'
});

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;
  webhookSecret: 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 credentials securely (e.g., in database)
    await saveCredentialsToDatabase(result.merchant.id, result.apiKey, result.webhookSecret);

    // 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