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

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.

Example request

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"
    }
  }'

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

{
  "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	none	Filter: "active", "completed", "expired", "deactivated"
search	string	none	Search by slug, name, or PayID

Example request

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

Response

{
  "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

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

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

Response

{
  "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

API Playground

POSThttps://api.zevpaycheckout.com/v1/checkout/dynamic-payid

API Key Stored locally in your browser

Request Body

amount integer

amount_validation selectDefault: A4 (At least)A0: Exact matchA1: Less thanA2: Greater thanA3: At most

allow_multiple_payments selectSelect...falsetrue

expires_in_minutes integer

name string

metadata object

Try it: List Dynamic PayIDs

API Playground

GEThttps://api.zevpaycheckout.com/v1/checkout/dynamic-payid

API Key Stored locally in your browser

Query Parameters

page

page_size

status Select...ActiveCompletedExpiredDeactivated

search