> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taprails.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchants

> Provision and list sub-merchants under your company.

## List Merchants

`GET /merchants`

Retrieve a list of all merchants associated with your company and their current balances.

### Authentication

Requires a **Secret Key** (`sk_...`) in the `x-api-key` header or as a Bearer token in the `Authorization` header.

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.taprails.com/api/v1/management/merchants \
    -H "x-api-key: sk_live_your_key"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.taprails.com/api/v1/management/merchants', {
    headers: { 'x-api-key': process.env.TAPRAILS_SECRET_KEY }
  });
  const data = await res.json();
  ```
</CodeGroup>

### Response

The response is a JSON object containing an array of merchant objects.

| Field       | Type    | Description                 |
| :---------- | :------ | :-------------------------- |
| `merchants` | `array` | A list of merchant objects. |

#### Merchant Object

| Field            | Type     | Description                                                    |
| :--------------- | :------- | :------------------------------------------------------------- |
| `id`             | `string` | Unique identifier for the merchant (e.g., `mch_abc123`).       |
| `name`           | `string` | The merchant's name.                                           |
| `email`          | `string` | The merchant's contact email.                                  |
| `wallet_address` | `string` | The USDC wallet address provisioned for this merchant on Base. |
| `balance`        | `string` | Current USDC balance of the merchant's wallet.                 |
| `created_at`     | `string` | ISO 8601 timestamp of when the merchant was created.           |

### Sample Response

```json theme={null}
{
  "merchants": [
    {
      "id": "mch_abc123",
      "name": "Coffee Haven",
      "email": "owner@coffeehaven.com",
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "balance": "150.50",
      "created_at": "2026-03-28T22:33:53Z"
    },
    {
      "id": "mch_def456",
      "name": "The Juice Bar",
      "email": "billing@juicebar.io",
      "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
      "balance": "85.20",
      "created_at": "2026-03-29T10:15:00Z"
    }
  ]
}
```

***

## Create Merchant

`POST /merchants/create`

Creates a new merchant under your company and provisions a dedicated Privy embedded wallet for their funds.

### Request Body

| Field   | Type     | Required | Description                                       |
| :------ | :------- | :------- | :------------------------------------------------ |
| `name`  | `string` | Yes      | The merchant's legal or trade name (min 2 chars). |
| `email` | `string` | Yes      | Unique contact email for the merchant.            |

### Example Request

```bash theme={null}
curl -X POST https://api.taprails.com/api/v1/management/merchants/create \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Urban Eats",
    "email": "ops@urbaneats.com"
  }'
```

### Response

| Field      | Type     | Description                        |
| :--------- | :------- | :--------------------------------- |
| `merchant` | `object` | The newly created merchant object. |

#### Merchant Object (Create)

| Field            | Type     | Description                                             |
| :--------------- | :------- | :------------------------------------------------------ |
| `id`             | `string` | Unique identifier for the merchant.                     |
| `name`           | `string` | The merchant's name.                                    |
| `email`          | `string` | The merchant's email.                                   |
| `wallet_address` | `string` | The provisioned USDC wallet address.                    |
| `privy_user_id`  | `string` | The underlying Privy user ID for the merchant's wallet. |
| `balance`        | `string` | Initial balance (typically "0.00").                     |
| `environment`    | `string` | The environment (`test` or `live`).                     |
| `created_at`     | `string` | ISO 8601 timestamp.                                     |

### Sample Response

```json theme={null}
{
  "merchant": {
    "id": "mch_xyz789",
    "name": "Urban Eats",
    "email": "ops@urbaneats.com",
    "wallet_address": "0xabcdef1234567890abcdef1234567890abcdef",
    "privy_user_id": "did:privy:ckxyz789...",
    "balance": "0.00",
    "environment": "live",
    "created_at": "2026-03-31T01:15:00Z"
  }
}
```

### Errors

| Status | Code                 | Description                                |
| :----- | :------------------- | :----------------------------------------- |
| 400    | `VALIDATION_ERROR`   | Name too short or invalid email format.    |
| 400    | `DUPLICATE_RESOURCE` | A merchant with this email already exists. |
| 401    | `UNAUTHORIZED`       | Invalid or missing Secret Key.             |

***

## Merchant Ledger

`GET /merchants/:id/transactions`

Retrieve the complete financial history for a specific merchant, including atomic balance snapshots for every transaction. Useful for auditing and deep financial reconciliation.

### Query Parameters

| Parameter | Type     | Required | Description                                        |
| :-------- | :------- | :------- | :------------------------------------------------- |
| `limit`   | `number` | No       | Number of records to return (default 50, max 100). |

### Example Request

```bash theme={null}
curl https://api.taprails.com/api/v1/management/merchants/mch_xyz789/transactions?limit=25 \
  -H "x-api-key: sk_live_your_key"
```

### Sample Response

```json theme={null}
{
  "merchant_id": "mch_xyz789",
  "merchant_name": "Urban Eats",
  "total_count": 1,
  "transactions": [
    {
      "id": "tx_abc123",
      "type": "PAYMENT",
      "amount": "5.00",
      "balance_before": "100.00",
      "balance_after": "105.00",
      "payment_id": "pay_987654",
      "status": "COMPLETED",
      "description": "NFC Payment Received",
      "created_at": "2026-04-03T12:00:00Z"
    }
  ]
}
```

***

## Update Status

`PATCH /merchants/:id/status`

Pause or reactivate a merchant's ability to process payments. This is a self-service toggle for companies to manage their sub-merchants.

### Request Body

| Field    | Type     | Required | Description                                  |
| :------- | :------- | :------- | :------------------------------------------- |
| `status` | `string` | Yes      | The new status. Allowed: `ACTIVE`, `PAUSED`. |

### Example Request

```bash theme={null}
curl -X PATCH https://api.taprails.com/api/v1/management/merchants/mch_xyz789/status \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "PAUSED"
  }'
```

### Sample Response

```json theme={null}
{
  "id": "mch_xyz789",
  "name": "Urban Eats",
  "status": "PAUSED",
  "updated_at": "2026-04-04T15:00:00Z"
}
```

<Warning>
  **Platform Restrictions:** If a merchant has been set to `BLACKLISTED`, `FROZEN`, or `SUSPENDED` by the TapRails platform (e.g. for compliance or security reasons), you **cannot** override that status using this endpoint. You will receive a `403 Forbidden` error.
</Warning>