Payment Links

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

Overview

Payment Links are reusable, shareable collection pages. Use a fixed link for a known amount or configure the supported link type for customer-entered payment details. Custom fields let you collect the context your business needs alongside each payment.

Lifecycle

Create the link and store its id, slug, and public URL.
Move the link to active when it is ready to accept payments.
Share the public URL with customers.
Query link transactions or process transaction webhooks for each payment.
Set the link to inactive when paused; expiry and quantity limits may also stop new payments.

The link status controls whether new customers can use it. Individual payments created through the link have their own transaction status and should be reconciled separately.

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