Payment Link Creation API

The Elyxa API allows you to create payment links that direct customers to a hosted checkout page. This is perfect for businesses that want to provide a seamless payment experience without handling cryptocurrency addresses directly.

Base URL

https://elyxa.app/api

Authentication

All API requests require authentication using your API key. Include it in the request header:

Authorization: Bearer YOUR_API_KEY

Create Payment Link Endpoint

Create a new payment link that customers can use to access a hosted checkout page.

POST https://elyxa.app/api/payments/links

Request Body:

{
  "amount": "25.50",
  "currency": "USD",
  "paymentMethods": ["BITCOIN", "LIGHTNING", "LITECOIN", "DOGECOIN", "MONERO"],
  "expirationMinutes": 120,
  "externalInvoiceId": "order_12345",
  "metadata": {
    "description": "Premium coffee beans",
    "orderId": "coffee_shop_001",
    "customerEmail": "customer@example.com"
  }
}

Response:

{
  "success": true,
  "paymentLink": "https://elyxa.app/pay/WfW5Dd1ASHSj4ZHhMC5yTA",
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "expiryTime": 1754875443,
  "expirationMinutes": 120,
  "amount": "25.50",
  "currency": "USD"
}

Request Parameters

Supported Payment Methods

• BITCOIN - Bitcoin on-chain payments
• LIGHTNING - Bitcoin Lightning Network payments
• LITECOIN - Litecoin payments
• DOGECOIN - Dogecoin payments
• MONERO - Monero payments

Smart Defaults

When you don't specify certain fields, the system automatically provides intelligent defaults:

Minimal Request (Recommended):

{
  "amount": "25.50",
  "currency": "USD"
}

Automatic Defaults Applied:

• Payment Methods: All 5 cryptocurrencies enabled
• Expiration: 15 minutes (or 60 minutes if Monero is included)
• Metadata: Empty object {}

Expiration Time Rules:

• BTC-only methods: Default 15 minutes
• With Monero: Minimum 60 minutes (1 hour) - enforced automatically
• Custom time: 1-1440 minutes (24 hours max)

Response Fields

How It Works

1. Create Payment Link

• You call the API with payment details
• We create an invoice and generate a unique payment link
• You receive the payment link URL

2. Share with Customer

• Send the payment link to your customer via email, SMS, or embed in your website
• Customer clicks the link and goes to a hosted checkout page

3. Customer Pays

• Customer sees all available payment methods on the hosted page
• They choose their preferred cryptocurrency and complete payment
• You receive webhook notifications about payment status

Key Differences from Invoice Creation

Error Responses

If the request fails, you'll receive an error response:

{
  "error": "Amount and currency are required",
  "success": false
}

Common Error Codes:

• 400: Invalid request parameters
• 401: Authentication failed
• 500: Internal server error

Example Usage

cURL

curl -X POST https://elyxa.app/api/payments/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.50",
    "currency": "USD",
    "expirationMinutes": 90,
    "metadata": {
      "description": "Coffee order #123",
      "orderId": "COFFEE-123"
    }
  }'

JavaScript

const response = await fetch('https://elyxa.app/api/payments/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '25.50',
    currency: 'USD',
    expirationMinutes: 90,
    metadata: {
      description: 'Coffee order #123',
      orderId: 'COFFEE-123'
    }
  })
});

const paymentLink = await response.json();
console.log('Share this link with your customer:', paymentLink.paymentLink);

Python

import requests

url = "https://elyxa.app/api/payments/links"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "amount": "25.50",
    "currency": "USD",
    "expirationMinutes": 90,
    "metadata": {
        "description": "Coffee order #123",
        "orderId": "COFFEE-123"
    }
}

response = requests.post(url, headers=headers, json=data)
payment_link = response.json()
print(f"Share this link with your customer: {payment_link['paymentLink']}")

Customer Experience

When a customer visits your payment link, they'll see:

1. Professional checkout page with your branding
2. Multiple payment options (Bitcoin, Lightning, Litecoin, Dogecoin, Monero)
3. Real-time exchange rates and amounts
4. QR codes for easy mobile payments
5. Payment status updates in real-time
6. Secure payment processing handled by Elyxa

Best Practices

• Use minimal requests - just amount and currency for simple cases
• Set appropriate expiry times - 15 minutes for fast payments, 60+ for Monero
• Share payment links via email, SMS, or embed in your website
• Use metadata to track orders and customer information
• Monitor webhooks for payment status updates
• Test the flow with small amounts before going live

Webhooks

Set up webhooks to receive real-time updates about payment status:

{
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "status": "paid",
  "amount": "25.50",
  "currency": "USD",
  "timestamp": "2025-01-20T10:30:00Z"
}

Rate Limiting

• Default expiration: 15 minutes (prevents exchange rate issues)
• Monero minimum: 60 minutes (required for blockchain confirmations)
• Maximum expiration: 24 hours (1440 minutes)

This approach gives you the simplicity of hosted checkout while maintaining full control over your payment flow and customer experience.