Authentication

The Payment Orchestrator API uses different authentication models depending on who is calling (your server, the buyer's browser, your public website) and how sensitive the operation is. This page walks through each model with working examples, then maps every endpoint group to the model it requires.

Base URL for all examples: https://api-gateway.lunixi.com/api/v1.

Bearer access token

Server-to-server calls are authenticated by a short-lived access token. You do not store it as a static key — you sign with your registered Ed25519 key and mint it from POST /api/v1/auth/token.

Ed25519 private key  ──sign──▶  POST /api/v1/auth/token  ──▶  at_live_…  (~5 min)

Send the token you get back in the Authorization header:

curl "https://api-gateway.lunixi.com/api/v1/payments?limit=20" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Step-Up: signed requests for money movement

Every endpoint that moves money — creating payment intents, direct charges, capture, void, refund — requires Step-Up auth: a valid Bearer token and an Ed25519 signature over the request. Even if your token is stolen, an attacker cannot move money without your private signing key.

A Step-Up request carries these headers:

The string you sign is built from the method, the full request path and the headers, joined with \n:

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

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
const body = JSON.stringify({
  amount: 10050,               // minor units — ₺100.50
  currency: 'TRY',
  orderId: 'ORD-9988',
});
 
const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
const date = new Date().toISOString();
const nonce = randomUUID();
 
const canonical = [
  'POST',
  '/api/v1/payments/intents',
  `X-Date:${date}`,
  `X-Nonce:${nonce}`,
  `Digest:${digest}`,
].join('\n');
 
const signature = sign(
  null, // Ed25519 — no digest algorithm
  Buffer.from(canonical),
  createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM),
).toString('base64');
 
const res = await fetch('https://api-gateway.lunixi.com/api/v1/payments/intents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LUNIXI_SECRET_KEY}`,
    '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': randomUUID(),
  },
  body,
});

Checkout form token & session-proof cookie (buyer side)

The hosted checkout form authenticates the buyer's browser without ever exposing your keys:

1. Your server creates an intent with Step-Up auth. The response contains a short-lived form token (expires in ~15 minutes) bound to your allowedOrigin.
2. The form calls POST /payments/form/live-analyze with that token; the response sets a session-proof cookie that binds the browser session.
3. Every /payments/form/* call carries the token; the card-touching calls (/form/tokenize, /form/2d, /form/3d) additionally require the session-proof cookie.

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/form/live-analyze" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ "token": "<form-token-from-intent>" }'

Publishable key + Origin allow-list

The publishable key (mk_live_pk_…) is safe to embed in your public website. It only unlocks read-only public catalog endpoints, and requests are additionally checked against your registered Origin allow-list — a stolen key is useless from another domain.

curl "https://api-gateway.lunixi.com/api/public/v1/subscription/plans" \
  -H "Authorization: Bearer mk_live_pk_xxxxxxxxxxxx" \
  -H "Origin: https://shop.example.com"

Used by /api/public/v1/subscription/plans|products|branding — for embedding pricing on your site. See Pricing & Portal SDK.

Idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) on every payment POST. If the same key is replayed — a network timeout, a double-clicked button, a retrying job — the API returns the original result instead of charging twice. Deduplication is backed by Redis with a database-uniqueness fallback.

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/pay_01JZ8K4W9X2R/refund" \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Idempotency-Key: refund-ORD-9988-1" \
  ... # Step-Up signature headers
  -d '{ "amount": 5000 }'

Which endpoints need which model

Errors

Next steps

• Quickstart — put the Step-Up flow to work and take your first payment
• Checkout Form — the full intent-create reference
• Webhooks — verify signed event deliveries