# Merchants API

Register and manage merchant accounts using the SDK.

---

## Register Merchant

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

+++ TypeScript
```typescript
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 |

!!!warning Save Your Credentials
The API key and webhook secret are shown only once during registration. Store both securely - they cannot be retrieved later. You can regenerate the webhook secret in the [Dashboard settings](/dashboard/settings/), but the API key requires contacting support.
!!!

---

## Get Current Merchant

Get the merchant associated with the current API key:

+++ TypeScript
```typescript
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:

+++ TypeScript
```typescript
const merchant = await hivepay.merchants.get('merchant_id');

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

---

## Update Merchant

Update merchant settings:

+++ TypeScript
```typescript
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 |

!!!info Note
You can only update merchants you own (matching API key).
!!!

---

## Using withApiKey

Create a new client with a different API key:

+++ TypeScript
```typescript
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

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

### RegisterResult

```typescript
interface RegisterResult {
  apiKey: string;
  webhookSecret: string;
  merchant: Merchant;
}
```

---

## Examples

### Complete Registration Flow

+++ TypeScript
```typescript
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

+++ TypeScript
```typescript
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);
}
```
+++