Invoice Retrieval API

The Elyxa API allows you to retrieve detailed information about existing payment invoices. 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

Retrieve Invoice Endpoint

Retrieve detailed information about a specific invoice using its ID.

GET https://elyxa.app/api/payments/invoices?invoiceId=INVOICE_ID

Query Parameters:

Parameter	Type	Required	Description
`invoiceId`	string	Yes	The unique identifier of the invoice to retrieve

Response:

{
    "success": true,
    "invoice": {
        "invoiceId": "CUghtjLMfkCnYW68whtzp4",
        "externalInvoiceId": "order_12345",
        "amount": 25.5,
        "currency": "USD",
        "fiatAmount": 25.5,
        "fiatCurrency": "USD",
        "status": "pending",
        "paymentMethods": [
            {
                "methodId": "LIGHTNING",
                "destination": "lnbc210760n1p5fnnatpp58vxh0z3dg482njrm7enknre50ww8kv3c9u7tflc0tr8rxqmer65sdp02pskjepqw3hjqjtww3shxetwvsszsnmjv3jhygzfgsazq2gcqzzsxqzuzsp5plx88ynxfganht7x26w07zulfp6yurzpdj660l5sr8v36hy55uts9qxpqysgqr4dhg2s0na57fxkgmj4vnnqpy59qxfggljcjkr3sqaucz4rhcmrn6p92ecsjjfuuvmgt7ulw5r7hdauvhper7w3g7y2ralvj9xvww2cp570lcw",
                "amount": 0.00021076,
                "currency": "BTC",
                "isPaid": false,
                "paidAmount": null,
                "paidAt": null
            },
            {
                "methodId": "BITCOIN",
                "destination": "bc1qgvj4kwq33y9gdjr7nmkna9wrzr6pj8f8f9pudg",
                "amount": 0.00021076,
                "currency": "BTC",
                "isPaid": false,
                "paidAmount": null,
                "paidAt": null
            }
        ],
        "expiryTime": "2025-08-11T11:25:35.000Z",
        "metadata": {
            "description": "Sample order payment",
            "orderId": "order_12345"
        },
        "createdAt": "2025-08-11T11:14:43.572Z",
        "updatedAt": "2025-08-11T11:29:43.761Z",
        "isExpired": false,
        "isFullyPaid": false,
        "paidAmount": 0
    }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`invoice`	object	The complete invoice object

Invoice Object Fields

Field	Type	Description
`invoiceId`	string	Unique identifier for the invoice
`externalInvoiceId`	string	External reference ID (if provided)
`amount`	number	The payment amount in the specified currency
`currency`	string	The currency for the payment
`fiatAmount`	number	The fiat amount (if different from amount)
`fiatCurrency`	string	The fiat currency (if different from currency)
`status`	string	Current status: `pending`, `paid`, `expired`, `cancelled`, or `refunded`
`paymentMethods`	array	Array of available payment methods with payment details
`expiryTime`	string	ISO 8601 timestamp when the invoice expires
`metadata`	object	Additional metadata associated with the invoice
`createdAt`	string	ISO 8601 timestamp when the invoice was created
`updatedAt`	string	ISO 8601 timestamp when the invoice was last updated
`isExpired`	boolean	Whether the invoice has expired
`isFullyPaid`	boolean	Whether the invoice has been fully paid
`paidAmount`	number	Total amount paid across all payment methods

Payment Method Fields

Field	Type	Description
`methodId`	string	Payment method identifier (e.g., `BITCOIN`, `LIGHTNING`, `MONERO`)
`destination`	string	Payment destination address or invoice
`amount`	number	Amount in the payment method's currency
`currency`	string	Currency for this payment method
`isPaid`	boolean	Whether this payment method has been paid
`paidAmount`	number	Amount actually paid (if different from requested amount)
`paidAt`	string	ISO 8601 timestamp when payment was received (if paid)

Example: Paid Invoice

Here's an example response for a fully paid invoice:

{
    "success": true,
    "invoice": {
        "invoiceId": "PaidInvoice123",
        "amount": 50.0,
        "currency": "USD",
        "status": "paid",
        "paymentMethods": [
            {
                "methodId": "BITCOIN",
                "destination": "bc1qgvj4kwq33y9gdjr7nmkna9wrzr6pj8f8f9pudg",
                "amount": 0.00123456,
                "currency": "BTC",
                "isPaid": true,
                "paidAmount": 0.00123456,
                "paidAt": "2025-08-11T11:20:15.000Z"
            }
        ],
        "expiryTime": "2025-08-11T11:25:35.000Z",
        "metadata": {},
        "createdAt": "2025-08-11T11:14:43.572Z",
        "updatedAt": "2025-08-11T11:20:15.000Z",
        "isExpired": false,
        "isFullyPaid": true,
        "paidAmount": 0.00123456
    }
}

Example: Expired Invoice

Here's an example response for an expired invoice:

{
    "success": true,
    "invoice": {
        "invoiceId": "ExpiredInvoice456",
        "amount": 25.5,
        "currency": "USD",
        "status": "expired",
        "paymentMethods": [
            {
                "methodId": "LIGHTNING",
                "destination": "lnbc210760n1p5fnnatpp58vxh0z3dg482njrm7enknre50ww8kv3c9u7tflc0tr8rxqmer65sdp02pskjepqw3hjqjtww3shxetwvsszsnmjv3jhygzfgsazq2gcqzzsxqzuzsp5plx88ynxfganht7x26w07zulfp6yurzpdj660l5sr8v36hy55uts9qxpqysgqr4dhg2s0na57fxkgmj4vnnqpy59qxfggljcjkr3sqaucz4rhcmrn6p92ecsjjfuuvmgt7ulw5r7hdauvhper7w3g7y2ralvj9xvww2cp570lcw",
                "amount": 0.00021076,
                "currency": "BTC",
                "isPaid": false
            }
        ],
        "expiryTime": "2025-08-11T11:25:35.000Z",
        "metadata": {},
        "createdAt": "2025-08-11T11:14:43.572Z",
        "updatedAt": "2025-08-11T11:29:43.761Z",
        "isExpired": true,
        "isFullyPaid": false,
        "paidAmount": 0
    }
}

Error Responses

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

Missing Invoice ID

{
    "error": "Invoice ID is required"
}

Status Code: 400

Invoice Not Found

{
    "error": "Invoice not found"
}

Status Code: 404

Authentication Error

{
    "error": "Invalid API key"
}

Status Code: 401

Server Error

{
    "error": "Internal server error",
    "success": false
}

Status Code: 500

Usage Examples

cURL

curl -X GET \
  "https://elyxa.app/api/payments/invoices?invoiceId=CUghtjLMfkCnYW68whtzp4" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (Fetch)

const response = await fetch(
  `https://elyxa.app/api/payments/invoices?invoiceId=${invoiceId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data.invoice);

Python (requests)

import requests

response = requests.get(
    f"https://elyxa.app/api/payments/invoices?invoiceId={invoice_id}",
    headers={"Authorization": f"Bearer {api_key}"}
)

invoice_data = response.json()
print(invoice_data["invoice"])

Notes

Only merchants can retrieve their own invoices
The API key must belong to the merchant who created the invoice
All timestamps are returned in ISO 8601 format (UTC)
Payment amounts are returned in the original currency of the payment method
The isExpired and isFullyPaid fields provide convenient boolean checks for common invoice states

Invoice Retrieval API

On this page