{
  "id": "pl_01HZXK8M9N2P3Q4R5S6T7U8V9W",
  "title": "Premium Subscription",
  "url": "https://checkout.devdraft.ai/premium-subscription",
  "description": "Monthly access to all premium features",
  "coverImage": null,
  "linkType": "PRODUCT",
  "status": "ACTIVE",
  "amount": 29.99,
  "paymentForId": null,
  "currency": "usdc",
  "allowQuantityAdjustment": true,
  "allowMobilePayment": true,
  "collectTax": false,
  "collectAddress": false,
  "limitPayments": false,
  "maxPayments": null,
  "customFields": null,
  "paymentLinkProducts": [],
  "isForAllProduct": false,
  "appId": "app_123456789",
  "customerId": null,
  "taxId": null,
  "expiration_date": null,
  "createdAt": "2023-07-01T12:00:00.000Z",
  "updatedAt": "2023-07-01T12:00:00.000Z"
}
The Create Payment Link API enables you to generate shareable URLs that allow customers to make payments for products, services, or custom amounts. Payment links support both one-time and recurring payments with extensive customization options including tax collection, quantity adjustments, and custom fields.

Endpoint Details

method
string
POST
url
string
/api/v0/payment-links
Authentication: Required (API Key & Secret)
Idempotency: Supported (recommended for all payment operations)

Authentication

All requests require API key authentication using the following headers:
  • x-client-key: Your application’s client key
  • x-client-secret: Your application’s client secret

Idempotency

The endpoint supports idempotency to prevent duplicate payment links:
  • idempotency-key: Include a unique UUID v4 in the header
  • Subsequent requests with the same key return the original response
  • Keys expire after 24 hours
TypeDescriptionUse Case
PRODUCTLink for specific products or product bundlesE-commerce, digital products, services
DONATIONLink for accepting donationsFundraising, charity, tips
SUBSCRIPTIONLink for recurring paymentsMonthly subscriptions, memberships

Request Parameters

Required Parameters

title
string
required
Display title for the payment link (3-100 characters)
Example: "Premium Subscription"
url
string
required
Unique URL slug for the payment link
Example: "premium-subscription"
Pattern: Valid URL or slug format
Type of the payment link
Values: "PRODUCT", "DONATION", "SUBSCRIPTION"
Example: "PRODUCT"
allowQuantityAdjustment
boolean
required
Whether to allow quantity adjustment
Default: true
Example: true
allowMobilePayment
boolean
required
Whether to allow mobile payment methods
Default: false
Example: true
currency
enum
required
Payment currency
Values: "usdc", "eurc"
Default: "usdc"
Example: "usdc"

Optional Parameters

description
string
Detailed description (max 500 chars, supports markdown)
Example: "Get access to all premium features with our monthly subscription plan"
coverImage
string
Cover image URL for the payment link
Example: "https://example.com/images/premium-subscription.jpg"
amount
number
Fixed amount for the payment link (minimum 0.01)
Example: 29.99
paymentForId
string
External reference ID for the payment
Example: "sub_123456789"
customerId
string
UUID of an existing customer
Example: "123e4567-e89b-12d3-a456-426614174002"
Array of products to include in the payment link
Type: Array of PaymentLinkProduct objects
isForAllProduct
boolean
Whether the payment link is for all products
Default: false
collectTax
boolean
Whether to collect tax on the payment
Default: false
taxId
string
UUID of the tax configuration to apply
Example: "123e4567-e89b-12d3-a456-426614174005"
collectAddress
boolean
Whether to collect customer address
Default: false
limitPayments
boolean
Whether to limit the number of payments
Default: false
maxPayments
number
Maximum number of payments allowed (minimum 1)
Example: 100
customFields
object
Custom fields for additional data collection
Example: {"customField1": "value1", "customField2": "value2"}
expiration_date
string
Expiration date for the payment link (ISO 8601 format)
Example: "2024-12-31T23:59:59Z"

PaymentLinkProduct Object

productId
string
required
UUID of the product to include
Example: "123e4567-e89b-12d3-a456-426614174000"
quantity
number
Quantity of the product (minimum 1)
Default: 1
Example: 2

Request Examples

curl -X POST "https://api.devdraft.ai/api/v0/payment-links" \
  -H "Content-Type: application/json" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "title": "Premium Subscription",
    "url": "premium-subscription",
    "description": "Monthly access to all premium features",
    "linkType": "PRODUCT",
    "amount": 29.99,
    "currency": "usdc",
    "allowQuantityAdjustment": true,
    "allowMobilePayment": true,
    "collectTax": false,
    "collectAddress": false,
    "limitPayments": false
  }'

Response Format

Success Response (201 Created)

{
  "id": "pl_01HZXK8M9N2P3Q4R5S6T7U8V9W",
  "title": "Premium Subscription",
  "url": "https://checkout.devdraft.ai/premium-subscription",
  "description": "Monthly access to all premium features",
  "coverImage": null,
  "linkType": "PRODUCT",
  "status": "ACTIVE",
  "amount": 29.99,
  "paymentForId": null,
  "currency": "usdc",
  "allowQuantityAdjustment": true,
  "allowMobilePayment": true,
  "collectTax": false,
  "collectAddress": false,
  "limitPayments": false,
  "maxPayments": null,
  "customFields": null,
  "paymentLinkProducts": [],
  "isForAllProduct": false,
  "appId": "app_123456789",
  "customerId": null,
  "taxId": null,
  "expiration_date": null,
  "createdAt": "2023-07-01T12:00:00.000Z",
  "updatedAt": "2023-07-01T12:00:00.000Z"
}

Response Fields

id
string
Unique payment link identifier
title
string
Display title of the payment link
url
string
Full checkout URL for the payment link
description
string | null
Description of the payment link
coverImage
string | null
Cover image URL
Type of payment link (PRODUCT, DONATION, SUBSCRIPTION)
status
string
Current status of the payment link (ACTIVE, INACTIVE, EXPIRED)
amount
number | null
Fixed amount for the payment link
currency
string
Payment currency (usdc, eurc)
allowQuantityAdjustment
boolean
Whether quantity adjustment is allowed
allowMobilePayment
boolean
Whether mobile payments are allowed
collectTax
boolean
Whether tax collection is enabled
collectAddress
boolean
Whether address collection is enabled
limitPayments
boolean
Whether payment count is limited
maxPayments
number | null
Maximum number of payments allowed
customFields
object | null
Custom fields for data collection
Array of associated products
appId
string
Application identifier
expiration_date
string | null
Expiration date (ISO 8601)
createdAt
string
Creation timestamp (ISO 8601)
updatedAt
string
Last update timestamp (ISO 8601)

Error Responses

{
  "statusCode": 400,
  "message": [
    "Title must be at least 3 characters long",
    "URL must be a valid URL or slug format"
  ],
  "error": "Bad Request"
}

Use Cases

1. E-commerce Product Sales

Create payment links for individual products or product bundles with customizable quantities and tax collection.

2. Subscription Services

Set up recurring payment links for memberships, subscriptions, and ongoing services.

3. Fundraising & Donations

Accept donations with flexible amounts, custom fields for donor information, and address collection.

4. Limited Time Offers

Create time-sensitive payment links with expiration dates and payment limits for special promotions.

5. Service Payments

Generate payment links for professional services, consultations, and custom amounts.

Best Practices

URL Management

  • Use descriptive, SEO-friendly URL slugs
  • Keep URLs short and memorable
  • Avoid special characters and spaces
  • Implement consistent naming conventions

Product Bundling

  • Group related products logically
  • Set appropriate default quantities
  • Enable quantity adjustment for flexibility
  • Consider tax implications for bundles

Customer Experience

  • Write clear, compelling descriptions
  • Use high-quality cover images
  • Collect only necessary information
  • Provide multiple payment options

Security & Compliance

  • Set appropriate expiration dates for sensitive links
  • Limit payment counts for exclusive offers
  • Collect required tax information
  • Implement proper fraud prevention

Integration Patterns

class DynamicPaymentLinks {
  constructor(paymentLinks) {
    this.paymentLinks = paymentLinks;
    this.pricingRules = new Map();
  }

  addPricingRule(productId, rule) {
    this.pricingRules.set(productId, rule);
  }

  async createDynamicLink(productId, basePrice, customerSegment) {
    const rule = this.pricingRules.get(productId);
    const finalPrice = rule ? rule(basePrice, customerSegment) : basePrice;
    
    return this.paymentLinks.createProductLink(
      `Product ${productId}`,
      `product-${productId}-${Date.now()}`,
      finalPrice,
      `Customized pricing for ${customerSegment}`
    );
  }

  async createBulkLinks(products) {
    const promises = products.map(product => 
      this.createDynamicLink(product.id, product.price, product.segment)
    );
    
    return Promise.all(promises);
  }
}

// Usage
const dynamicLinks = new DynamicPaymentLinks(paymentLinks);

// Add pricing rules
dynamicLinks.addPricingRule('product-1', (basePrice, segment) => {
  return segment === 'premium' ? basePrice * 0.9 : basePrice;
});

// Create dynamic link
const link = await dynamicLinks.createDynamicLink('product-1', 100, 'premium');
class PaymentLinkAnalytics {
  constructor(paymentLinks) {
    this.paymentLinks = paymentLinks;
    this.analytics = new Map();
  }

  async createTrackedLink(linkData, trackingParams) {
    const link = await this.paymentLinks.createPaymentLink({
      ...linkData,
      customFields: {
        ...linkData.customFields,
        tracking_source: trackingParams.source,
        tracking_medium: trackingParams.medium,
        tracking_campaign: trackingParams.campaign
      }
    });

    this.analytics.set(link.id, {
      created: new Date(),
      source: trackingParams.source,
      conversions: 0,
      revenue: 0
    });

    return link;
  }

  recordConversion(linkId, amount) {
    const stats = this.analytics.get(linkId);
    if (stats) {
      stats.conversions++;
      stats.revenue += amount;
    }
  }

  getAnalytics(linkId) {
    return this.analytics.get(linkId);
  }

  getTopPerformingLinks(limit = 10) {
    return Array.from(this.analytics.entries())
      .sort((a, b) => b[1].revenue - a[1].revenue)
      .slice(0, limit);
  }
}

Support

For additional support or questions about the Create Payment Link API:
  1. Check our API status page for known issues
  2. Review the error codes and messages in your responses
  3. Contact our support team with your payment link ID for specific issues
  4. Use our testing environment to validate integrations before going live