Authentication

All API requests to LuxCore must be authenticated. Most integrations use API keys on API v1. Merchants explicitly onboarded to API v2 use HMAC signatures for payment creation.

Obtaining API Keys

API keys and merchant accounts are created by the LuxCore team during onboarding. Self-registration is not available.

To obtain your API keys:

Contact your LuxCore account manager
Or email developers@lux-core.io

Once your account is set up, you can view your API keys in the Merchant Dashboard under Settings → API Keys.

API Key Types

LuxCore uses API keys to authenticate requests.

Key Types

Key Prefix	Environment	Description
`qp_prod_sk_`	Production	Real transactions with actual money movement
`qp_test_sk_`	Test	Simulated transactions, no real money movement

Keep your API keys secure! Never expose them in client-side code, public repositories, or browser requests.

Making API v1 Authenticated Requests

Include your API key in the X-API-Key header with every request:

curl -X GET "https://api.lux-core.io/api/v1/payments" \
  -H "X-API-Key: qp_prod_sk_your_api_key_here" \
  -H "Content-Type: application/json"

API v2 HMAC Payment Requests

Merchants onboarded to API v2 create payments through:

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

API v2 payment creation does not accept X-API-Key. Each request must be signed with HMAC-SHA256 using the payment HMAC secret issued during onboarding or API v2 enablement. This secret is separate from webhook signing secrets.

Required Headers

Header	Description
`X-Merchant-Id`	Numeric merchant ID
`X-Timestamp`	Unix timestamp in seconds
`X-Nonce`	Unique nonce, 8-128 characters
`X-Signature-Version`	Canonicalization version, currently `v1`
`X-Signature`	`hmac_sha256=<hex digest>`

Canonical String

Build the canonical string exactly as:

v1.{timestamp}.{nonce}.{method}.{path_with_query}.{sha256_raw_body_hex}

Rules:

method is uppercase, for example POST
path_with_query includes /api/v2/payments and any query string exactly as sent
sha256_raw_body_hex is the SHA-256 hash of the raw request body bytes
Reject locally if the timestamp differs from current time by more than 300 seconds
Never reuse a nonce within the 300-second replay window

Node.js Example

const crypto = require('crypto');

const merchantId = '123';
const secret = process.env.LUXCORE_HMAC_SECRET;
const body = JSON.stringify({
  amount: 100050,
  currency: 'MXN',
  method: 'spei',
  type: 'deposit',
  merchant_reference: 'order_123456789',
  customer: { name: 'Juan Perez', email: 'juan@example.com' }
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID().replace(/-/g, '');
const path = '/api/v2/payments';
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const canonical = `v1.${timestamp}.${nonce}.POST.${path}.${bodyHash}`;
const digest = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

await fetch('https://api.lux-core.io/api/v2/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Merchant-Id': merchantId,
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature-Version': 'v1',
    'X-Signature': `hmac_sha256=${digest}`
  },
  body
});

JWT Bearer Token

Some endpoints also support JWT Bearer token authentication as an alternative to API keys.

curl -X GET "https://api.lux-core.io/api/v1/payments" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

For API v1 merchant integrations, API keys are the recommended authentication method. API v2 payment creation uses HMAC. JWT Bearer tokens are available for advanced use cases — contact support for details.

Test Mode vs Production

Test and production requests use the same API endpoint. The environment is determined by your API key type.

Test Mode Behavior

When using test API keys (qp_test_sk_*):

Payments are simulated and do not process real funds
Webhooks are delivered normally for testing integrations
All API responses mirror production behavior
Balance operations use test balances isolated from production
No actual bank transfers or card charges occur

Switching Environments

Simply change your API key to switch between test and production:

# Test mode
curl -H "X-API-Key: qp_test_sk_abc123..." https://api.lux-core.io/api/v1/payments

# Production mode
curl -H "X-API-Key: qp_prod_sk_xyz789..." https://api.lux-core.io/api/v1/payments

API Key Scopes

API keys can be configured with specific scopes to limit access:

Scope	Description
`payments.create`	Create new payments
`payments.read`	View payment details
`payments.view`	View payment details (alias for `payments.read`)
`payments.cancel`	Cancel pending payments
`payments.methods`	Access payment methods info
`webhooks.create`	Create webhook endpoints
`webhooks.read`	View webhook configurations
`webhooks.view`	View webhook configurations (alias for `webhooks.read`)
`webhooks.update`	Modify webhook settings
`webhooks.delete`	Delete webhooks
`balance.read`	View account balances
`balance.view`	View account balances (alias for `balance.read`)

Rate Limits

API requests are rate-limited to ensure fair usage:

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

Rate limits are applied per API key. If you exceed the limit, you’ll receive a 429 Too Many Requests response.

Error Responses

Authentication errors return standard HTTP status codes:

Status Code	Description
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	API key lacks required scope
`429 Too Many Requests`	Rate limit exceeded

Example Error Response

{
  "statusCode": 401,
  "message": "Authentication required. Use either Bearer token or X-API-Key header.",
  "error": "Unauthorized"
}

Best Practices

Use Environment Variables

Store API keys in environment variables, never in code

Rotate Keys Regularly

Regenerate API keys periodically for security

Use Minimal Scopes

Request only the scopes your application needs

Monitor Usage

Track API usage in the dashboard for anomalies

Key Rotation

To rotate your API keys:

Generate a new API key in the Dashboard under Settings -> API Keys
Update your application to use the new key
Verify the new key works correctly
Deactivate the old key in the Dashboard

Multiple API keys can be active simultaneously, allowing zero-downtime rotation. For webhook secret rotation, delete and recreate the webhook endpoint with a new secret.

Getting Started

Guides

SDKs & Examples

Reference

Authentication

Authentication

Obtaining API Keys

API Key Types

Key Types

Making API v1 Authenticated Requests

API v2 HMAC Payment Requests

Required Headers

Canonical String

Node.js Example

JWT Bearer Token

Test Mode vs Production

Test Mode Behavior

Switching Environments

API Key Scopes

Rate Limits

Error Responses

Best Practices

Use Environment Variables

Rotate Keys Regularly

Use Minimal Scopes

Monitor Usage

Key Rotation

Getting Started

Guides

SDKs & Examples

Reference

Documentation Index

​Authentication

​Obtaining API Keys

​API Key Types

​Key Types

​Making API v1 Authenticated Requests

​API v2 HMAC Payment Requests

​Required Headers

​Canonical String

​Node.js Example

​JWT Bearer Token

​Test Mode vs Production

​Test Mode Behavior

​Switching Environments

​API Key Scopes

​Rate Limits

​Error Responses

​Best Practices

Use Environment Variables

Rotate Keys Regularly

Use Minimal Scopes

Monitor Usage

​Key Rotation

Authentication

Obtaining API Keys

API Key Types

Key Types

Making API v1 Authenticated Requests

API v2 HMAC Payment Requests

Required Headers

Canonical String

Node.js Example

JWT Bearer Token

Test Mode vs Production

Test Mode Behavior

Switching Environments

API Key Scopes

Rate Limits

Error Responses

Best Practices

Key Rotation