Payment Links - XentFi API Documentation

Overview

Why Use Payment Links?

🚀 No Code Required

Launch a payment page in minutes without any development - just generate and share

💳 Multiple Payment Methods

Support both Wallet Connect and deposit address payments in a single link

🎨 Custom Branding

Customize the payment page with your logo, colors, and success messages

📊 Built-in Analytics

Track payment status, conversion rates, and customer behavior

🔒 Secure by Default

Enterprise-grade security with automatic fraud detection and AML screening

🔄 Recurring Payments

Create links for subscription billing with configurable payment limits

How Payment Links Work

Use Cases

One-time Payments

Use Case	Example	Best For
Invoice payment	Service invoice for $1,000	Freelancers, agencies
Product checkout	One-time product purchase	E-commerce stores
Donation	Campaign donation page	Non-profits, creators
Event ticket	Conference ticket payment	Event organizers

Recurring Payments

Use Case	Example	Best For
Subscription	Monthly membership fee	SaaS businesses
Retainer	Weekly service payment	Consulting firms
Installment	3-part payment plan	High-value products
Crowdfunding	Monthly pledge	Crowdfunding campaigns

Marketing Campaigns

Use Case	Example	Best For
Limited offer	24-hour flash sale	Promotions
Affiliate links	Partner-specific payment	Affiliate programs
A/B testing	Multiple link versions	Optimization
Seasonal promo	Holiday special pricing	Seasonal campaigns

Creating Payment Links

Basic Link

curl -X POST https://api.xentfi.com/v1/payment/links \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "masterId": "your-master-wallet-id",
    "name": "Product Purchase",
    "amount": "100",
    "currency": "USD",
    "redirectUrl": "https://yourapp.com/success"
  }'

{
    "data": {
        "id": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase",
        "amount": "100",
        "currency": "USD",
        "url": "https://pay.xentfi.com/link_123e4567",
        "redirectUrl": "https://yourapp.com/success",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00.000Z"
    }
}

Advanced Configuration

{
    "masterId": "your-master-wallet-id",
    "name": "Premium Subscription",
    "description": "Monthly subscription for premium features",
    "amount": "49.99",
    "currency": "USD",
    "paymentLimit": 12,
    "expiresAt": "2024-12-31T23:59:59Z",
    "redirectUrl": "https://yourapp.com/welcome",
    "successMessage": "Thank you for subscribing!",
    "failureMessage": "Payment failed. Please try again.",
    "allowedPaymentMethods": [
        "wallet_connect",
        "deposit_address"
    ],
    "allowedNetworks": [
        "eth-mainnet",
        "polygon-mainnet",
        "base-mainnet"
    ],
    "metadata": {
        "planId": "premium_monthly",
        "customerTier": "gold"
    }
}

Payment Page Experience

The hosted payment page adapts to your brand and supports multiple payment methods.

Customer Journey

Customer Clicks Link

Customer opens the payment link in their browser

Enters Details

Optional: Customer provides name and email

Selects Payment Method

Choose between Wallet Connect or deposit address

Completes Payment

Customer pays using their preferred method

Redirected to Success Page

Automatic redirect to your configured URL

Payment Methods

Wallet Connect

Feature	Description
Supported wallets	MetaMask, Trust Wallet, Rainbow, Coinbase Wallet, WalletConnect
User experience	Connect wallet → Approve → Confirm transaction
Best for	Users who already have a crypto wallet
Payment speed	Transaction confirms in seconds

Deposit Address

Feature	Description
Supported wallets	Any wallet or exchange
User experience	Copy address → Send funds
Best for	Exchange users, large payments
Payment speed	Depends on blockchain network

Payment Status Flow

Payment Limits & Expiration

Payment Limits

Control how many payments a link can accept:

Limit Type	Description	Use Case
Single use	`paymentLimit: 1`	One-time invoice
Multi-use	`paymentLimit: 10`	Shared payment link
Unlimited	`paymentLimit: null`	Donation page
Subscription	`paymentLimit: 12`	Monthly subscription (12 months)

Expiration Settings

Setting	Description	Default
Link expiry	Link stops working after date	Never
Session timeout	Payment session expires	3 minutes (deposit)
Quote expiry	Price quote valid for	15 minutes

Customization Options

Branding

Element	Customizable	Description
Logo	✅ Yes	Your company logo displayed on payment page
Colors	✅ Yes	Primary and secondary colors
Fonts	✅ Yes	Custom font family
Success message	✅ Yes	Text shown after payment
Failure message	✅ Yes	Text shown if payment fails

Redirect Behavior

Webhook Events

Event	Trigger	Payload contains
`payment.created`	Link opened	Payment intent details
`payment.processing`	Payment submitted	Transaction hash
`payment.completed`	Payment confirmed	Full transaction details
`payment.failed`	Payment failed	Error reason
`payment.expired`	Session timeout	Expiration details

Analytics & Reporting

Available Metrics

Metric	Description	Update Frequency
Conversion rate	% of links that result in payment	Real-time
Average payment value	Average transaction amount	Daily
Payment methods	Distribution by method	Real-time
Geographic breakdown	Customer locations	Daily
Device breakdown	Desktop vs mobile	Daily
Time to payment	Average completion time	Hourly

Best Practices

Use descriptive names - Include product name, customer ID, or invoice number
Set payment limits - Prevent overpayment for limited-use links
Configure redirect URLs - Always provide success/failure redirects
Add metadata - Store internal references for reconciliation
Monitor webhooks - Implement proper webhook handling
Test thoroughly - Use testnet before going live

Payment Link vs Deposit Address

Feature	Payment Link	Deposit Address
Customer experience	Guided checkout	Manual address copy
Payment methods	Wallet Connect + Deposit	Deposit only
QR code	Auto-generated	Manual generation
Branding	Customizable	None
Analytics	Built-in	Basic
Best for	New customers, marketing	Technical users, recurring
Setup time	1 minute	1 minute

Marketing Integration

Email Templates

Include payment links in your email campaigns:

<!-- Example email template -->
<a href="https://pay.xentfi.com/link_123e4567"
   style="background: #F5A623; padding: 12px 24px; border-radius: 8px; color: white;">
  Pay Your Invoice
</a>

QR Codes

Each payment link automatically generates a QR code for in-person payments:

Display on screen for customers to scan
Print on physical invoices
Include in marketing materials

Troubleshooting

Link shows 'Payment limit reached'

Solution: The link has reached its maximum number of payments. Create a new link or increase the payment limit.

Customer sees wrong amount

Possible causes:

Exchange rate fluctuations
Different network selected
Token price changes

Solution: The amount is locked for 15 minutes; advise customer to complete payment quickly.

Redirect not working

Possible causes:

Invalid URL format
CORS issues
Missing protocol (https://)

Solution: Ensure redirect URLs include https:// and are publicly accessible.

Webhook not received

Solution:

Verify webhook is configured
Check endpoint is publicly accessible
Review webhook logs in dashboard

Performance Benchmarks

Metric	Target	Description
Link creation	< 500ms	Time to generate payment link
Page load time	< 1 second	Payment page load speed
Wallet Connect	< 3 seconds	Wallet connection time
Deposit detection	< 10 seconds	Time to detect incoming payment
Webhook delivery	< 2 seconds	Time to send notification

Pricing

Feature	Starter	Professional	Business	Enterprise
Payment links/month	100	1,000	10,000	Unlimited
Custom branding	❌	✅	✅	✅
Analytics	Basic	Advanced	Premium	Custom
API access	✅	✅	✅	✅
Webhooks	✅	✅	✅	✅
Priority support	❌	✅	✅	24/7

Compliance

Requirement	Status	Description
AML screening	✅	All payments screened
Sanctions check	✅	OFAC compliance
Fraud detection	✅	Automated monitoring
Data privacy	✅	GDPR compliant
PCI DSS	✅	Level 1 certified

Master Wallets

Receive payments to your treasury

Webhooks

Real-time payment notifications

Auto Settlement

Automatic fund distribution

Next Steps

Set up webhooks for real-time notifications
Configure auto-settlement for fund distribution
Review API Reference for complete endpoint documentation

Documentation Index

​Overview

​Why Use Payment Links?

🚀 No Code Required

💳 Multiple Payment Methods

🎨 Custom Branding

📊 Built-in Analytics

🔒 Secure by Default

🔄 Recurring Payments

​How Payment Links Work

​Use Cases

​One-time Payments

​Recurring Payments

​Marketing Campaigns

​Creating Payment Links

​Basic Link

​Advanced Configuration

​Payment Page Experience

​Customer Journey

​Payment Methods

​Wallet Connect

​Deposit Address

​Payment Status Flow

​Payment Limits & Expiration

​Payment Limits

​Expiration Settings

​Customization Options

​Branding

​Redirect Behavior

​Webhook Events

​Analytics & Reporting

​Available Metrics

​Best Practices

​Payment Link vs Deposit Address

​Marketing Integration

​Email Templates

​QR Codes

​Troubleshooting

​Performance Benchmarks

​Pricing

​Compliance

​Related Products