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

# Branch API

> Create and manage branches to organise payments, payment links, and direct debit contracts across locations or teams.

## Endpoints

| Method | Endpoint | Description | Rate Limit |
| - | - | - | - |
| POST | `/v1/branch` | Create a branch | 60 req/min |
| GET | `/v1/branch/list` | List branches | 200 req/min |
| GET | `/v1/branch/:id` | Get branch by ID | 300 req/min |
| PATCH | `/v1/branch/:id` | Update a branch | 60 req/min |
| DELETE | `/v1/branch/:id` | Deactivate a branch | 30 req/min |

***

## Create Branch

Creates a new branch under the authenticated merchant. All API-created branches automatically use the merchant's bank account for settlements.

```
POST /v1/branch
```

### Authentication

Requires [HMAC authentication](https://docs.ceypay.io/api/v1/authentication.md) with headers:

* `x-api-key`: Your API key ID only (e.g., `ak_live_xxx`)
* `x-timestamp`: Current Unix timestamp in milliseconds
* `x-signature`: HMAC-SHA256 signature (using derived signing key)

### Request Body

| Field | Type | Required | Max Length | Description |
| - | - | - | - | - |
| `name` | string | Yes | 255 | Branch name |
| `code` | string | Yes | 50 | Unique code within the merchant |
| `address` | string | No | 255 | Street address |
| `city` | string | No | 100 | City |
| `postalCode` | string | No | 20 | Postal code |
| `phone` | string | No | 20 | Contact phone |
| `telegramGroupId` | string | No | 50 | Telegram group for notifications |

### Example Request

```bash theme={null}
curl -X POST "https://api.ceypay.io/v1/branch" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here" \
  -d '{
    "name": "Colombo Main Branch",
    "code": "COL-MAIN",
    "address": "123 Galle Road",
    "city": "Colombo",
    "postalCode": "00300",
    "phone": "+94112345678",
    "telegramGroupId": "-1001234567890"
  }'
```

### Example Response (201 Created)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "merchantId": "merchant_12345",
  "name": "Colombo Main Branch",
  "code": "COL-MAIN",
  "address": "123 Galle Road",
  "city": "Colombo",
  "postalCode": "00300",
  "phone": "+94112345678",
  "telegramGroupId": "-1001234567890",
  "isActive": true,
  "usesMerchantBankAccount": true,
  "createdAt": "2026-04-17T10:30:00.000Z",
  "updatedAt": "2026-04-17T10:30:00.000Z"
}
```

### Error Responses

| Status | Description |
| - | - |
| 400 | Bad request — validation error |
| 401 | Unauthorized — invalid HMAC signature |
| 409 | Conflict — branch code already exists |
| 429 | Too many requests — rate limit exceeded |

***

## List Branches

Retrieves a paginated list of branches for the authenticated merchant. Supports filtering by active status and searching by name or code.

```
GET /v1/branch/list
```

### Authentication

Requires [HMAC authentication](https://docs.ceypay.io/api/v1/authentication.md) with headers:

* `x-api-key`: Your API key ID only (e.g., `ak_live_xxx`)
* `x-timestamp`: Current Unix timestamp in milliseconds
* `x-signature`: HMAC-SHA256 signature (using derived signing key)

### Query Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `page` | integer | 1 | Page number |
| `limit` | integer | 20 | Items per page |
| `search` | string | — | Search by name or code |
| `isActive` | `"true"` \| `"false"` | — | Filter by active status |
| `sortBy` | string | `created_at` | Sort field |
| `sortOrder` | `"asc"` \| `"desc"` | `desc` | Sort direction |

### Example Request

```bash theme={null}
curl "https://api.ceypay.io/v1/branch/list?page=1&limit=20&isActive=true" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here"
```

### Example Response (200 OK)

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "merchantId": "merchant_12345",
      "name": "Colombo Main Branch",
      "code": "COL-MAIN",
      "city": "Colombo",
      "isActive": true,
      "usesMerchantBankAccount": true,
      "createdAt": "2026-04-17T10:30:00.000Z",
      "updatedAt": "2026-04-17T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "totalItems": 5,
    "totalPages": 1
  }
}
```

### Error Responses

| Status | Description |
| - | - |
| 401 | Unauthorized — invalid HMAC signature |
| 429 | Too many requests — rate limit exceeded |

***

## Get Branch

Retrieves a single branch by ID. Only returns branches belonging to the authenticated merchant.

```
GET /v1/branch/:id
```

### Authentication

Requires [HMAC authentication](https://docs.ceypay.io/api/v1/authentication.md) with headers:

* `x-api-key`: Your API key ID only (e.g., `ak_live_xxx`)
* `x-timestamp`: Current Unix timestamp in milliseconds
* `x-signature`: HMAC-SHA256 signature (using derived signing key)

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string (UUID) | Yes | Branch ID |

### Example Request

```bash theme={null}
curl "https://api.ceypay.io/v1/branch/550e8400-e29b-41d4-a716-446655440010" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here"
```

### Example Response (200 OK)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "merchantId": "merchant_12345",
  "name": "Colombo Main Branch",
  "code": "COL-MAIN",
  "address": "123 Galle Road",
  "city": "Colombo",
  "postalCode": "00300",
  "phone": "+94112345678",
  "telegramGroupId": "-1001234567890",
  "isActive": true,
  "usesMerchantBankAccount": true,
  "createdAt": "2026-04-17T10:30:00.000Z",
  "updatedAt": "2026-04-17T10:30:00.000Z"
}
```

### Error Responses

| Status | Description |
| - | - |
| 401 | Unauthorized — invalid HMAC signature |
| 403 | Forbidden — branch belongs to another merchant |
| 404 | Branch not found |
| 429 | Too many requests — rate limit exceeded |

***

## Update Branch

Updates an existing branch. All fields are optional — only include fields you want to change.

```
PATCH /v1/branch/:id
```

### Authentication

Requires [HMAC authentication](https://docs.ceypay.io/api/v1/authentication.md) with headers:

* `x-api-key`: Your API key ID only (e.g., `ak_live_xxx`)
* `x-timestamp`: Current Unix timestamp in milliseconds
* `x-signature`: HMAC-SHA256 signature (using derived signing key)

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string (UUID) | Yes | Branch ID |

### Request Body

All fields are optional.

| Field | Type | Max Length | Description |
| - | - | - | - |
| `name` | string | 255 | Branch name |
| `code` | string | 50 | Unique code within the merchant |
| `address` | string | 255 | Street address |
| `city` | string | 100 | City |
| `postalCode` | string | 20 | Postal code |
| `phone` | string | 20 | Contact phone |
| `telegramGroupId` | string | 50 | Telegram group for notifications |

### Example Request

```bash theme={null}
curl -X PATCH "https://api.ceypay.io/v1/branch/550e8400-e29b-41d4-a716-446655440010" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here" \
  -d '{
    "phone": "+94117654321",
    "telegramGroupId": "-1009876543210"
  }'
```

### Example Response (200 OK)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "merchantId": "merchant_12345",
  "name": "Colombo Main Branch",
  "code": "COL-MAIN",
  "address": "123 Galle Road",
  "city": "Colombo",
  "postalCode": "00300",
  "phone": "+94117654321",
  "telegramGroupId": "-1009876543210",
  "isActive": true,
  "usesMerchantBankAccount": true,
  "createdAt": "2026-04-17T10:30:00.000Z",
  "updatedAt": "2026-04-17T11:00:00.000Z"
}
```

### Error Responses

| Status | Description |
| - | - |
| 400 | Bad request — validation error |
| 401 | Unauthorized — invalid HMAC signature |
| 404 | Branch not found |
| 409 | Conflict — branch code already in use |
| 429 | Too many requests — rate limit exceeded |

***

## Deactivate Branch

Deactivates a branch. This is a soft delete — the branch record and its associated payment history are preserved.

```
DELETE /v1/branch/:id
```

### Authentication

Requires [HMAC authentication](https://docs.ceypay.io/api/v1/authentication.md) with headers:

* `x-api-key`: Your API key ID only (e.g., `ak_live_xxx`)
* `x-timestamp`: Current Unix timestamp in milliseconds
* `x-signature`: HMAC-SHA256 signature (using derived signing key)

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string (UUID) | Yes | Branch ID |

### Example Request

```bash theme={null}
curl -X DELETE "https://api.ceypay.io/v1/branch/550e8400-e29b-41d4-a716-446655440010" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here"
```

### Response (204 No Content)

No response body.

### Error Responses

| Status | Description |
| - | - |
| 401 | Unauthorized — invalid HMAC signature |
| 404 | Branch not found |
| 429 | Too many requests — rate limit exceeded |

***

## Branch Object

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Branch ID |
| `merchantId` | UUID | Owning merchant |
| `name` | string | Branch name |
| `code` | string | Unique code within the merchant |
| `address` | string? | Street address |
| `city` | string? | City |
| `postalCode` | string? | Postal code |
| `phone` | string? | Contact phone |
| `telegramGroupId` | string? | Telegram group for notifications |
| `isActive` | boolean | Whether the branch is active |
| `usesMerchantBankAccount` | boolean | Always `true` for API-created branches |
| `createdAt` | ISO 8601 | Creation timestamp |
| `updatedAt` | ISO 8601 | Last update timestamp |

***

## Error Responses

| Status | Error | Description |
| - | - | - |
| 400 | Bad Request | Invalid request body or validation error |
| 401 | Unauthorized | Invalid API key or signature |
| 403 | Forbidden | Branch belongs to another merchant |
| 404 | Not Found | Branch not found |
| 409 | Conflict | Branch code already exists |
| 429 | Too Many Requests | Rate limit exceeded |

See [Error Codes](https://docs.ceypay.io/api/v1/errors.md) for detailed error handling.

***

## Related Documentation

* [Quick Start](https://docs.ceypay.io/api/v1/quickstart.md) - Getting started guide
* [Authentication](https://docs.ceypay.io/api/v1/authentication.md) - HMAC signature details
* [Payments](https://docs.ceypay.io/api/v1/payments.md) - Accept payments via branches
* [Payment Links](https://docs.ceypay.io/api/v1/payment-links.md) - Assign payment links to branches
* [Direct Debit](https://docs.ceypay.io/api/v1/direct-debit.md) - Associate contracts with branches
* [Rate Limits](https://docs.ceypay.io/api/v1/rate-limits.md) - API rate limiting
* [Errors](https://docs.ceypay.io/api/v1/errors.md) - Error codes reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.