Invoice Creation API

The Elyxa API allows you to create payment invoices for your customers. All API requests should be made to the base URL with proper authentication.

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 Invoice Endpoint

Create a new payment invoice for your customers.

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

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,
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "expiryTime": 1754875443,
  "expirationMinutes": 120,
  "paymentMethods": [
    {
      "paymentMethodId": "LIGHTNING",
      "destination": "lnbc213980n1p5fjs40pp5mvgl2pht4a6tfs73hthwmatpcmxrfj5kyl2c57pwmzvkpq2j8v7sdp02pskjepqw3hjqjtww3shxetwvsszsnmjv3jhygzfgsazq2gcqzzsxqzuzsp5jrlfu2t0pvdwsjgscxzjeyhv48hqzr5spph6hd8nhn2q4dnhxhvs9qxpqysgqd2x8w9np79lkfh2v8lumgj3nm40mgv536d9xm9cwal6x6vqzlk5n0z2cv2s7gdfq9zhlh0sf0dr3svgv4fu2e8zyl9ucr83w28u632gpeq2u37",
      "paymentLink": "lightning:lnbc213980n1p5fjs40pp5mvgl2pht4a6tfs73hthwmatpcmxrfj5kyl2c57pwmzvkpq2j8v7sdp02pskjepqw3hjqjtww3shxetwvsszsnmjv3jhygzfgsazq2gcqzzsxqzuzsp5jrlfu2t0pvdwsjgscxzjeyhv48hqzr5spph6hd8nhn2q4dnhxhvs9qxpqysgqd2x8w9np79lkfh2v8lumgj3nm40mgv536d9xm9cwal6x6vqzlk5n0z2cv2s7gdfq9zhlh0sf0dr3svgv4fu2e8zyl9ucr83w28u632gpeq2u37",
      "amount": "0.00021398",
      "currency": "BTC"
    },
    {
      "paymentMethodId": "BITCOIN",
      "destination": "bc1qj2fq492m79e0unp2vvej26468dk3vr50tw3zhj",
      "paymentLink": "bitcoin:bc1qj2fq492m79e0unp2vvej26468dk3vr50tw3zhj?amount=0.00021398",
      "amount": "0.00021398",
      "currency": "BTC"
    },
    {
      "paymentMethodId": "LITECOIN",
      "destination": "ltc1qgxszmp8qg08h33dmm7lh64zf3mlzfvkvjqgsjj",
      "paymentLink": "litecoin:ltc1qgxszmp8qg08h33dmm7lh64zf3mlzfvkvjqgsjj?amount=0.20837766",
      "amount": "0.20837766",
      "currency": "LTC"
    },
    {
      "paymentMethodId": "DOGECOIN",
      "destination": "D8j8v1ZbqKqi58VQo39oSGSqfxC4GZLEgm",
      "paymentLink": "dogecoin:D8j8v1ZbqKqi58VQo39oSGSqfxC4GZLEgm?amount=0.20837766",
      "amount": "0.20837766",
      "currency": "DOGE"
    },
    {
      "paymentMethodId": "MONERO",
      "destination": "489nBCfoGxTQBNUnGupJdufhxYRdJumBLX5mGNDErvfYU4zLxwjqyxA4mMrQhriKMDArsZkH7WBA846WoGvxz5C4Mi5nHRz",
      "paymentLink": "",
      "amount": "0.00012345",
      "currency": "XMR"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
`amount`	string	Yes	The payment amount in the specified currency
`currency`	string	Yes	The currency for the payment (e.g., USD, EUR)
`paymentMethods`	array	No	Array of supported payment methods (defaults to all available)
`expirationMinutes`	number	No	Custom expiration time in minutes (1-1440, defaults to 15 for BTC, 60 for Monero)
`externalInvoiceId`	string	No	Your internal reference ID for the payment
`metadata`	object	No	Additional data to store with the invoice

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

Field	Type	Description
`success`	boolean	Indicates if the invoice was created successfully
`invoiceId`	string	Unique identifier for the created invoice
`expiryTime`	number	Unix timestamp when the invoice expires
`expirationMinutes`	number	Actual expiration time in minutes from creation
`paymentMethods`	array	Available payment methods with details

Payment Method Response Structure

Each payment method includes:

paymentMethodId: Human-readable method name
destination: Cryptocurrency address for payment
paymentLink: Deep link for wallet apps (empty for Monero)
amount: Amount in the specific cryptocurrency
currency: Cryptocurrency symbol

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/invoices \
  -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/invoices', {
  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 invoice = await response.json();
console.log('Invoice created:', invoice.invoiceId);

Python

import requests

url = "https://elyxa.app/api/payments/invoices"
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)
invoice = response.json()
print(f"Invoice created: {invoice['invoiceId']}")

Best Practices

Use minimal requests - just amount and currency for simple cases
Set appropriate expiry times - 15 minutes for fast payments, 60+ for Monero
Include metadata for order tracking and customer information
Handle all payment methods - customers can choose their preferred cryptocurrency
Monitor expiration - invoices automatically expire to avoid rate fluctuations

Rate Limiting

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

Invoice Creation API

On this page