Authentication

The Wallet API runs on separate surfaces, each with its own identity model. Picking the wrong surface is the most common integration mistake: endpoints your server calls live under /api/v1/wallet/*, endpoints the end user's app calls live under /api/portal/v1/wallet/*, and endpoints your operations team uses live under /api/panel/v1/wallet/*. The three identity models are below; for measured endpoint counts and cross-surface overlap see the matrix right after.

Base URL: https://api-gateway.lunixi.com.

Surface comparison matrix

There are in fact four surfaces: three carry one of the identity models above, and the fourth is a single endpoint reserved for terminal activation. The endpoint counts below are counted from the running controllers, not from documentation.

Of the panel's 186 endpoints, 162 live in the main controller and 10 in the four-eyes request controller; the remaining 14 are in the card (7), cash-out (4) and card-event webhook (3) controllers.

How much do panel and s2s overlap?

The 139 capabilities that exist in the panel and have no s2s counterpart:

External API (s2s) — signed requests

The wallet s2s surface is signature-based: every request is signed with your Ed25519 private key. You do not additionally send a Bearer API key here — the signature is your identity.

Get your key

Create a secret key under API Keys in the merchant panel. Two provisioning models exist:

• Platform (reveal-once) — the platform generates the key pair, registers the public key and shows you the private key exactly once. Once you close that screen it cannot be retrieved; if lost, rotate.
• BYO (bring your own) — you generate the key pair and upload only the public key. The private key never reaches the platform; this is the safest option.

# Generate an Ed25519 key pair for BYO
openssl genpkey -algorithm ed25519 -out lunixi-signing.key
openssl pkey -in lunixi-signing.key -pubout -out lunixi-signing.pub

The key's id (kid) goes in the X-Key-Id header.

Key permissions

After the signature, every request passes two more checks:

1. Product — the key must list the wallet product (WALLET_SERVICE). Otherwise every endpoint, reads included, returns 403 PRODUCT_NOT_ENABLED.
2. Permission — the key must carry the wallet permission for the call. Permissions are enforced fail-closed: a call the key is not permitted for returns 403 WALLET_INSUFFICIENT_SCOPE, and a key with no wallet permission can do nothing on the wallet.

Permissions are not hierarchical: a read permission does not allow writes, and a set-up permission never moves money.

What that means in practice:

• A reporting or support integration can be given read permissions only; it cannot call transfers/w2w or withdrawals/bank.
• Money leaving the platform needs its own permission: wallet:operation:intervene alone cannot send money to an IBAN or a bank account.
• If a call returns WALLET_INSUFFICIENT_SCOPE, add the permission from the table above to the key in the panel.
• Also fill in the key's IP allow-list for production keys.

Request headers

Canonical string

The signed text is these lines joined with \n:

POST
/api/v1/wallet/transfers/w2w
X-Date:2026-08-07T12:00:00.000Z
X-Nonce:9f8d2c4e-1a3b-4c5d-8e7f-0a1b2c3d4e5f
Digest:SHA-256=k6I5cUt...=

Digest and compact JSON

The server parses the JSON body and recomputes the SHA-256 digest over its compact form — no line breaks and no spaces between tokens. Send the body as compact JSON and compute Digest over exactly the string you send. A pretty-printed body fails with 401 INVALID_DIGEST, even when its content is the same. In Node.js, JSON.stringify(body) without an indent argument produces the right form.

Idempotency-Key

The header is trimmed and must be 1–128 characters. On the endpoints below it is required; a missing or blank header is rejected with 400:

• End users and wallets: POST end-users, POST end-users/:id/freeze, PUT end-users/:id/kyc-level, POST end-users/:id/wallets, POST wallets/:id/accounts
• Corporate accounts: POST corporate-accounts, employees/import, employees/offboard
• Transfers and withdrawals: transfers/w2w, transfers/w2iban and withdrawals/bank — both initiate and complete
• Top-ups and payments: topups/card, agent-topups, payments/buy, payments/:id/approve, collect
• POST qr, POST bulk-payouts

It is not required on quotes, GET endpoints, PUT programs/:programId/collection-anchor, deposit instructions, bank-integrations/inbound-credits, topups/:id/refund, qr/:id/revoke, qr/parse, wallets/lookup, or the bulk-payout submit, approve, reject, process and retry-failed calls.

Working example

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
const BASE = 'https://api-gateway.lunixi.com';
const path = '/api/v1/wallet/transfers/w2w';
 
const body = JSON.stringify({
  endUserId: '8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34',
  sourceWalletAccountId: 'c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47',
  destinationPhone: '+905321234567',
  amount: '10050',            // minor-unit string — ₺100.50
  currency: 'TRY',
  paymentPurpose: 'P2P',
});
 
const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
const date = new Date().toISOString();
const nonce = randomUUID();
 
const canonical = ['POST', path, `X-Date:${date}`, `X-Nonce:${nonce}`, `Digest:${digest}`].join('\n');
 
const signature = sign(
  null,                        // Ed25519 — no separate digest algorithm
  Buffer.from(canonical),
  createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM),
).toString('base64');
 
const res = await fetch(BASE + path, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Key-Id': process.env.LUNIXI_KEY_ID,
    'X-Date': date,
    'X-Nonce': nonce,
    'Digest': digest,
    'X-Signature': signature,
    'Idempotency-Key': 'p2p-9988-attempt-1',
  },
  body,
});

Verify connectivity first

When setting up signing, start with an endpoint that has no body and needs no idempotency:

GET /api/v1/wallet/ping

ping requires a set-up permission (wallet:program:manage or wallet:enduser:manage) on the key; a read-only key receives 403 WALLET_INSUFFICIENT_SCOPE. A 200 means your key, clock and canonical string are correct. Do not attempt money-movement endpoints before ping works — they are far harder to debug.

Response format

Successful responses arrive in the gateway envelope; the fields documented on each page are under data:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "operationId": "7a3e9c1d-2b4f-4e8a-9d6c-0f5b8e2a1c93",
    "status": "CHALLENGED"
  },
  "requestId": "…"
}

• Lists return data.items and data.nextCursor; send nextCursor back as cursor to fetch the next page. The operation list returns its records under data.operations.
• Errors return the HTTP status and a body carrying code (for example WALLET_NOT_FOUND) and message.
• Every id is a UUID. Amounts are minor-unit digit strings of up to 18 digits: "12550" means ₺125.50.

Error codes

Portal / SDK — publishable key + customer session

The end user's app never carries a signing key — if it did, anyone who installed the app could reach every wallet in your tenant.

Details: Portal — Identity & Session.

Merchant panel

Panel endpoints (/api/panel/v1/wallet/*) use your panel session, and each endpoint is bound to an RBAC permission code (wallet:program:manage, wallet:operation:intervene, wallet:bulk:approve, …). Money-critical actions additionally enforce four eyes.

Details: Panel — Overview & Permissions.

Terminal activation — the only endpoint with no identity guard

POST /api/v1/wallet/terminals/activate is the only wallet endpoint without an identity guard: it asks for no signature, no panel session and no customer session.

This is not an omission but the solution to a chicken-and-egg problem: a device that has not been activated yet has no identity — and no key to sign with, because this endpoint is what grants it one.

The proof of authority is the one-time activation code the device presents:

Creating the terminal itself, issuing an activation code, rotating or revoking its credential are all on the panel surface (wallet:terminal:manage) — see Panel — QR & Terminals.

Key management

• Rotation — rotating in the panel issues a new key and revokes the old one. For a zero-downtime switch, deploy the new key first, move traffic, then revoke the old one.
• Revocation — revoke immediately on suspicion of leakage; requests with a revoked kid get INVALID_KID.
• The private key must never reach logs, repositories, mobile apps or browsers. The platform does not store it either.