Quickstart

1. Select the environment

LuxPay provisions sandbox and production base URLs separately. Do not duplicate the host throughout your codebase; use a configuration value such as LUXPAY_BASE_URL and bind it per deployment environment. Start with GET /health and require the service to return status: ok before running a smoke workflow.

2. Obtain an access token

Customer applications use customer registration or login. Business systems use the business employee login or a service credential explicitly provisioned by LuxPay. Send the token as Authorization: Bearer <token> over HTTPS only. Do not retain the password after authentication.

3. Read wallets and balance

Call GET /wallets, select the returned wallet identifier, then call GET /wallets/{walletId}/balance. Available balance is not always the same as cached balance because held funds are excluded. Never recompute authoritative balances from a client-side transaction list.

4. Perform a safe mutation

Generate a unique idempotency key and call Create transfer. If the connection drops, retry with the same key instead of creating a new one. Persist the transaction or transfer identifier returned by LuxPay, then reconcile through transaction history or the relevant payment status endpoint.

5. Prepare for production

Apply connection timeouts, bounded retries with backoff, and request correlation using X-Request-ID. Treat 401, 403, 409, 422, and 429 as distinct conditions, and do not expose internal server messages directly to end users.