API Reference

This section provides detailed documentation for all LuxCore API endpoints.

Base URL

https://api.lux-core.io/api/v1

API v2 HMAC payment and balance endpoints are available at:

https://api.lux-core.io/api/v2

Authentication

API v1 endpoints require an API key in the X-API-Key header:

curl -H "X-API-Key: qp_test_sk_your_key_id:your_secret" https://api.lux-core.io/api/v1/payments

Endpoints

Payments

Method	Endpoint	Description
`POST`	`/payments`	Create a new payment
`POST`	`/payments` on the API v2 base URL	Create a new payment with HMAC authentication for API v2 merchants
`GET`	`/payments/{id}` on the API v2 base URL	Get payment by ID with HMAC authentication for API v2 merchants
`GET`	`/payments`	List payments
`GET`	`/payments/{id}`	Get payment by ID
`POST`	`/payments/{id}/cancel`	Cancel a payment
`GET`	`/payments/methods`	Get available payment methods
`POST`	`/payments/methods/validate`	Validate a payment method

Fastoo Payment Routing

The existing v1/v2 payment creation endpoints accept payout.fastooDestination for withdrawal or withdrawal_pp with method: "bank_transfer". It supports wallet lookup, saved bank/SEPA accounts and inline bank beneficiaries. Typed Fastoo and legacy payout destinations cannot be combined. Use the standard payment status endpoints and webhooks to track Fastoo payments. See Fastoo Cross-Border Payments for destination formats, currency requirements and examples.

Webhooks

Method	Endpoint	Description
`POST`	`/webhooks`	Create a webhook
`GET`	`/webhooks`	List webhooks
`GET`	`/webhooks/{id}`	Get webhook by ID
`PUT`	`/webhooks/{id}`	Update webhook
`DELETE`	`/webhooks/{id}`	Delete webhook
`POST`	`/webhooks/{id}/test`	Send test event
`PUT`	`/webhooks/{id}/enable`	Enable webhook
`PUT`	`/webhooks/{id}/disable`	Disable webhook
`GET`	`/webhooks/{id}/events`	Get webhook events
`POST`	`/webhooks/{id}/retry`	Retry failed events
`GET`	`/webhooks/{id}/audit`	Read webhook configuration history
`GET`	`/webhooks/{webhookId}/events/{eventId}/signature`	Read event signature metadata

Balance

Method	Endpoint	Description
`GET`	`/balance`	Get balance by currency
`GET`	`/balance` on the API v2 base URL	Get balance by currency with HMAC authentication for API v2 merchants
`GET`	`/balance/all`	Get all balances
`GET`	`/balance/all` on the API v2 base URL	Get all balances with HMAC authentication for API v2 merchants
`GET`	`/merchants/{id}/balance`	Get merchant balance
`GET`	`/merchants/{id}/balance/all`	Get all merchant balances

Tickets

Method	Endpoint	Description
`POST`	`/tickets`	Create a support ticket
`GET`	`/tickets`	List tickets
`GET`	`/tickets/{id}`	Get ticket details
`POST`	`/tickets/{id}/close`	Close a ticket
`POST`	`/tickets/{id}/reopen`	Reopen a ticket
`POST`	`/tickets/{id}/comments`	Add a comment
`GET`	`/tickets/{id}/comments`	List comments
`POST`	`/tickets/{id}/upload-url`	Generate attachment upload URL
`GET`	`/tickets/{id}/attachments/{attachmentId}`	Download ticket attachment
`GET`	`/tickets/{id}/comments/{commentId}/attachments/{attachmentId}`	Download comment attachment

Common Parameters

Pagination

List endpoints support pagination:

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (max 100)
`offset`	integer	0	Number of results to skip

Filtering

Most list endpoints support filtering by common fields:

Parameter	Type	Description
`status`	string	Filter by status
`created_at_from`	ISO 8601	Start date
`created_at_to`	ISO 8601	End date

Response Format

Success Response

Response formats depend on the endpoint: payment creation returns its payment object directly; list endpoints return an envelope. This is a list example:

{
  "success": true,
  "data": [],
  "total": 0,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_pages": 0
  }
}

Error Response

Business logic errors include error_code and timestamp:

{
  "statusCode": 400,
  "message": "Payment cannot be cancelled in current status: completed",
  "error_code": "PAYMENT_ALREADY_PROCESSED",
  "timestamp": "2025-01-28T10:00:00.000Z"
}

Validation errors include a readable message and an error_code; clients may also encounter a legacy error label:

{
  "statusCode": 400,
  "message": "amount must not be less than 1; merchant_reference must be a string",
  "error_code": "BAD_REQUEST"
}

Rate Limits

Endpoint Type	Limit
Payment creation	5000 requests/minute (burst: 500/10sec)
Standard endpoints	100 requests/minute

Limits are per endpoint and client IP. X-RateLimit-Reset and Retry-After are relative seconds; the burst window uses a -burst header suffix. For example:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 45

OpenAPI Specification

Download the OpenAPI specification for use with code generators and API clients:

Download OpenAPI Spec

OpenAPI 3.0 JSON specification

Using the Reference

Use the linked guides for workflows and the downloadable merchant OpenAPI specification for request/response schemas. It covers merchant API operations and hosted payment-page lookups; provider callbacks are outside this integration reference.

Getting Started

Guides

SDKs & Examples

Reference

API Reference Overview

API Reference

Base URL

Authentication

Endpoints

Payments

Fastoo Payment Routing

Webhooks

Balance

Tickets

Common Parameters

Filtering

Response Format

Success Response

Error Response

Rate Limits

OpenAPI Specification

Download OpenAPI Spec

Using the Reference

​API Reference

​Base URL

​Authentication

​Endpoints

​Payments

​Fastoo Payment Routing

​Webhooks

​Balance

​Tickets

​Common Parameters

​Pagination

​Filtering

​Response Format

​Success Response

​Error Response

​Rate Limits

​OpenAPI Specification

Download OpenAPI Spec

​Using the Reference

API Reference

Base URL

Authentication

Endpoints

Payments

Fastoo Payment Routing

Webhooks

Balance

Tickets

Common Parameters

Pagination

Filtering

Response Format

Success Response

Error Response

Rate Limits

OpenAPI Specification

Using the Reference