Creating Links

POST /api/v1/payments/links creates a new payment link and returns the https://pay.lunixi.com/<CODE> address you share. This page covers authentication, every request field, the response and errors. You can also create links from the dashboard; this page is for API integrations from your server.

How it works

Authentication

Payment link endpoints (/api/v1/payments/links/*) accept only requests signed with your API key. Every request carries the headers below; no Authorization header is needed. A Bearer access token or a dashboard session does not stand in for the signature on these endpoints — a request without the signature headers receives 401 AUTH_HEADERS_MISSING.

The signed text is the following lines joined with \n (the Digest in the example belongs to the body of the sample request below):

POST
/api/v1/payments/links
X-Date:2026-09-25T09:00:00Z
X-Nonce:64ae70b60739b3515d972c0378854a59
Digest:SHA-256=MBzVeFBxTxZxT8gMQ+nBA+64x1CwAEeT+E7KM02BaEg=

The Node.js examples in this section use the signedHeaders helper below. Your private key stays on your server; never put it in a browser or a mobile app.

import { createHash, createPrivateKey, sign, randomUUID } from 'node:crypto';
 
export const BASE_URL = 'https://api-gateway.lunixi.com';
const signingKey = createPrivateKey(process.env.LUNIXI_SIGNING_KEY_PEM);
 
// pathWithQuery: the full path including the query string, e.g. '/api/v1/payments/links?limit=25'
// body: the exact JSON string you send; omit it for requests without a body
export function signedHeaders(method, pathWithQuery, body) {
  const date = new Date().toISOString();
  const nonce = randomUUID();
  const headers = { 'X-Key-Id': process.env.LUNIXI_KEY_ID, 'X-Date': date, 'X-Nonce': nonce };
  const lines = [method, pathWithQuery, `X-Date:${date}`, `X-Nonce:${nonce}`];
  if (body !== undefined) {
    const digest = 'SHA-256=' + createHash('sha256').update(body).digest('base64');
    headers['Content-Type'] = 'application/json';
    headers['Digest'] = digest;
    lines.push(`Digest:${digest}`);
  }
  headers['X-Signature'] = sign(null, Buffer.from(lines.join('\n')), signingKey).toString('base64');
  return headers;
}

The cURL examples compute the signature with OpenSSL 3.0 or later (openssl pkeyutl -rawin). Registering and rotating keys: Authentication.

Scopes

After the signature is verified, the key's scope is checked. A missing scope returns 403 API_INSUFFICIENT_SCOPE.

Environment

A link's environment (TEST or LIVE) is decided by your key's environment. You do not need to send environment in the body; if you do, it must match your key's environment, otherwise 403 payment_link.environment.mismatch is returned. A key only sees and changes links in its own environment.

Request

POST /api/v1/payments/links — signed request, scope payment-link:create.

Idempotency-Key

Required. 8–200 characters of printable ASCII without spaces (^[\x21-\x7E]{8,200}$). Use a value that identifies the link — e.g. plink-INV-2026-0042.

• Same key + same body → no new link is created; the link created with this key is returned with 200 and replayed: true. You can safely retry after a network timeout.
• Same key + different body → 409 payment_link.idempotency.conflict.
• Missing key → 400 payment_link.idempotency.key_required; malformed key → 400 payment_link.idempotency.key_invalid.

Fields

An undefined field or a wrong type returns 400 VALIDATION_ERROR. A business-rule violation (e.g. no amountMinor on a FIXED link) returns 422 payment_link.validation.invalid, and details.errors lists which field was rejected and why.

items[]

buyerFields

Each field takes one of HIDDEN | OPTIONAL | REQUIRED.

customFields[]

Answers are stored as strings: "true" / "false" for CHECKBOX, YYYY-MM-DD for DATE. There is no file-upload field.

recipient and prefill

• recipient — { name, email, phone } (name up to 120 and email up to 180 characters, phone in E.164). Fill it in when the link is for a specific person: POST /:id/send and reminders go to this address by default, and the access verification code is sent only to this email. The payment page shows it masked only.
• prefill — { name, surname, email, phone, identityNumber, address, city, country, zipCode } (country in ISO 3166-1 alpha-2). These details are not sent to the buyer's browser; they are written to the payment record's buyer details on the server. Values the buyer types only fill fields that are still empty. If you added access verification to the link, a buyer who passes it sees these details in the form — except identityNumber.

Both objects are stored encrypted and returned in the clear only in your own API responses.

checkout

Sample request

# Requires OpenSSL 3.0+. The body must be compact JSON.
KEY_ID="mk_test_sk_..."             # X-Key-Id
KEY_FILE="lunixi-signing.key"       # your Ed25519 private key (PEM)
REQ_PATH="/api/v1/payments/links"
BODY='{"usage":"SINGLE_USE","amountMode":"FIXED","currency":"TRY","amountMinor":150000,"title":"November consulting fee","expiresAt":"2026-10-31T20:59:59.000Z","reference":"INV-2026-0042","recipient":{"name":"Ayşe Yılmaz","email":"[email protected]"},"metadata":{"crmId":"A-77"}}'
 
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
NONCE=$(openssl rand -hex 16)
DIGEST="SHA-256=$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | base64)"
printf 'POST\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$REQ_PATH" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
SIGNATURE=$(openssl pkeyutl -sign -inkey "$KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: plink-INV-2026-0042" \
  --data-raw "$BODY"

Body examples for other link types:

// Donation — the buyer enters the amount, with suggested amount buttons
{ "usage": "MULTI_USE", "amountMode": "OPEN", "currency": "TRY",
  "minAmountMinor": 5000, "suggestedAmountsMinor": [10000, 25000, 50000],
  "title": "Winter campaign donation", "buttonLabelKey": "DONATE" }
 
// Ticket — fixed price, quantity selection, capacity of 200
{ "usage": "MULTI_USE", "amountMode": "FIXED", "currency": "TRY",
  "amountMinor": 45000, "quantityEnabled": true, "minQuantity": 1, "maxQuantity": 4,
  "capacity": 200, "title": "Workshop — 12 November", "eventAt": "2026-11-12T16:00:00.000Z" }
 
// Itemized — size selection, stock per item
{ "usage": "MULTI_USE", "amountMode": "ITEMIZED", "currency": "TRY",
  "title": "Team jersey",
  "items": [
    { "itemKey": "jersey_m", "name": "Jersey — M", "unitPriceMinor": 90000, "maxQuantity": 3, "capacity": 40 },
    { "itemKey": "jersey_l", "name": "Jersey — L", "unitPriceMinor": 90000, "maxQuantity": 3, "capacity": 40 }
  ] }

Response

201 Created — 200 OK with replayed: true on a replay.

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "id": "5f0c1d2e-8a4b-4c6d-9e7f-1a2b3c4d5e6f",
    "shortCode": "7KQ2M9XAPT",
    "url": "https://pay.lunixi.com/7KQ2M9XAPT",
    "organizationId": "b1d2c3e4-…",
    "environment": "TEST",
    "state": "ACTIVE",
    "version": 1,
    "rowVersion": 1,
    "createdBy": { "type": "API_KEY", "id": "mk_test_sk_…" },
    "createdAt": "2026-09-25T09:00:00.000Z",
    "updatedAt": "2026-09-25T09:00:00.000Z",
    "completedAt": null,
    "expiredAt": null,
    "deactivatedAt": null,
    "takedown": null,
    "verificationLocked": false,
    "hasActiveAttempt": false,
    "amountLocked": false,
    "counters": {
      "paidCount": 0, "collectedAmountMinor": 0, "refundedAmountMinor": 0,
      "soldQuantity": 0, "reservedQuantity": 0, "attemptCount": 0
    },
    "availability": { "soldOut": false, "remainingQuantity": null, "inProgress": false, "items": [] },
    "usage": "SINGLE_USE",
    "amountMode": "FIXED",
    "currency": "TRY",
    "amountMinor": 150000,
    "title": "November consulting fee",
    "expiresAt": "2026-10-31T20:59:59.000Z",
    "reference": "INV-2026-0042",
    "recipient": { "name": "Ayşe Yılmaz", "email": "[email protected]", "phone": "" },
    "metadata": { "crmId": "A-77" },
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "req_7f3d9c1a4b2e"
}

The response contains every field you sent, flat, together with their defaults (shortened in the sample). Unset timestamps and optional ids are returned as null. The link's own fields:

Errors

The error envelope and the rule to branch on code: Error Handling.

4xx errors do not resolve by retrying the same request; fix the request first. On 5xx responses (e.g. 503, 504), retry with exponential backoff using the same Idempotency-Key and the same body: if the first attempt created the link, no second link is created and the recorded link is returned with replayed: true.

Webhooks

payment.link.created is published when a link is created. All payment and link events: Webhooks.

Next steps

• Managing Links — listing, updating, pausing, sending, QR
• Payment Page — the page the buyer sees, branding and access verification
• Webhooks — fulfilling orders on payment.captured