Merchant Verticals

Verticals turn a generic store into a purpose-built system — restaurants, bars, events, retail, or service businesses. Assigning a vertical stamps its feature set and default configuration onto the merchant, tailoring the payment moments and workflow tooling the store exposes.

Available verticals

GullyPay ships five platform vertical templates. Each is a fixed capability set — a list of features plus default config values.

Vertical	Features
Restaurant	qr_ordering, table_management, split_payments, tipping, kitchen_display
Bar	tabs, group_payments, bottle_service, tipping, age_verification
Event	ticketing, qr_scanning, vip_upgrades, resale_control, capacity_management
Retail	pos_checkout, inventory, loyalty, barcode_scanning, returns
Service	bookings, deposits, subscriptions, calendar, reminders

Templates are platform constants

The five vertical templates and their feature sets are fixed platform configuration, not merchant-editable data. Assigning a vertical copies its features and default config onto the merchant's merchant_verticals record, where store tooling reads them.

Endpoints

GET/verticalsList all available vertical templates with feature sets and default config

GET/verticals/templates/:verticalGet a single vertical template's features and default config

GET/verticals/merchants/:merchantIdGet a merchant's current vertical assignment (or null)

POST/verticals/merchants/:merchantIdAssign or change a merchant's vertical

Authentication

The three GET reads are public and require no auth. POST /verticals/merchants/:merchantId requires a Bearer JWT (Authorization: Bearer <token>).

GET /verticals

Returns every vertical template. Public.

Response

[
{
  "id": "restaurant",
  "name": "Restaurant",
  "features": ["qr_ordering", "table_management", "split_payments", "tipping", "kitchen_display"],
  "config": { "tipOptions": [15, 18, 20, 25], "tableCount": 20, "qrMenuEnabled": true }
},
{
  "id": "bar",
  "name": "Bar",
  "features": ["tabs", "group_payments", "bottle_service", "tipping", "age_verification"],
  "config": { "tipOptions": [18, 20, 25], "tabAutoClose": true, "splitEnabled": true }
}
]

GET /verticals/templates/:vertical

Returns a single template, or null if the vertical id is unknown. Public.

Response — GET /verticals/templates/retail

{
"id": "retail",
"name": "Retail",
"features": ["pos_checkout", "inventory", "loyalty", "barcode_scanning", "returns"],
"config": { "loyaltyEnabled": true, "returnWindow": 30, "taxRate": 0.08 }
}

GET /verticals/merchants/:merchantId

Returns the merchant's current assignment, or null if none has been set.

Response

{
"id": "3f9c...",
"merchantId": "8a21...",
"vertical": "restaurant",
"config": { "tipOptions": [15, 18, 20, 25], "tableCount": 20, "qrMenuEnabled": true },
"features": ["qr_ordering", "table_management", "split_payments", "tipping", "kitchen_display"],
"createdAt": "2026-07-18T12:00:00.000Z",
"updatedAt": "2026-07-18T12:00:00.000Z"
}

POST /verticals/merchants/:merchantId

Assign a vertical to a merchant, or change the existing one. Requires a Bearer JWT. The body carries the vertical id; the server copies that template's features and config onto the assignment (upserting the merchant_verticals row).

Request Body

{
"vertical": "restaurant"
}

Field	Type	Required	Description
`vertical`	string	Yes	Template id — one of `restaurant`, `bar`, `event`, `retail`, `service`

Response

{
"merchantId": "8a21...",
"vertical": "restaurant",
"features": ["qr_ordering", "table_management", "split_payments", "tipping", "kitchen_display"],
"config": { "tipOptions": [15, 18, 20, 25], "tableCount": 20, "qrMenuEnabled": true }
}

An unknown vertical id returns { "error": "Unknown vertical" } without modifying any record.

Example

curl -X POST https://gullypay.xyz/api/verticals/merchants/8a21... \
-H "Authorization: Bearer $GULLYPAY_JWT" \
-H "Content-Type: application/json" \
-d '{"vertical":"restaurant"}'

Next steps

Merchants — create and manage merchant accounts
Payments — accept payments across every rail
Checkout — hosted and embedded checkout