> ## 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.

# Payment Links API

> Accept payments without full checkout integration. Generate reusable or single-use payment links and share them via email, SMS, or social media.

## Endpoints

| Method | Endpoint                | Description               | Rate Limit  |
| ------ | ----------------------- | ------------------------- | ----------- |
| POST   | `/v1/payment-link`      | Create a new payment link | 50 req/min  |
| GET    | `/v1/payment-link/:id`  | Get payment link details  | 100 req/min |
| GET    | `/v1/payment-link/list` | List payment links        | 100 req/min |
| DELETE | `/v1/payment-link/:id`  | Deactivate a payment link | 50 req/min  |

***

## Create Payment Link

Create a new payment link.

```
POST /v1/payment-link
```

### Example Request

```bash theme={null}
curl -X POST "https://api.ceypay.io/v1/payment-link" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_live_abc123" \
  -H "x-timestamp: 1705315800000" \
  -H "x-signature: your_signature_here" \
  -d '{
    "merchantTradeNo": "ORDER-2025-001",
    "name": "Premium Subscription",
    "description": "Monthly premium plan subscription",
    "amount": 49.99,
    "currency": "USDT",
    "reusable": false,
    "allowCustomAmount": false,
    "allowQuantityBuy": true,
    "maxQuantity": 10,
    "successUrl": "https://yourstore.com/payment/success",
    "cancelUrl": "https://yourstore.com/payment/cancelled",
    "webhookUrl": "https://yourstore.com/webhooks/ceypay"
  }'
```

### Request Body

| Field               | Type    | Required | Description                                                                    |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `name`              | string  | Yes      | Name of the payment link.                                                      |
| `description`       | string  | No       | Description of the payment.                                                    |
| `amount`            | number  | No\*     | Fixed amount. Required if `allowCustomAmount` is false.                        |
| `currency`          | string  | Yes      | Currency code (e.g., `USDT`, `LKR`).                                           |
| `allowCustomAmount` | boolean | Yes      | Whether to allow customers to enter a custom amount. Default: `false`.         |
| `minAmount`         | number  | No\*     | Minimum amount for custom payments. Required if `allowCustomAmount` is true.   |
| `maxAmount`         | number  | No\*     | Maximum amount for custom payments. Required if `allowCustomAmount` is true.   |
| `allowQuantityBuy`  | boolean | No       | Allow customers to purchase multiple quantities. Default: `false`.             |
| `maxQuantity`       | number  | No\*     | Maximum quantity allowed per purchase. Required if `allowQuantityBuy` is true. |
| `reusable`          | boolean | No       | Whether the link can be used multiple times. Default: `true`.                  |
| `expirationDate`    | string  | No       | Expiration date in ISO 8601 format.                                            |
| `successUrl`        | string  | No       | URL to redirect customers after successful payment.                            |
| `cancelUrl`         | string  | No       | URL to redirect customers if they cancel the payment.                          |
| `webhookUrl`        | string  | No       | Webhook URL to receive payment notifications.                                  |
| `merchantTradeNo`   | string  | No       | Unique merchant trade number for tracking.                                     |
| `branchId`          | string  | No       | Branch ID to associate with.                                                   |

### Example Response (201 Created)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "merchant_12345",
  "slug": "link_abc123xyz",
  "merchantTradeNo": "ORDER-2025-001",
  "name": "Premium Subscription",
  "description": "Monthly premium plan subscription",
  "amount": 49.99,
  "currency": "USDT",
  "allowCustomAmount": false,
  "allowQuantityBuy": true,
  "maxQuantity": 10,
  "reusable": false,
  "successUrl": "https://yourstore.com/payment/success",
  "cancelUrl": "https://yourstore.com/payment/cancelled",
  "webhookUrl": "https://yourstore.com/webhooks/ceypay",
  "used_count": 0,
  "status": "ACTIVE",
  "creator_type": "API_KEY",
  "creator_id": "ak_live_abc123",
  "created_at": "2025-11-25T10:30:00Z",
  "updated_at": "2025-11-25T10:30:00Z"
}
```

***

## Get Payment Link

Get details of a specific payment link.

```
GET /v1/payment-link/:id
```

### Example Request

```bash theme={null}
curl "https://api.ceypay.io/v1/payment-link/550e8400-e29b-41d4-a716-446655440000" \
  -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-446655440000",
  "merchant_id": "merchant_12345",
  "slug": "link_abc123xyz",
  "name": "Premium Subscription",
  "description": "Monthly premium plan subscription",
  "amount": 49.99,
  "currency": "USDT",
  "status": "ACTIVE",
  ...
}
```

***

## List Payment Links

Retrieve a paginated list of payment links.

```
GET /v1/payment-link/list
```

### Example Request

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

### Query Parameters

| Parameter  | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| `page`     | number | Page number (default: 1).      |
| `pageSize` | number | Items per page (default: 20).  |
| `branchId` | string | Filter by branch ID.           |
| `search`   | string | Search by name or description. |

### Example Response (200 OK)

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Premium Subscription",
      "amount": 49.99,
      "currency": "USDT",
      "status": "ACTIVE",
      ...
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 45,
  "totalPages": 3,
  "hasNext": true,
  "hasPrev": false
}
```

***

## Deactivate Payment Link

Deactivate (soft delete) a payment link. It will no longer accept new payments.

```
DELETE /v1/payment-link/:id
```

### Example Request

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

### Example Response (200 OK)

```json theme={null}
{
  "message": "Payment link deactivated successfully"
}
```

***

## Error Codes

| Status | Description                              |
| ------ | ---------------------------------------- |
| 400    | Bad Request - Invalid data.              |
| 401    | Unauthorized - Invalid signature.        |
| 403    | Forbidden - Access denied.               |
| 404    | Not Found - Payment link not found.      |
| 429    | Too Many Requests - Rate limit exceeded. |