Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lux-core.io/llms.txt

Use this file to discover all available pages before exploring further.

​
API Changelog

Stay informed about new features, improvements, and breaking changes to the LuxCore API.
Subscribe to our developer newsletter to receive changelog updates via email.

​
2026

​
April 2026

​
2026-04-29
API v2 HMAC payment creation
  • Added a merchant-scoped POST /api/v2/payments endpoint for merchants onboarded to API v2
  • API v2 payment creation uses HMAC-SHA256 request signing instead of X-API-Key
  • API v2 HMAC request headers use X-Merchant-Id, X-Timestamp, X-Nonce, X-Signature-Version, and X-Signature
  • Signatures cover the raw request body hash, method, path with query string, Unix timestamp, and nonce
  • Requests outside a 300-second timestamp window or with a reused nonce are rejected
  • Existing API v1 endpoints and API-key authentication remain unchanged for v1 merchants
  • API v2 payment HMAC secrets are separate from webhook signing secrets and are shown only when issued or rotated
  • Switching a merchant from API v1 to API v2 revokes active API keys and issues one-time HMAC credentials

​
March 2026

​
2026-03-17
Performance & Reliability OverhaulBreaking Change
  • Payment amount field now enforces integer validation — values must be whole numbers representing minor currency units (e.g., cents). Requests with decimal/float amounts will be rejected with a 400 error. If you were previously sending integer values, no changes are needed.
Improvements
  • Payment creation latency reduced significantly through internal architecture optimizations (eliminated inter-service network round-trips for requisite selection)
  • customer_id field on payments is now optional — payments can be created without a customer identifier
  • merchant_reference uniqueness constraint relaxed: duplicate references are now allowed for failed, expired, and cancelled payments, preventing spurious conflicts on retried payment flows
  • Payment page: improved loading experience with skeleton placeholders instead of spinner
  • Payment page: added countdown timer for payment expiration
  • Payment page: sensitive URL parameters are now stripped from the browser address bar after loading
  • Payment page: security headers hardened (X-Frame-Options, Content-Security-Policy, Permissions-Policy)
  • Improved error responses with structured error codes and consistent formatting across all API endpoints
  • Overall platform reliability and resilience improvements under high concurrency
​
2026-03-10
Webhook ordering support
  • Webhook payloads now include a status_version field — a monotonically increasing integer that increments with every payment status change
  • Use status_version to detect out-of-order or duplicate webhooks: ignore events where status_version is less than or equal to the last processed version
  • See the Webhooks Guide for implementation details
​
2026-03-01
Per-payment traffic type
  • Payments now support an optional traffic_type field (primary, secondary, vip) passed at creation time
  • Admin panel: new traffic type filter on the payments list and stats pages
  • Admin panel: traffic type badge displayed in payment details drawer
  • CSV export includes the traffic_type column

​
February 2026

​
2026-02-26
Support Tickets API
  • New public API endpoints for merchant ticket management (/tickets)
  • Create, list, and view support tickets via API
  • Add and list comments on tickets with attachment support
  • Close and reopen tickets programmatically
  • File attachments via pre-signed upload/download URLs
  • Admin replies on merchant tickets now trigger ticket.comment_added webhook
  • New webhook events: ticket.created, ticket.updated, ticket.comment_added, ticket.resolved, ticket.closed
  • New API key scopes: tickets.create, tickets.read, tickets.update
​
2026-02-26
iPay integration hardening
  • Pending payment monitor: iPay payments with “Pending” (end-of-day settlement) status are now automatically monitored. Alerts are sent after 6 hours, and payments are auto-cancelled after 24 hours if unresolved
  • Amount mismatch alerting: Real-time alerts are now triggered when an iPay callback reports an amount that doesn’t match the expected payment amount
  • Rate limiting: Provider callback endpoints now enforce rate limits (300 req/min) to prevent abuse, replacing the previous unlimited access
  • Documentation: Added iPay integration details including redirect flow, response fields, limits, and callback status mapping to the Payments Guide
​
2026-02-17
payment.refunded added to default webhook events
  • payment.refunded is now included in the default set of webhook events for both in-request and admin-created webhooks
  • New default: payment.created, payment.completed, payment.failed, payment.refunded
  • Existing webhooks are not affected — only newly created webhooks will include payment.refunded by default
  • To receive refund events on existing webhooks, update the events array via the API or pass webhook_events explicitly when creating payments

​
January 2026

​
v1.5.0 - In-Request Webhooks

​
2026-01-30
Per-Payment Webhook URLYou can now pass a webhook URL directly in the payment creation request, enabling per-payment notification routing without pre-configuring webhooks.New Features
  • webhook_url: Optional field in POST /payments — specify a URL to receive webhook events for this specific payment
  • webhook_events: Optional array to choose which events to subscribe to (defaults to payment.created, payment.completed, payment.failed, payment.refunded)
  • Automatic deduplication: If the same merchant sends the same webhook_url across multiple payments, the system reuses the existing webhook configuration
  • Default webhook secret: In-request webhooks are signed using a per-merchant default secret, visible in the merchant settings panel
How it works
  • Pass webhook_url (and optionally webhook_events) when creating a payment
  • The system automatically creates (or reuses) a webhook endpoint for your merchant
  • Events are delivered to both admin-configured webhooks and in-request webhooks in parallel
  • In-request webhooks use the same HMAC-SHA256 signature verification as admin webhooks
API Changes
  • POST /payments now accepts optional webhook_url (string, max 2048 chars) and webhook_events (string array)
  • In-request webhooks are excluded from GET /webhooks listing by default (use ?source=in_request to view them)
  • Merchant detail response now includes default_webhook_secret field
Breaking changes
  • None (backwards compatible)

​
v1.4.1 - PayID payments

​
2026-01-22
AUD currency and PayID payment methodAdded support for Australian Dollar (AUD) and PayID as a new payment method.New Features
  • AUD currency: Full support for Australian Dollar deposits and withdrawals
  • PayID method (payid): Near-instant payments via Australia’s New Payments Platform (NPP). Customers can pay using an email address, phone number, or ABN as the PayID identifier
  • PayID deposits: Customers send funds to a dynamically generated PayID. Response includes payid_details with the PayID identifier and reference
  • PayID withdrawals: Send payouts to a recipient’s PayID (email, phone, or ABN) instead of BSB/account number
  • AUD bank transfers: Traditional BSB + account number method also supported for both deposits and withdrawals
API Changes
  • POST /payments now accepts "currency": "AUD" with methods bank_transfer or payid
  • For AUD bank transfers, bank_details response includes bsb field (6-digit BSB code)
  • For PayID deposits, response includes payid_details object with payid, payid_type, payid_name, and reference
  • For PayID withdrawals, payout object accepts payid and payid_type fields instead of bank_account/bank_code
  • payid_type accepts: email, phone, abn
Breaking changes
  • None (backwards compatible)

​
v1.4.0 - Webhook Security & Contract Stabilization

​
2026-01-20
Webhook Payload WhitelistImproved security and API contract stability for webhook payloads.Changes
  • customer_data in webhook payloads now uses a whitelist approach — only specific, documented fields are included
  • Internal processing data (IP addresses, user agents, internal IDs, processing metadata) is no longer sent to merchant webhooks
  • payout object is now only included for withdrawal type payments (not for deposits)
Allowed customer_data fields
  • Top-level: note, customer_email, customer_phone, customer_name, external_id, reference, description, expires_at, requested_payment_type
  • commission: currency, total_minor
  • payout (withdrawals only): bank_code, bank_account, recipient_name, bank_name
Breaking changes
  • Webhook payloads no longer include internal fields that were previously exposed unintentionally
  • If your integration relied on undocumented fields in customer_data, you may need to update your webhook handler

​
2025

​
December 2025

​
v1.3.0 - Customer Management System

​
2025-12-22
Customer Base & Payment LinkingNew customer management system that enables tracking and analytics across payments.New Features
  • Customer ID: Merchants can optionally pass customer_id when creating payments to link to an existing customer
  • Auto-linking: When customer_id is not provided, customers are automatically created/matched by email or phone
  • Customer Data in Response: Payment responses now include customer object with id, email, phone, name
API Changes
  • POST /payments now accepts optional customer_id field (integer)
  • Payment responses include customer_id and customer object
  • customer object in request body remains required (name, email, phone)
Breaking changes
  • None (backwards compatible)

​
v1.2.2 - Payment Page Enhancements

​
2025-12-03
Standalone Payment Page & Return URL SupportMajor improvements to the hosted payment page experience.New Features
  • Return URLs: Merchants can now provide success_url and cancel_url for merchant settings for automatic redirect after payment completion
  • Mercado Pago Integration: Quick-pay button with deep link support (mobile devices only)
Technical Changes
  • Improved bundle size and performance
  • Fixed SSE event handling for real-time payment status updates
  • Payment page now correctly updates UI when payment status changes via SSE
API Changes
  • GET /payment-pages/:token/details now returns return_urls object with success_url and cancel_url
Breaking changes
  • None (backwards compatible)

​
v1.2.1 - API Consistency & Validation

​
2025-12-02
API key format alignment and validation improvementsThis release fixes inconsistencies between API validation, documentation, and Swagger schemas.API Key Format Changes
  • Standardized API key format validation:
    • Test keys: qp_test_sk_* (e.g., qp_test_sk_abc123...)
    • Production keys: qp_prod_sk_* (e.g., qp_prod_sk_xyz789...)
  • Removed support for deprecated formats: qp_sandbox_sk_*, qp_live_*
  • Updated all documentation and Swagger examples to reflect correct key formats
Payment Status Updates
  • Added refunded and partial_refund statuses to payment API schemas
  • Payment pages now correctly display refund statuses
  • DTOs and filters now support filtering by refund statuses
Withdrawal Validation
  • recipient_name and bank_account are now required fields for withdrawal requests for ARS flow.
  • Improved error messages for missing payout details
  • Consistent validation across all withdrawal types
Documentation Fixes
  • Payment page URLs are now documented as dynamic (vary by currency/method/region)
  • Updated all code examples with correct API key formats
  • Clarified payout field requirements for different countries
Breaking changes
  • API keys using qp_sandbox_sk_* or qp_live_* formats will no longer be accepted
  • Withdrawal requests without recipient_name or bank_account will return 400 Bad Request

​
November 2025

​
v1.2.0 - Production Stability Release

​
2025-11-29
Major improvementsFollowing the successful scaling deployment, we shipped a set of optimizations based on real world usage patterns.Improvements
  • Optimized payment processing pipeline for higher throughput
  • Increased rate limits for payment creation to 5000 requests per minute (burst: 500 requests per 10 seconds)
  • Improved webhook delivery reliability and retry mechanism
  • More descriptive error messages for validation failures
Performance
  • Reduced average API response time by about 40%
  • Faster payment status transitions
Breaking changes
  • None
​
2025-11-25
Enhanced testing and quality of life
  • Improved consistency of API responses across endpoints
Breaking changes
  • None
​
2025-11-22
LKR currency and iPay payment methodAdded support for Sri Lankan Rupee (LKR) and iPay as a new payment method.New Features
  • LKR currency: Full support for Sri Lankan Rupee deposits
  • iPay method (ipay): Redirect-based online payments for Sri Lanka. Customers are redirected to a hosted checkout page to complete payment via Visa, Mastercard, LankaQR, or iPay App
  • Payment scheme filtering: Optionally restrict to a single scheme (VISA, MC, IPAY, LQR) via ipay.payment_method field in the request
API Changes
  • POST /payments now accepts "currency": "LKR" with method ipay
  • Response includes redirect_url for customer redirect to complete payment
  • Optional ipay object in request body accepts payment_method field to filter available payment schemes
Breaking changes
  • None (backwards compatible)
​
2025-11-18
Optimization and refactors
  • Internal architecture improvements for better scalability
  • Enhanced payment method validation rules
  • Improved balance calculation accuracy
Breaking changes
  • None

​
October 2025

​
v1.1.0 - Webhooks Improvements

​
2025-10-30
Webhook manager improvementsNew features
  • Enhanced webhook signature binding for improved security and verification
Developer note
  • Make sure your webhook handlers are idempotent to safely handle retries.
Breaking changes
  • None
​
2025-10-24
Webhook delivery fixes
  • Fixed webhook signature generation for consistent verification on client side
  • Improved webhook retry logic with exponential backoff
  • Enhanced request binding for webhook payloads
Breaking changes
  • None
​
2025-10-22
Payment limits update
  • Corrected maximum amount validation rules
  • Improved amount formatting in API responses
Breaking changes
  • None
​
2025-10-17
Production deployment optimizations
  • Enhanced API key handling and validation
  • Improved error responses for invalid credentials
  • Added support for additional payment method configurations
Breaking changes
  • None
Deprecation notice
  • API key formats qp_sandbox_sk_* and qp_live_* are deprecated and will stop working in December 2025
  • Please use the standard formats: qp_test_sk_* for test mode, qp_prod_sk_* for production

​
September 2025

​
v1.0.2 - Integration Fixes

​
2025-09-14
Webhook flow corrections
  • Fixed payment.completed webhook not being sent in some scenarios
  • Improved webhook scheduling reliability
  • Enhanced stale webhook detection and cleanup
Breaking changes
  • None
​
2025-09-10
Balance and withdrawal improvements
  • Resolved issues with balance calculations
  • Fixed withdrawal validation edge cases
  • Improved payment and requisite lock expiry handling
Breaking changes
  • None
​
2025-09-08
API key and proxy compatibility
  • Fixed API key validation in specific edge cases
  • Improved proxy compatibility by handling X-Forwarded-Host headers
  • Strengthened request validation
Breaking changes
  • None
​
2025-09-05
Documentation updates
  • Updated API documentation with corrected parameters
  • Removed redundant request parameters
  • Improved example payloads
Breaking changes
  • None

​
August 2025

​
v1.0.1 - Private Beta Improvements

​
2025-08-28
Payment processing enhancements
  • Improved SPEI transfer handling
  • Enhanced bank account validation (CLABE format)
  • More informative error messages for invalid bank accounts
Breaking changes
  • None
​
2025-08-15
Webhook reliability improvements
  • Added automatic retry for failed webhook deliveries
  • Implemented webhook event deduplication
  • Enhanced HMAC-SHA256 signature verification
Developer note
  • Webhook receivers should remain idempotent due to retries and deduplication.
Breaking changes
  • None
​
2025-08-05
Balance API enhancements
  • Added /balance/all endpoint for multi-currency support
  • Improved balance precision handling
  • Added available and pending balance breakdown
Breaking changes
  • None

​
July 2025

​
v1.0.0 - Initial Release

​
2025-07-25
Public API v1.0.0 releasePublic release of the LuxCore Payment Gateway API.Core features
  • Payment creation (deposits and withdrawals)
  • Multiple payment methods support
  • Hosted payment pages (deposit_pp, withdrawal_pp)
  • Real time webhook notifications
  • Balance inquiry API
  • Test and production modes via API key prefixes (qp_test_sk_*, qp_prod_sk_*)
Supported payment methods
  • bank_transfer - bank transfers (Argentina, Uruguay)
  • spei - Mexican interbank transfers (SPEI)
  • oxxo - cash payments at OXXO stores
  • card - credit and debit cards (tokenized)
  • cash - cash payments
  • crypto - cryptocurrency payments
Supported currencies
  • ARS - Argentine peso
  • UYU - Uruguayan peso
  • MXN - Mexican peso
Webhook events
  • payment.created - payment initialized
  • payment.processing - payment is being processed
  • payment.completed - payment successful
  • payment.failed - payment failed
  • payment.cancelled - payment cancelled
  • payout.created - payout initiated
  • payout.completed - payout successful
  • payout.failed - payout failed
​
2025-07-10
Private beta launch
  • Initial API endpoints for selected partners
  • Core payment functionality
  • Basic webhook support
  • Authentication via API keys

​
Versioning Policy

The LuxCore API uses semantic versioning:
  • Major versions (v1, v2) indicate breaking changes
  • Minor versions add new features that are backwards compatible
  • Patches include bug fixes and minor improvements

​
Breaking changes

We strive to minimize breaking changes. When they occur:
  1. We announce them at least 1 month in advance
  2. We provide migration guides
  3. We support the previous version during a transition period

​
Deprecation policy

Deprecated features will:
  • Be announced in the changelog
  • Continue working for at least 3 months
  • Return deprecation warnings in API responses when possible

​
Upcoming Changes

These features are in development. Timelines are estimates and may change.

​
Q2 2026 (planned)

  • Programmatic Refunds - Initiate refunds via API instead of support tickets
  • Transaction Reports - Export transaction history and analytics
  • Batch Payouts - Bulk payout operations (up to 1000 payouts per request)
  • Webhook Filtering - Subscribe to specific event types and filter by criteria
  • Additional currencies - CLP (Chilean peso)

​
Migration Guides

When breaking changes occur, we will publish detailed migration guides here.