# Merchant API Reference

***

### **POST /merchants/signup**

Create a new merchant account.

#### Request

```bash
curl -X POST https://stacks-gateway-backend.onrender.com/merchants/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coffee Shop",
    "email": "owner@example.com",
    "password": "super-secret"
  }'
```

#### Response

```json
{
  "message": "Merchant account created successfully",
  "merchant": {
    "id": "merch_123",
    "name": "Coffee Shop",
    "email": "owner@example.com",
    "apiKey": "pk_live_abc",
    "apiSecret": "sk_live_xyz",
    "createdAt": "2025-08-18T17:30:00Z",
    "payoutStxAddress": null,
    "webhookSecret": null,
    "webhookUrl": null
  }
}
```

> ⚠️ **Note**: Store your `apiSecret` securely. It is required for **authentication when creating charges**.

***

### **POST /merchants/login**

Authenticate an existing merchant.\
Sets a `connect.sid` cookie for dashboard endpoints.

#### Request

```bash
curl -X POST https://stacks-gateway-backend.onrender.com/merchants/login \
  -H "Content-Type: application/json" \
  -c cookie.txt \
  -d '{
    "email": "owner@example.com",
    "password": "super-secret"
  }'
```

#### Response

```json
{
  "message": "Login successful",
  "merchant": {
    "id": "merch_123",
    "name": "Coffee Shop",
    "email": "owner@example.com",
    "apiKey": "pk_live_abc",
    "apiSecret": "sk_live_xyz",
    "payoutStxAddress": "STX123...",
    "webhookSecret": "whsec_123...",
    "webhookUrl": "https://merchant.com/webhook"
  }
}
```

***

### **PUT /merchants/config**

Update merchant settings like payout address and webhook configuration.\
Requires login (`connect.sid` cookie).

#### Request

```bash
curl -X PUT https://stacks-gateway-backend.onrender.com/merchants/config \
  -H "Content-Type: application/json" \
  -b cookie.txt \
  -d '{
    "payoutStxAddress": "STX123...",
    "webhookUrl": "https://merchant.com/webhook",
    "webhookSecret": "whsec_123..."
  }'
```

#### Response

```json
{
  "payoutStxAddress": "STX123...",
  "webhookUrl": "https://merchant.com/webhook",
  "webhookSecret": "whsec_123..."
}
```

***

### **POST /merchants/logout**

Destroy the session and clear cookies.

#### Request

```bash
curl -X POST https://stacks-gateway-backend.onrender.com/merchants/logout \
  -b cookie.txt
```

#### Response

```json
{ "message": "Logged out successfully" }
```

***

### **GET /merchants/me**

Return details of the authenticated merchant.\
Requires login (`connect.sid` cookie).

#### Request

```bash
curl -X GET https://stacks-gateway-backend.onrender.com/merchants/me \
  -b cookie.txt
```

#### Response

```json
{
  "id": "merch_123",
  "name": "Coffee Shop",
  "email": "owner@example.com",
  "apiKey": "pk_live_abc",
  "apiSecret": "sk_live_xyz",
  "payoutStxAddress": "STX123...",
  "webhookSecret": "whsec_123...",
  "webhookUrl": "https://merchant.com/webhook"
}
```

***

### **POST /merchants/api-secret/rotate**

Rotate the merchant’s `apiSecret`.\
Requires login (`connect.sid` cookie).

Rotating invalidates the old secret immediately and returns the new one.\
Use the new `apiSecret` for all future API requests that require authentication.

**Request**

```bash
curl -X POST https://stacks-gateway-backend.onrender.com/merchants/api-secret/rotate \
  -H "Content-Type: application/json" \
  -b cookie.txt
```

**Response**

```json
{
  "message": "secret rotated",
  "apiKey": "pk_live_abc",
  "apiSecret": "sk_live_new123"
}
```

> ⚠️ **Note**: The old secret is no longer valid after rotation.\
> Copy and securely store the new `apiSecret` — you will need it for charge creation and other API calls.

***

### **GET /merchants/charges**

List all charges created by the merchant (dashboard view).\
Requires login (`connect.sid` cookie).

#### Request

```bash
curl -X GET https://stacks-gateway-backend.onrender.com/merchants/charges \
  -b cookie.txt
```

#### Response

```json
{
  "charges": [
    {
      "chargeId": "8a1e20b2-...",
      "amountSbtc": 0.002,
      "amountUsd": 90.12,
      "status": "COMPLETED",
      "createdAt": "2025-08-18T17:40:00Z",
      "paidAt": "2025-08-18T17:45:00Z",
      "payerAddress":"ST123123VASD12",
      "payoutTxId": "abc123...",
      "order_id":"laptop",
      "failureReason": null
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://spay.gitbook.io/spay-docs/core-apis/merchant-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.