# Dynamic PayID

Create and manage temporary, auto-expiring checkout PayIDs. Dynamic PayIDs are ideal for one-time payments, invoices, or payment links.

**Required permission:** `virtual_payid`

## Create Dynamic PayID

```
POST /v1/checkout/dynamic-payid
```

### Authentication

Requires a **secret key** (`sk_*`).

### Request body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `amount` | number | No | Expected payment amount in naira (e.g., `5000`). If omitted, any amount is accepted |
| `amount_validation` | string | No | How to validate incoming amounts. Default: `"A4"`. See [amount validation rules](#amount-validation-rules) |
| `allow_multiple_payments` | boolean | No | Accept more than one payment. Default: `false` |
| `expires_in_minutes` | integer | No | Expiry time in minutes. Default: `1440` (24h). Max: `4320` (72h) |
| `name` | string | No | Display name (max 255 chars). Auto-generated from your account name if omitted |
| `metadata` | object | No | Custom key-value data stored with the PayID |

::: tip Settlement
Payments received on this PayID are settled to your API key's configured settlement ledger. To change where payments are settled, update your API key's settlement configuration in the [dashboard](https://business.zevpay.ng).
:::

### Example request

::: code-group

```bash [cURL]
curl -X POST https://api.zevpaycheckout.com/v1/checkout/dynamic-payid \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_test_your_secret_key" \
  -d '{
    "amount": 5000,
    "amount_validation": "A0",
    "name": "Invoice #1234",
    "expires_in_minutes": 1440,
    "metadata": {
      "invoice_id": "INV-1234"
    }
  }'
```

```javascript [Node.js]
const response = await fetch(
  "https://api.zevpaycheckout.com/v1/checkout/dynamic-payid",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "sk_test_your_secret_key",
    },
    body: JSON.stringify({
      amount: 5000,
      amount_validation: "A0",
      name: "Invoice #1234",
      expires_in_minutes: 1440,
      metadata: { invoice_id: "INV-1234" },
    }),
  }
);
const data = await response.json();
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "slug": "a4b7",
    "suffix": ".dypid",
    "full_pay_id": "a4b7.dypid",
    "settlement_pay_id_id": "s1t2u3v4-...",
    "creator_pay_id_id": "c1d2e3f4-...",
    "creator_type": "business",
    "business_id": "b1c2d3e4-...",
    "name": "Invoice #1234",
    "amount": "5000.00",
    "amount_validation": "A0",
    "allow_multiple_payments": false,
    "status": "active",
    "source": "api",
    "expires_at": "2026-03-09T12:00:00.000Z",
    "deactivated_at": null,
    "completed_at": null,
    "created_at": "2026-03-08T12:00:00.000Z"
  }
}
```

---

## List Dynamic PayIDs

```
GET /v1/checkout/dynamic-payid
```

### Query parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Page number |
| `page_size` | integer | 20 | Items per page (max 100) |
| `status` | string | — | Filter: `"active"`, `"completed"`, `"expired"`, `"deactivated"` |
| `search` | string | — | Search by slug, name, or PayID |

### Example request

```bash
curl "https://api.zevpaycheckout.com/v1/checkout/dynamic-payid?status=active&page_size=10" \
  -H "x-api-key: sk_test_your_secret_key"
```

### Response

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-...",
        "full_pay_id": "a4b7.dypid",
        "name": "Invoice #1234",
        "amount": "5000.00",
        "status": "active",
        "expires_at": "2026-03-09T12:00:00.000Z",
        "created_at": "2026-03-08T12:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}
```

---

## Get Dynamic PayID

```
GET /v1/checkout/dynamic-payid/:id
```

### Path parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Dynamic PayID UUID |

### Example request

```bash
curl https://api.zevpaycheckout.com/v1/checkout/dynamic-payid/a1b2c3d4-... \
  -H "x-api-key: sk_test_your_secret_key"
```

---

## Deactivate Dynamic PayID

Deactivate a dynamic PayID before its natural expiry.

```
DELETE /v1/checkout/dynamic-payid/:id
```

### Example request

```bash
curl -X DELETE https://api.zevpaycheckout.com/v1/checkout/dynamic-payid/a1b2c3d4-... \
  -H "x-api-key: sk_test_your_secret_key"
```

### Response

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "Dynamic PayID deactivated."
  }
}
```

---

## Amount Validation Rules

Control how incoming payment amounts are validated against the configured `amount`:

| Rule | Description |
|------|-------------|
| `A0` | **Exact match** — payment must equal the amount exactly |
| `A1` | **Less than** — payment must be less than the amount |
| `A2` | **Greater than** — payment must be greater than the amount |
| `A3` | **At most** — payment must be equal to or less than the amount |
| `A4` | **At least** — payment must be equal to or greater than the amount (default) |
| `A5` | **Any amount** — no validation applied |

If `amount` is not set, all incoming payments are accepted regardless of the validation rule.

---

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier (UUID) |
| `slug` | string | Short auto-generated slug |
| `suffix` | string | Always `".dypid"` |
| `full_pay_id` | string | Complete PayID (e.g., `"a4b7.dypid"`) |
| `settlement_pay_id_id` | string | PayID where payments are settled |
| `creator_pay_id_id` | string | Creator's PayID UUID |
| `creator_type` | string | `"personal"` or `"business"` |
| `business_id` | string\|null | Business UUID (if created by a business) |
| `name` | string | Display name |
| `amount` | string\|null | Configured amount (naira, e.g., `"5000.00"`) |
| `amount_validation` | string | Validation rule (`A0`–`A5`) |
| `allow_multiple_payments` | boolean | Whether multiple payments are accepted |
| `status` | string | `"active"`, `"completed"`, `"expired"`, or `"deactivated"` |
| `source` | string | Creation source (`"api"`, `"dashboard"`, etc.) |
| `expires_at` | string | ISO 8601 expiry timestamp |
| `deactivated_at` | string\|null | When deactivated (if applicable) |
| `completed_at` | string\|null | When a payment was received (if applicable) |
| `created_at` | string | ISO 8601 creation timestamp |

## Try it — Create Dynamic PayID

<ApiPlayground
  method="POST"
  endpoint="/v1/checkout/dynamic-payid"
  :bodyFields="[
    { name: 'amount', type: 'integer', placeholder: '5000', description: 'Amount in naira' },
    { name: 'amount_validation', type: 'select', options: [{ label: 'A0 — Exact match', value: 'A0' }, { label: 'A1 — Less than', value: 'A1' }, { label: 'A2 — Greater than', value: 'A2' }, { label: 'A3 — At most', value: 'A3' }], placeholder: 'Default: A4 (At least)' },
    { name: 'allow_multiple_payments', type: 'select', options: [{ label: 'false', value: 'false' }, { label: 'true', value: 'true' }] },
    { name: 'expires_in_minutes', type: 'integer', placeholder: '1440', description: 'Default: 1440 (24h)' },
    { name: 'name', type: 'string', placeholder: 'Invoice #1234' },
    { name: 'metadata', type: 'object', placeholder: '{ &quot;invoice_id&quot;: &quot;INV-1234&quot; }' },
  ]"
/>

## Try it — List Dynamic PayIDs

<ApiPlayground
  method="GET"
  endpoint="/v1/checkout/dynamic-payid"
  :queryParams="[
    { name: 'page', type: 'integer', placeholder: '1', default: '1' },
    { name: 'page_size', type: 'integer', placeholder: '20' },
    { name: 'status', type: 'select', options: [{ label: 'Active', value: 'active' }, { label: 'Completed', value: 'completed' }, { label: 'Expired', value: 'expired' }, { label: 'Deactivated', value: 'deactivated' }] },
    { name: 'search', type: 'string', placeholder: 'Search by slug, name, or PayID' },
  ]"
/>