Merchants API

Manage your merchant account.

Create Merchant

Create a new merchant account.

POST /api/merchants

Request

{
  "name": "my-store",
  "displayName": "My Store",
  "logoUrl": "https://mystore.com/logo.png"
}

Field	Type	Required	Description
name	string	Yes	Unique identifier (lowercase, no spaces)
displayName	string	No	Display name shown to users
logoUrl	string	No	URL to your logo

Response

{
  "success": true,
  "message": "Merchant created successfully",
  "responseObject": {
    "id": "merch_abc123",
    "name": "my-store",
    "displayName": "My Store",
    "logoUrl": "https://mystore.com/logo.png",
    "apiKey": "zkp_live_a1b2c3d4e5f6...",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

caution

The apiKey is only returned once. Store it securely - you cannot retrieve it later.

---

Get Merchant

Get your merchant account details.

GET /api/merchants/:id

Response

{
  "success": true,
  "responseObject": {
    "id": "merch_abc123",
    "name": "my-store",
    "displayName": "My Store",
    "logoUrl": "https://mystore.com/logo.png",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Note: The apiKey is never returned in GET requests.

---

Get Current Merchant

Get the merchant associated with your API key.

GET /api/merchants/me

Response

{
  "success": true,
  "responseObject": {
    "id": "merch_abc123",
    "name": "my-store",
    "displayName": "My Store",
    "logoUrl": "https://mystore.com/logo.png",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

---

Update Merchant

Update your merchant account.

PATCH /api/merchants/:id

Request

{
  "displayName": "My Updated Store",
  "logoUrl": "https://mystore.com/new-logo.png"
}

All fields are optional. Only provided fields are updated.

Response

{
  "success": true,
  "responseObject": {
    "id": "merch_abc123",
    "name": "my-store",
    "displayName": "My Updated Store",
    "logoUrl": "https://mystore.com/new-logo.png",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

---

Merchant Fields

Field	Type	Description
id	string	Unique merchant ID
name	string	Unique identifier (immutable)
displayName	string	Human-readable name
logoUrl	string	Logo URL for checkout UI
apiKey	string	API key (only on creation)
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

---

Usage Notes

• The name field cannot be changed after creation
• The apiKey is only returned when creating the merchant
• Use displayName for the name shown in the checkout UI
• The logoUrl should be a publicly accessible HTTPS URL
• Logo is displayed in the checkout header