Payment Links

Base URL: /v1/payment-links
Auth: Authorization: Bearer <secret_key>

Create payment link

POST /v1/payment-links

Body:

{
  "currency": "NGN",
  "title": "January dues",
  "description": "Membership dues",
  "amount": 5000,
  "slug": "jan-dues",
  "type": "fixed",
  "quantity_limit": 1,
  "expires_at": "2026-12-31T23:59:59Z",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "fields": ["First Name", "Last Name", "Email", "Phone"]
}

Notes:

payment-link slugs are globally unique because the public payment URL is slug-based
if the requested slug already exists, the API automatically appends a numeric suffix such as -2 or -3

Example response:

{
  "data": {
    "id": "plink_1234567890",
    "title": "January dues",
    "description": "Membership dues",
    "type": "fixed",
    "amount": 5000,
    "currency": "NGN",
    "status": "pending",
    "slug": "jan-dues",
    "url": "https://pay.example.com/jan-dues",
    "quantity_limit": 1,
    "expires_at": "2026-12-31T23:59:59Z",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "metadata": {
      "fields": ["First Name", "Last Name", "Email", "Phone"]
    },
    "created_at": "2026-05-18T10:00:00Z",
    "updated_at": "2026-05-18T10:00:00Z"
  }
}

List payment links

GET /v1/payment-links

Query:

id
status
slug
date_from
date_to
page
limit

Notes:

when id is provided, the endpoint returns a single payment link
without id, the endpoint returns a paginated list in latest-first order
date-only filters are normalized as:
- date_from=YYYY-MM-DD => YYYY-MM-DD 00:00:00
- date_to=YYYY-MM-DD => YYYY-MM-DD 23:59:59

Single-item example:

GET /v1/payment-links?id=plink_1234567890

Single-item response:

{
  "data": {
    "id": "plink_1234567890",
    "title": "January dues",
    "description": "Membership dues",
    "type": "fixed",
    "amount": 5000,
    "currency": "NGN",
    "status": "active",
    "slug": "jan-dues",
    "url": "https://pay.example.com/jan-dues",
    "quantity_limit": 1,
    "expires_at": "2026-12-31T23:59:59Z",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "metadata": {
      "fields": ["First Name", "Last Name", "Email", "Phone"]
    },
    "created_at": "2026-05-18T10:00:00Z",
    "updated_at": "2026-05-18T10:30:00Z"
  }
}

List example:

GET /v1/payment-links?status=active&date_from=2026-05-01&date_to=2026-05-18&page=1&limit=25

List response:

{
  "data": [
    {
      "id": "plink_1234567890",
      "title": "January dues",
      "description": "Membership dues",
      "type": "fixed",
      "amount": 5000,
      "currency": "NGN",
      "status": "active",
      "slug": "jan-dues",
      "url": "https://pay.example.com/jan-dues",
      "quantity_limit": 1,
      "expires_at": "2026-12-31T23:59:59Z",
      "success_url": "https://example.com/success",
      "cancel_url": "https://example.com/cancel",
      "metadata": {
        "fields": ["First Name", "Last Name", "Email", "Phone"]
      },
      "created_at": "2026-05-18T10:00:00Z",
      "updated_at": "2026-05-18T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "total_pages": 1
  }
}

Payment link transactions

GET /v1/payment-links/transactions

Query:

uid (payment link uid)
trx_id
reference
status
customer_email
date_from
date_to
page
limit

Notes:

when trx_id or reference is provided, the endpoint returns a single transaction
otherwise it returns a paginated list of transactions linked to payment links
date-only filters are normalized as:
- date_from=YYYY-MM-DD => YYYY-MM-DD 00:00:00
- date_to=YYYY-MM-DD => YYYY-MM-DD 23:59:59

Single-item example:

GET /v1/payment-links/transactions?reference=trx-ref-001

Single-item response:

{
  "data": {
    "id": 1001,
    "trx_id": "trx_001",
    "reference": "trx-ref-001",
    "status": "success",
    "amount": 5000,
    "currency": "NGN",
    "customer_email": "[email protected]",
    "payment_link_uid": "plink_1234567890",
    "created_at": "2026-05-18T10:15:00Z",
    "updated_at": "2026-05-18T10:20:00Z"
  }
}

List example:

GET /v1/payment-links/transactions?uid=plink_1234567890&status=success&page=1&limit=20

List response:

{
  "data": [
    {
      "id": 1001,
      "trx_id": "trx_001",
      "reference": "trx-ref-001",
      "status": "success",
      "amount": 5000,
      "currency": "NGN",
      "customer_email": "[email protected]",
      "payment_link_uid": "plink_1234567890",
      "created_at": "2026-05-18T10:15:00Z",
      "updated_at": "2026-05-18T10:20:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

Update payment link status

POST /v1/payment-links/status

Body:

{
  "uid": "plink_123",
  "status": "active"
}

Allowed statuses:

pending
active
inactive
expired

Response:

{
  "data": {
    "id": "plink_123",
    "title": "January dues",
    "description": "Membership dues",
    "type": "fixed",
    "amount": 5000,
    "currency": "NGN",
    "status": "active",
    "slug": "jan-dues",
    "url": "https://pay.example.com/jan-dues",
    "quantity_limit": 1,
    "expires_at": "2026-12-31T23:59:59Z",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "metadata": {
      "fields": ["First Name", "Last Name", "Email", "Phone"]
    },
    "created_at": "2026-05-18T10:00:00Z",
    "updated_at": "2026-05-18T10:45:00Z"
  }
}