Create Payment Link

The Create Payment Link endpoint allows you to create shareable payment links that enable customers to make payments for products, services, or custom amounts. Payment links support multiple payment types, currencies, and advanced customization options including tax collection, address capture, and payment limits.

Endpoint DetailsCopied!

Method: POST
URL: /api/v0/payment-links
Content-Type: application/json
Authentication: Required (x-client-key and x-client-secret)
Scope Required: payment_link:create

Request HeadersCopied!

Header	Type	Required	Description
`x-client-key`	string	Yes	Your API client key
`x-client-secret`	string	Yes	Your API client secret
`idempotency-key`	string	Yes	Unique UUID for request idempotency
`Content-Type`	string	Yes	Must be `application/json`

Request BodyCopied!

Core Fields

Field	Type	Required	Description
`title`	string	Yes	Display title (3-100 characters)
`url`	string	Yes	Unique URL slug (letters, numbers, hyphens, underscores, slashes, dots)
`linkType`	enum	Yes	Type of payment link
`description`	string	No	Detailed description (max 500 chars, supports markdown)
`coverImage`	string	No	Cover image URL

Payment Configuration

Field	Type	Required	Description
`amount`	number	No	Fixed amount (min 0.01), required for non-product types
`currency`	enum	No	Payment currency (default: `usdc`)
`recurringType`	enum	No	Payment frequency (default: `ONE_TIME`)
`walletId`	string	No	Specific wallet ID (uses app default if not provided)
`expiration_date`	datetime	No	Payment link expiration date

Product Configuration

Field	Type	Required	Description
`paymentLinkProducts`	array	No	Array of products for bundle payments
`isForAllProduct`	boolean	No	Include all products from catalog (default: false)
`allowQuantityAdjustment`	boolean	No	Allow customers to adjust quantities (default: true)

Customer Data Collection

Field	Type	Required	Description
`collectAddress`	boolean	No	Require customer address (default: false)
`requirePhoneNumber`	boolean	No	Require phone number (default: false)
`allowBusinessTaxId`	boolean	No	Allow business tax ID input (default: false)
`customFields`	object	No	Custom form fields

Tax Configuration

Field	Type	Required	Description
`collectTax`	boolean	No	Apply tax calculation (default: false)
`taxId`	string	No	Tax configuration ID (required if collectTax is true)

Payment Limits & Controls

Field	Type	Required	Description
`limitPayments`	boolean	No	Limit total number of payments (default: false)
`maxPayments`	number	No	Maximum payment count (required if limitPayments is true)
`customerId`	string	No	Restrict to specific customer

Payment Methods & Experience

Field	Type	Required	Description
`allowMobilePayment`	boolean	No	Enable mobile payments (default: false)
`confirmationPage`	enum	No	Post-payment page behavior (default: `SHOW`)
`createInvoicePdf`	boolean	No	Generate PDF receipt (default: false)

EnumsCopied!

Payment Link Types

Value	Description	Use Case
`PRODUCT`	Product-based payments	Selling specific products with quantities
`DONATION`	Donation payments	Accepting custom donation amounts
`INVOICE`	Invoice payments	Converting invoices to payment links
`SUBSCRIPTION`	Recurring subscriptions	Monthly/yearly service subscriptions
`COLLECTION`	General collections	Event tickets, fees, memberships

Recurring Types

Value	Description
`ONE_TIME`	Single payment
`WEEKLY`	Every week
`BI_WEEKLY`	Every two weeks
`MONTHLY`	Every month
`BI_MONTHLY`	Every two months
`QUARTERLY`	Every three months
`ANNUALLY`	Every year

Supported Currencies

Currency	Description	Networks
`usdc`	USD Coin	Ethereum, Polygon, Solana, Arbitrum, Base, Optimism
`eurc`	Euro Coin	Solana only

Confirmation Page Types

Value	Description
`SHOW`	Display confirmation page
`REDIRECT`	Redirect to custom URL

Example RequestsCopied!

Simple Product Payment Link

curl -X POST "https://api.devdraft.com/api/v0/payment-links" \
  -H "x-client-key: your_client_key" \
  -H "x-client-secret: your_client_secret" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Subscription",
    "url": "premium-subscription",
    "description": "Monthly access to all premium features",
    "linkType": "PRODUCT",
    "amount": 29.99,
    "recurringType": "MONTHLY",
    "currency": "usdc",
    "allowQuantityAdjustment": true,
    "collectTax": false,
    "collectAddress": true,
    "requirePhoneNumber": true,
    "confirmationPage": "SHOW",
    "createInvoicePdf": true
  }'

Product Bundle Payment Link

curl -X POST "https://api.devdraft.com/api/v0/payment-links" \
  -H "x-client-key: your_client_key" \
  -H "x-client-secret: your_client_secret" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440002" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Startup Bundle",
    "url": "startup-bundle",
    "description": "Everything you need to get started",
    "linkType": "PRODUCT",
    "paymentLinkProducts": [
      {
        "productId": "123e4567-e89b-12d3-a456-426614174003",
        "quantity": 1
      },
      {
        "productId": "123e4567-e89b-12d3-a456-426614174004",
        "quantity": 2
      }
    ],
    "allowQuantityAdjustment": true,
    "collectTax": true,
    "taxId": "123e4567-e89b-12d3-a456-426614174005",
    "collectAddress": true,
    "limitPayments": true,
    "maxPayments": 100,
    "currency": "usdc"
  }'

Donation Payment Link

curl -X POST "https://api.devdraft.com/api/v0/payment-links" \
  -H "x-client-key: your_client_key" \
  -H "x-client-secret: your_client_secret" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440003" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Support Our Mission",
    "url": "donate-now",
    "description": "Help us make a difference in the community",
    "linkType": "DONATION",
    "currency": "usdc",
    "allowMobilePayment": true,
    "collectAddress": false,
    "requirePhoneNumber": false,
    "confirmationPage": "SHOW",
    "expiration_date": "2024-12-31T23:59:59Z"
  }'

ResponseCopied!

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Premium Subscription",
  "description": "Monthly access to all premium features",
  "url": "premium-subscription",
  "linkType": "PRODUCT",
  "status": "ACTIVE",
  "amount": 29.99,
  "currency": "usdc",
  "recurringType": "MONTHLY",
  "walletId": "wallet_550e8400-e29b-41d4-a716-446655440000",
  "appId": "app_550e8400-e29b-41d4-a716-446655440000",
  "allowQuantityAdjustment": true,
  "collectTax": false,
  "collectAddress": true,
  "requirePhoneNumber": true,
  "limitPayments": false,
  "maxPayments": null,
  "allowBusinessTaxId": false,
  "allowMobilePayment": false,
  "confirmationPage": "SHOW",
  "createInvoicePdf": true,
  "allowCryptoPayment": true,
  "isForAllProduct": false,
  "customFields": null,
  "expiration_date": null,
  "customerId": null,
  "taxId": null,
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses

400 Bad Request - Validation Error

{
  "statusCode": 400,
  "message": [
    "Title must be at least 3 characters long",
    "Amount must be greater than 0"
  ],
  "error": "Bad Request"
}

401 Unauthorized - Invalid Authentication

{
  "statusCode": 401,
  "message": "Application not authenticated",
  "error": "Unauthorized"
}

404 Not Found - Invalid References

{
  "statusCode": 404,
  "message": "Tax with ID 123e4567-e89b-12d3-a456-426655440000 not found",
  "error": "Not Found"
}

Business Logic & ValidationCopied!

Automatic Wallet Assignment

If walletId is not provided, the system automatically assigns your app's default wallet
If no default wallet exists, the request fails with a 404 error

Payment Link Types Logic

PRODUCT Type:

Requires either amount OR paymentLinkProducts
If using paymentLinkProducts, total is calculated from product prices
Supports quantity adjustments when allowQuantityAdjustment is true

DONATION Type:

No fixed amount required
Customers can enter custom amounts during checkout
Minimum amount validation applies during payment

SUBSCRIPTION Type:

Requires amount and recurringType other than ONE_TIME
Creates recurring payment schedule

Tax Calculation

When collectTax is true, taxId must be provided
Tax is calculated as: (subtotal * tax_percentage / 100)
Tax applies to the base amount before any additional fees

Payment Limits

When limitPayments is true, maxPayments must be specified
Once limit is reached, payment link becomes inactive
Payment counter tracks successful payments only

Integration Best PracticesCopied!

URL Slug Guidelines

// Good URL examples
"premium-subscription"
"startup-bundle-2024"
"donation/annual-campaign"

// Invalid URLs (will be rejected)
"premium subscription"  // spaces not allowed
"special@offer"         // special characters not allowed

Error Handling

try {
  const response = await fetch('/api/v0/payment-links', {
    method: 'POST',
    headers: {
      'x-client-key': 'your_client_key',
      'x-client-secret': 'your_client_secret',
      'idempotency-key': generateUUID(),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(paymentLinkData)
  });

  if (response.status === 400) {
    const errors = await response.json();
    console.log('Validation errors:', errors.message);
  } else if (response.ok) {
    const paymentLink = await response.json();
    console.log('Payment link created:', paymentLink.url);
  }
} catch (error) {
  console.error('Request failed:', error);
}

Product Bundle Best Practices

Validate Products: Ensure all productId values exist in your catalog
Quantity Management: Set appropriate default quantities
Price Display: Total price is calculated automatically from product prices
Tax Integration: Configure tax settings before enabling collectTax

Rate LimitingCopied!

Limit: 100 requests per minute per API key
Headers: Monitor X-RateLimit-* headers in responses
Best Practice: Implement exponential backoff for rate limit errors

Security & ComplianceCopied!

Idempotency: Always include unique idempotency-key for each request
URL Uniqueness: URLs must be unique within your account
Data Validation: All input is validated server-side
Audit Trail: All payment link creation attempts are logged

Use CasesCopied!

E-commerce Integration

Create product-specific payment links for your online store with automatic inventory tracking and tax calculation.

Fundraising & Donations

Enable flexible donation collection with custom amounts and donor information capture.

Event Management

Create payment links for event tickets, workshop fees, or conference registrations with payment limits.

Service Billing

Generate payment links for professional services, consulting fees, or project-based billing.