Skip to main content

​
API Changelog

Stay informed about new features, improvements, and breaking changes to the LuxCore API.

​
2026

​
October 2026

​
API key rotation and support ticket attachments
  • After a key rotation with a grace period, the previous key stops working when the grace period ends (before, it stayed active)
  • Keys staged with a scheduled activation time are activated automatically within about a minute of that time; the previous key’s grace period starts at activation
  • Ticket attachment upload URLs are valid for 2 minutes; uploads are limited to 20 per ticket and 200 per merchant per hour, and a file over 10 MB or whose content does not match its declared type is rejected
  • A closed ticket accepts no new attachments or comments (409, TICKET_CLOSED); reopen it first
  • Ticket webhook events are published through the same durable webhook queue as payment events
  • API v2 HMAC authentication is unchanged Payout cancellation and refund eligibility
  • POST /api/v1/payments/{id}/cancel cancels a payout (withdrawal) only while it is pending and not yet assigned for processing; a payout that is processing or already assigned returns 400 Bad Request and keeps its status
  • Deposit cancellation is unchanged
  • Refund requests from the merchant dashboard are accepted only for completed deposits; payouts and payments that are not completed cannot be refunded
​
Bank transfer instructions on hosted checkout
  • Hosted payment pages display bank transfer details when the account is prepared after the checkout link was created
  • Existing payment links, signing and expiry rules are unchanged
​
Merchant authentication and key limits
  • API v1 JWT access now checks the current merchant account status; inactive accounts receive 403 Forbidden
  • Configured API-key daily request limits are counted separately from total usage and reset at midnight UTC; concurrent requests cannot exceed the configured limit
  • Swagger authentication examples include the full <key_id>:<secret> header value
  • API v2 HMAC authentication is unchanged
​
Complete API v1 key examples
  • Authentication and integration examples show the full <key_id>:<secret> header value
  • Legacy integrations that send only the key ID should migrate to the full format to support full-key validation
  • API v2 HMAC authentication is unchanged API v1 merchant access
  • API-key requests require a verified merchant account; suspended or blocked accounts receive 403 Forbidden
  • Access is checked again on subsequent requests after the merchant account becomes active Integration examples and reference updates
  • Updated payment, balance, ticket and webhook examples to match the client API contract
  • Clarified testing prerequisites and safe handling of uncertain payment results
  • Updated the downloadable merchant API specification and documentation links
​
iPay payment return pages
  • Payment return pages display the status returned for the payment, including completed and processing outcomes
  • Merchant return and cancellation redirects preserve existing URL parameters and safely encode the payment reference
​
Fastoo cross-border integration guide
  • Added Fastoo documentation for the existing wallet, bank and SEPA payout contract in API v1/v2, including cURL, Python and Node.js examples
  • Documented client request fields, currency requirements, incoming payment instructions and status handling
  • Clarified how clients handle uncertain payment results; this documentation update changes no API behavior
​
Hosted payment page: exact amounts for every currency scale
  • GET /payment-pages/{token}/details returns two new optional fields in payment: decimal_places (integer 0–8, the currency’s number of decimal places) and amount_minor_exact (the exact amount in minor units as an integer string). The amount in major units is amount_minor_exact / 10^decimal_places
  • payment.amount is now computed with the currency’s decimal places. Previously it always divided the minor amount by 100, which was wrong for currencies without two decimal places (for example CLP or KWD); values for two-decimal currencies are unchanged
  • payment.amount_minor and payment.amount keep their JSON number types. If the currency’s decimal places cannot be determined, decimal_places is omitted and amount keeps the previous two-decimal value
  • Bank-app deep links on the hosted payment page (deep_links) now format the amount with the currency’s decimal places; links for two-decimal currencies are unchanged. If the decimal places cannot be determined, links that carry the amount are not generated; bank details and links without an amount stay available
  • The amount of POST /api/v1/payments and POST /api/v2/payments is now documented as minor units of the currency (previously “cents”); its values and validation are unchanged
  • Merchant API responses (/api/v1/payments, /api/v2/payments, balance) and webhook payloads are unchanged
​
Webhooks: test deliveries are marked, delivery connects only to validated addresses
  • Test deliveries carry the new header X-Webhook-Test: true (test events sent from the back office and POST /api/v1/webhooks/{id}/test). A back-office test event is delivered only to the selected webhook. Real deliveries never carry this header, and a custom header with this name is not sent. Webhook payload fields are unchanged
  • Test deliveries no longer count toward a webhook’s total_events, successful_events, failed_events and success_rate
  • At each delivery attempt the webhook host is resolved once, and every resolved address must be public; the request then connects to a validated address with the original Host header and TLS server name. Redirects are still not followed. When the host cannot be resolved or resolves to a private or reserved address, the attempt is recorded as failed and retried on the usual schedule
  • Creating or updating a webhook, and webhook_url on payment creation, are now refused with 400 (“Invalid webhook URL: Host could not be resolved”) when the host cannot be resolved; previously a DNS failure was accepted
​
Payment creation reliability
  • Payment creation failures provide clearer error explanations
  • After a timeout or unknown creation result, check the original payment before submitting a replacement
  • Payment status values and expiration rules are unchanged
​
Payment API rate limits
  • Payment creation allows 5,000 requests per minute and 500 per 10 seconds per client IP
  • Payment listing and ticket endpoints allow 100 requests per minute; hosted payment pages allow 60 requests per minute and event streams allow 10 per minute
  • Requests over a limit receive 429 Too Many Requests; use Retry-After and the rate-limit response headers to schedule your next request
​
Fastoo payout destinations
  • Payment creation supports payout.fastooDestination for wallet, bank and SEPA payouts with method: "bank_transfer"
  • Use the standard payment status endpoint and webhooks to track results; contact your account manager for route availability
​
Authorization and webhook improvements
  • API-key and Bearer requests consistently enforce access to the merchant’s data
  • Webhook settings support HMAC-SHA256 and HMAC-SHA512; unsupported RSA signing and verify_ssl: false are rejected
  • API reference includes v2 balance and payment-status routes and current webhook test response schemas
​
Payment queries and webhook delivery
  • Payment lists consistently apply pagination and merchant access rules
  • Payment responses return the documented metadata fields
  • Retried webhook deliveries retain their event id and created_at; deduplicate deliveries using the event id

​
May 2026

​
Test webhook payload parity
  • POST /api/v1/webhooks/{webhook_id}/test now sends the same webhook body envelope as automatic payment webhooks: id, created_at, data.payment, and merchant_id
  • Legacy test inputs such as event, payment, timestamp, and raw_payload remain accepted, but are normalized before delivery
  • Test delivery headers now match production-style webhook signature headers and no longer include test-only X-Webhook-Event or X-Webhook-Retry
​
TRY currency documentation
  • Documented Turkish Lira (TRY) as a supported ISO 4217 currency
  • Added TRY to public currency references in the introduction, balance guide, webhook payload reference, and error recovery guidance
  • Added a TRY bank transfer example to the payments guide
​
API v2 HMAC payment lookup and balance polling
  • Added GET /api/v2/payments/{payment_id} for API v2 merchants
  • Added GET /api/v2/balance and GET /api/v2/balance/all for API v2 merchants
  • API v2 GET requests use HMAC-SHA256 authentication with the same X-Merchant-Id, X-Timestamp, X-Nonce, X-Signature-Version, and X-Signature headers
  • GET request signatures use the SHA-256 hash of an empty raw body: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

​
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 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
  • Faster payment creation
  • customer_id field on payments is now optional — payments can be created without a customer identifier
  • A merchant_reference can be reused after its payment fails, expires or is cancelled; check the original outcome before submitting a replacement
  • 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
  • Improved hosted payment page security
  • 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 for implementation details
​
Per-payment traffic type
  • Payments now support an optional traffic_type field (primary, secondary, vip) passed at creation time
  • Payment lists support filtering by traffic type
  • Payment details display the traffic type
  • 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 payment status guidance
  • Expanded the payment guide with iPay checkout instructions, response fields, limits and payment statuses
  • Clarified how to track payments while their status is pending
​
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 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)
  • The same webhook_url can be used for multiple payments
  • Verify in-request webhook signatures using your merchant webhook signing secret
Integration steps
  • Pass webhook_url (and optionally webhook_events) when creating a payment
  • Choose the notification types using webhook_events
  • Notifications are sent to the configured webhook URL
  • Verify signatures using the Webhooks Guide
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)
Breaking changes
  • None (backwards compatible)

​
v1.4.1 - PayID payments

​
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

​
Documented webhook fieldsImproved security and API contract stability for webhook payloads.Changes
  • customer_data contains the documented fields listed below
  • 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 include only the documented fields
  • 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 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
  • Payments can be created without supplying customer_id
  • 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 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)
Payment page improvements
  • Faster payment page loading
  • The payment page updates when the payment status changes
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 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...:4f9c...)
    • Production keys: qp_prod_sk_* (e.g., qp_prod_sk_xyz789...:8e1b...)
  • 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
  • Payment lists support filtering by refund status
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 - Payment Reliability

​
Major improvementsImprovements
  • Improved payment processing reliability
  • 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
  • Faster API responses
  • Faster payment status transitions
Breaking changes
  • None
​
Consistent API responses
  • Improved consistency of API responses across endpoints
Breaking changes
  • None
​
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)
​
Payment validation and balances
  • Enhanced payment method validation rules
  • Improved balance calculation accuracy
Breaking changes
  • None

​
October 2025

​
v1.1.0 - Webhooks Improvements

​
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
​
Webhook delivery fixes
  • Fixed webhook signature generation for consistent verification on client side
  • Improved webhook retry logic with exponential backoff
Breaking changes
  • None
​
Payment limits update
  • Corrected maximum amount validation rules
  • Improved amount formatting in API responses
Breaking changes
  • None
​
API authentication improvements
  • 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
  • More reliable payment notifications
Breaking changes
  • None
​
Balance and withdrawal improvements
  • Resolved issues with balance calculations
  • Fixed withdrawal validation edge cases
  • Clearer handling of expired payments
Breaking changes
  • None
​
API key validation
  • Fixed API key validation in specific edge cases
  • 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
  • Documented how to deduplicate repeated webhook deliveries
  • 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 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
​
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

​
Migration Guides

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