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 and balance requests.

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	Credentials designated for an agreed testing setup

Key Format

A full API key contains two parts separated by a colon: <key_id>:<secret>. The key ID identifies the credential; the secret is shown when the key is created or rotated. Store the full value securely. Always send the full <key_id>:<secret> value in X-API-Key. Legacy integrations that send only the key ID should migrate to the full format; key-ID-only requests can be rejected with 401 Unauthorized when full-key validation is enforced.

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

Making API v1 Authenticated Requests

Include your full API key (<key_id>:<secret>) 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_key_id:your_secret" \
  -H "Content-Type: application/json"

import requests

headers = {
    "X-API-Key": "qp_prod_sk_your_key_id:your_secret",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.lux-core.io/api/v1/payments",
    headers=headers
)

const axios = require("axios");

const response = await axios.get("https://api.lux-core.io/api/v1/payments", {
  headers: {
    "X-API-Key": "qp_prod_sk_your_key_id:your_secret",
    "Content-Type": "application/json",
  },
});

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.lux-core.io/api/v1/payments");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: qp_prod_sk_your_key_id:your_secret",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

package main

import (
    "log"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api.lux-core.io/api/v1/payments", nil)
    if err != nil {
        log.Fatal(err)
    }
    req.Header.Set("X-API-Key", "qp_prod_sk_your_key_id:your_secret")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
}

API v2 HMAC Requests

Merchants onboarded to API v2 use HMAC-authenticated endpoints:

POST https://api.lux-core.io/api/v2/payments
GET  https://api.lux-core.io/api/v2/payments/{payment_id}
GET  https://api.lux-core.io/api/v2/balance
GET  https://api.lux-core.io/api/v2/balance/all

API v2 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 or GET
path_with_query includes the API v2 path and any query string exactly as sent
sha256_raw_body_hex is the SHA-256 hash of the raw request body bytes
GET requests use an empty raw body hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Reject locally if the timestamp differs from current time by more than 300 seconds
Never reuse a nonce within the 300-second replay window

Examples:

v1.1777893479.1777893479267617000zi3o8qdb.GET./api/v2/payments/pay_example_001.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
v1.1777893479.1777893479267617000zi3o8qdb.GET./api/v2/balance?currency=ARS&balance_type=main.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
v1.1777893479.1777893479267617000zi3o8qdb.GET./api/v2/balance/all.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

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. Confirm the environment with your account manager before creating payments.

Confirm Your Testing Setup

Ask your account manager to confirm the testing endpoint, credentials, enabled routes, recipient fixtures and balance setup before creating payments. Do not assume that changing a key prefix enables simulation or isolates balances. Use only the credentials issued for the agreed environment.

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 endpoint and client IP. 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. Coordinate webhook signing-secret rotation with support and verify signatures using a test delivery before processing payments.

Getting Started

Guides

SDKs & Examples

Reference

Authentication

Authentication

Obtaining API Keys

API Key Types

Key Types

Key Format

Making API v1 Authenticated Requests

API v2 HMAC Requests

Required Headers

Canonical String

Node.js Example

JWT Bearer Token

Test Mode vs Production

Confirm Your Testing Setup

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

​Key Format

​Making API v1 Authenticated Requests

​API v2 HMAC Requests

​Required Headers

​Canonical String

​Node.js Example

​JWT Bearer Token

​Test Mode vs Production

​Confirm Your Testing Setup

​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

Key Format

Making API v1 Authenticated Requests

API v2 HMAC Requests

Required Headers

Canonical String

Node.js Example

JWT Bearer Token

Test Mode vs Production

Confirm Your Testing Setup

API Key Scopes

Rate Limits

Error Responses

Best Practices

Key Rotation