Create Payment Link

Generates a shareable link for collecting payments.

Authentication required (User JWT).

POST /api/merchants/:merchantId/payment-links

Path Parameters

Parameter	Type	Description
merchantId	String	The ID of the parent merchant.

Request Body

{
  "title": "Monthly Subscription Fee",
  "description": "Payment for premium access - October",
  "amount": 250000, // Optional: Integer (kobo/cents). Omit for variable amount.
  "customSlug": "october-sub", // Optional: Alphanumeric, max 50 chars.
  "isReusable": true, // Optional: boolean, defaults to false.
  "redirectUrl": "https://yourdomain.com/payment-success" // Optional
}

Field	Type	Required	Description
title	String	Yes	Name of the payment link, displayed to the customer.
description	String	No	Additional details about the payment.
amount	Integer	No	Amount in kobo/cents. If omitted, the customer can enter an amount.
customSlug	String	No	Unique alphanumeric string for the link URL (/pay/{slug}). If omitted, a random one is generated.
isReusable	Boolean	No	If true, the link can be paid multiple times. Defaults to false.
redirectUrl	String	No	URL to redirect the customer to after a successful payment.

Response 201 Created

Returns the details of the newly created payment link.

{
  "message": "Payment link created successfully",
  "link": {
    "id": "uuid-link-789",
    "merchantId": "uuid-merchant-456",
    "slug": "october-sub", // Or the generated slug
    "title": "Monthly Subscription Fee",
    "description": "Payment for premium access - October",
    "amount": 250000,
    "currency": "NGN",
    "isActive": true,
    "isReusable": true,
    "redirectUrl": "https://yourdomain.com/payment-success",
    "createdAt": "2023-10-27T11:00:00.000Z",
    "updatedAt": "2023-10-27T11:00:00.000Z"
    // Excludes the nested 'merchant' object
  }
}

Errors

• 400 Bad Request: Validation failed.
• 401 Unauthorized: Invalid or missing JWT.
• 404 Not Found: Merchant not found.
• 409 Conflict: Custom slug already exists for this merchant.
• 500 Internal Server Error