> ## 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.
# Changelog
> Track changes and updates to the LuxCore API
# 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
**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
**Performance & Reliability Overhaul**
**Breaking 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
**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](/guides/webhooks#ordering-and-deduplication) for implementation details
**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
**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`
**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
**`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
**Per-Payment Webhook URL**
You 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
**AUD currency and PayID payment method**
Added 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
**Webhook Payload Whitelist**
Improved 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
**Customer Base & Payment Linking**
New 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
**Standalone Payment Page & Return URL Support**
Major 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
**API key format alignment and validation improvements**
This 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
**Major improvements**
Following 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
**Enhanced testing and quality of life**
* Improved consistency of API responses across endpoints
**Breaking changes**
* None
**LKR currency and iPay payment method**
Added 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)
**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
**Webhook manager improvements**
**New 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
**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
**Payment limits update**
* Corrected maximum amount validation rules
* Improved amount formatting in API responses
**Breaking changes**
* None
**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
**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
**Balance and withdrawal improvements**
* Resolved issues with balance calculations
* Fixed withdrawal validation edge cases
* Improved payment and requisite lock expiry handling
**Breaking changes**
* None
**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
**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
**Payment processing enhancements**
* Improved SPEI transfer handling
* Enhanced bank account validation (CLABE format)
* More informative error messages for invalid bank accounts
**Breaking changes**
* None
**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
**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
**Public API v1.0.0 release**
Public 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
**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.
***
{/* Check current API status and subscribe to incident updates. */}