Endpoint Details
POST
/api/v0/payment-links
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 keyx-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
Payment Link Types
Type | Description | Use Case |
---|---|---|
PRODUCT | Link for specific products or product bundles | E-commerce, digital products, services |
DONATION | Link for accepting donations | Fundraising, charity, tips |
SUBSCRIPTION | Link for recurring payments | Monthly subscriptions, memberships |
Request Parameters
Required Parameters
Display title for the payment link (3-100 characters)
Example:
Example:
"Premium Subscription"
Unique URL slug for the payment link
Example:
Pattern: Valid URL or slug format
Example:
"premium-subscription"
Pattern: Valid URL or slug format
Type of the payment link
Values:
Example:
Values:
"PRODUCT"
, "DONATION"
, "SUBSCRIPTION"
Example:
"PRODUCT"
Whether to allow quantity adjustment
Default:
Example:
Default:
true
Example:
true
Whether to allow mobile payment methods
Default:
Example:
Default:
false
Example:
true
Payment currency
Values:
Default:
Example:
Values:
"usdc"
, "eurc"
Default:
"usdc"
Example:
"usdc"
Optional Parameters
Detailed description (max 500 chars, supports markdown)
Example:
Example:
"Get access to all premium features with our monthly subscription plan"
Cover image URL for the payment link
Example:
Example:
"https://example.com/images/premium-subscription.jpg"
Fixed amount for the payment link (minimum 0.01)
Example:
Example:
29.99
External reference ID for the payment
Example:
Example:
"sub_123456789"
UUID of an existing customer
Example:
Example:
"123e4567-e89b-12d3-a456-426614174002"
Array of products to include in the payment link
Type: Array of
Type: Array of
PaymentLinkProduct
objectsWhether the payment link is for all products
Default:
Default:
false
Whether to collect tax on the payment
Default:
Default:
false
UUID of the tax configuration to apply
Example:
Example:
"123e4567-e89b-12d3-a456-426614174005"
Whether to collect customer address
Default:
Default:
false
Whether to limit the number of payments
Default:
Default:
false
Maximum number of payments allowed (minimum 1)
Example:
Example:
100
Custom fields for additional data collection
Example:
Example:
{"customField1": "value1", "customField2": "value2"}
Expiration date for the payment link (ISO 8601 format)
Example:
Example:
"2024-12-31T23:59:59Z"
PaymentLinkProduct Object
UUID of the product to include
Example:
Example:
"123e4567-e89b-12d3-a456-426614174000"
Quantity of the product (minimum 1)
Default:
Example:
Default:
1
Example:
2
Request Examples
Response Format
Success Response (201 Created)
Response Fields
Unique payment link identifier
Display title of the payment link
Full checkout URL for the payment link
Description of the payment link
Cover image URL
Type of payment link (PRODUCT, DONATION, SUBSCRIPTION)
Current status of the payment link (ACTIVE, INACTIVE, EXPIRED)
Fixed amount for the payment link
Payment currency (usdc, eurc)
Whether quantity adjustment is allowed
Whether mobile payments are allowed
Whether tax collection is enabled
Whether address collection is enabled
Whether payment count is limited
Maximum number of payments allowed
Custom fields for data collection
Array of associated products
Application identifier
Expiration date (ISO 8601)
Creation timestamp (ISO 8601)
Last update timestamp (ISO 8601)
Error Responses
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
Dynamic Link Generation
Link Analytics
Support
For additional support or questions about the Create Payment Link API:- Check our API status page for known issues
- Review the error codes and messages in your responses
- Contact our support team with your payment link ID for specific issues
- Use our testing environment to validate integrations before going live
For more information, see: