Branches

Branches represent physical store locations for a merchant. Each branch can have its own POS terminals and payment settings.

Create Branch

POST /v1/branches

Requires a valid Bearer token in the Authorization header.

Request Body

string

required

Branch display name (e.g., Colombo Main Store).

string

required

Physical address of the branch.

string

required

City where the branch is located.

string

Branch contact phone number.

Example Request

{
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678"
}

Example Response (201)

{
  "id": "branch_abc123",
  "merchantId": "merch_abc123",
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678",
  "status": "active",
  "createdAt": "2026-03-26T10:00:00Z"
}

List Branches

GET /v1/branches

Returns all branches for the authenticated merchant.

Query Parameters

integer

default:"1"

Page number.

integer

default:"20"

Items per page (max 100).

Example Response (200)

{
  "data": [
    {
      "id": "branch_abc123",
      "name": "Colombo Main Store",
      "address": "123 Galle Road, Colombo 03",
      "city": "Colombo",
      "status": "active",
      "createdAt": "2026-03-26T10:00:00Z"
    },
    {
      "id": "branch_def456",
      "name": "Kandy Branch",
      "address": "45 Peradeniya Road, Kandy",
      "city": "Kandy",
      "status": "active",
      "createdAt": "2026-03-20T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Get Branch

GET /v1/branches/{id}

Path Parameters

string

required

The branch identifier (e.g., branch_abc123).

Example Response (200)

{
  "id": "branch_abc123",
  "merchantId": "merch_abc123",
  "name": "Colombo Main Store",
  "address": "123 Galle Road, Colombo 03",
  "city": "Colombo",
  "phone": "+94112345678",
  "status": "active",
  "createdAt": "2026-03-26T10:00:00Z",
  "updatedAt": "2026-03-26T10:00:00Z"
}

Delete Branch

DELETE /v1/branches/{id}

Permanently deletes a branch. Active POS terminals associated with the branch will be deactivated.

Path Parameters

string

required

The branch identifier (e.g., branch_abc123).

Example Response (200)

{
  "message": "Branch deleted successfully"
}

Error Responses

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Branch not found"
  }
}

Overview

Authentication

Merchants

Payments

Checkout Sessions

Settlements

Webhooks

Subscriptions

Direct Debit

Refunds

Exchange Rates

Admin

Create Branch

Request Body

Example Request

Example Response (201)

List Branches

Query Parameters

Example Response (200)

Get Branch

Path Parameters

Example Response (200)

Delete Branch

Path Parameters

Example Response (200)

Error Responses

​Create Branch

​Request Body

​Example Request

​Example Response (201)

​List Branches

​Query Parameters

​Example Response (200)

​Get Branch

​Path Parameters

​Example Response (200)

​Delete Branch

​Path Parameters

​Example Response (200)

​Error Responses

Create Branch

Request Body

Example Request

Example Response (201)

List Branches

Query Parameters

Example Response (200)

Get Branch

Path Parameters

Example Response (200)

Delete Branch

Path Parameters

Example Response (200)

Error Responses