{ "openapi": "3.1.0", "info": { "title": "LanaPay API", "version": "1.0.0", "summary": "Hosted LanaCoin (LANA) checkout for online shops.", "description": "LanaPay lets an online shop accept LANA. You create a **checkout session** priced in fiat;\nthe shopper is sent to a hosted page on pay.lanapays.us, scans or pastes their wallet key,\nand the payment is signed **inside the shopper's own browser** — the key never reaches LanaPay\nor the shop. You are told the payment landed by an HMAC-signed webhook, or by polling the session.\n\n## Merchant reward — LanaPay deducts nothing\nYou receive the full invoice your shopper paid, **plus a reward on top of it**: 2% as standard,\n5% for merchants enrolled in Lana8Wonder, and up to 20% for merchants in the Abundance model.\nThe reward is funded by the investor financing the purchase — never by you and never by the shopper,\nwho pays exactly the invoice total. Nothing is paid out on failed or expired sessions.\n\n## Fulfilment rule\nA shopper returning to your return_url proves nothing — anyone can open that URL. Fulfil only after\nyour server has confirmed `status: \"paid\"` **and** that `amount` and `currency` match the order,\neither from a verified webhook or from `GET /api/v1/sessions/{id}`.\n\nFull prose documentation: https://pay.lanapays.us/llms-full.txt", "contact": { "name": "LanaPay", "url": "https://pay.lanapays.us/docs" } }, "servers": [ { "url": "https://pay.lanapays.us", "description": "Production" } ], "tags": [ { "name": "Checkout sessions", "description": "Create and inspect checkout sessions." }, { "name": "Payment links", "description": "Reusable no-code links; each payment mints its own session and order_id." }, { "name": "Public", "description": "Unauthenticated discovery data. Open CORS." } ], "security": [ { "SecretKey": [] }, { "PlatformKey": [] } ], "paths": { "/api/v1/sessions": { "post": { "tags": [ "Checkout sessions" ], "operationId": "createCheckoutSession", "summary": "Create a checkout session", "description": "`order_id` is the idempotency key. Re-posting the same order_id with an identical amount and currency returns the existing session with **200** instead of creating a second one; a different amount is a 409 conflict. An expired or cancelled session frees its order_id for a retry.\n\nWith a platform key (`pk_platform_…`) the body must also carry `unit_id` — the enrolled unit the session is for. A merchant key is bound to its own unit and ignores `unit_id`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "order_id", "return_url" ], "properties": { "amount": { "type": "string", "pattern": "^\\d{1,6}(\\.\\d{1,2})?$", "example": "19.90", "description": "Fiat amount as a decimal string with at most 2 decimals." }, "currency": { "type": "string", "enum": [ "EUR", "GBP", "USD" ], "description": "Must match the currency your merchant account is bound to." }, "order_id": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$", "example": "ORDER-1042" }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Platform keys only, and then required: the enrolled business unit to create the session for. Ignored for merchant sk_live_ keys, which are bound to one unit." }, "return_url": { "type": "string", "format": "uri", "description": "Where the shopper lands after paying. Receives ?lanapay_session_id=…&lanapay_order_id=…, or substitutes a {SESSION_ID} placeholder if present." }, "cancel_url": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 500 }, "expires_in": { "type": "integer", "minimum": 300, "maximum": 86400, "description": "Seconds. Defaults to your merchant expiry setting (60 minutes unless changed)." }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Up to 10 keys, echoed back on reads and webhooks. Never sent onward to the payment processor." } } } } } }, "responses": { "200": { "description": "Idempotent replay — the existing session for this order_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "201": { "description": "Session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "INVALID_AMOUNT · INVALID_CURRENCY · INVALID_ORDER_ID · INVALID_RETURN_URL · INVALID_CANCEL_URL · INVALID_METADATA · INVALID_EXPIRES_IN · INVALID_UNIT_ID (platform key: unit_id missing or not 32 lowercase hex)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MERCHANT_PENDING · MERCHANT_SUSPENDED · MERCHANT_REJECTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND — the key's merchant account is not active · MERCHANT_NOT_ENROLLED — platform key: the named unit has no active LanaPay merchant account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ORDER_ID_CONFLICT — same order_id, different amount · ORDER_ALREADY_PAID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "TOO_MANY_OPEN_SESSIONS, or the per-key rate limit (120/min; 600/min for the platform key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Checkout sessions" ], "operationId": "listCheckoutSessions", "summary": "List checkout sessions", "parameters": [ { "name": "unit_id", "in": "query", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" }, "description": "Required for a platform key — whose sessions to list; the platform never lists everything. Ignored for merchant keys." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "cancelled", "expired" ] } }, { "name": "order_id", "in": "query", "schema": { "type": "string" }, "description": "Exact match." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Cursor: the id of the last session from the previous page." } ], "responses": { "200": { "description": "Newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } }, "has_more": { "type": "boolean" } } } } } }, "400": { "description": "UNIT_ID_REQUIRED · INVALID_UNIT_ID (platform key only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}": { "get": { "tags": [ "Checkout sessions" ], "operationId": "getCheckoutSession", "summary": "Retrieve a checkout session", "description": "The authoritative way to confirm a payment before fulfilling. Applies lazy expiry on read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND — unknown id, or it belongs to another merchant (deliberately indistinguishable). A platform key may retrieve any unit's session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/expire": { "post": { "tags": [ "Checkout sessions" ], "operationId": "expireCheckoutSession", "summary": "Close an unpaid session", "description": "Closes a pending session with status `cancelled` and emits `session.cancelled`. Frees the order_id.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The closed session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND — unknown id, or another merchant's session. A platform key may close any unit's session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "NOT_EXPIRABLE — already paid, cancelled or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment_links": { "post": { "tags": [ "Payment links" ], "operationId": "createPaymentLink", "summary": "Create a payment link", "security": [ { "SecretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "fixed", "open" ] }, "amount": { "type": "string", "pattern": "^\\d{1,6}(\\.\\d{1,2})?$", "example": "19.90", "description": "Fiat amount as a decimal string with at most 2 decimals." }, "currency": { "type": "string", "enum": [ "EUR", "GBP", "USD" ] }, "description": { "type": "string", "maxLength": 200 }, "min_amount": { "type": "number" }, "max_amount": { "type": "number" }, "presets": { "type": "array", "items": { "type": "number" }, "maxItems": 4 }, "max_uses": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "INVALID_TYPE · INVALID_AMOUNT · INVALID_CURRENCY · INVALID_MAX_USES", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Payment links" ], "operationId": "listPaymentLinks", "summary": "List payment links", "security": [ { "SecretKey": [] } ], "responses": { "200": { "description": "Newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } }, "has_more": { "type": "boolean" } } } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment_links/{id}/deactivate": { "post": { "tags": [ "Payment links" ], "operationId": "deactivatePaymentLink", "summary": "Deactivate a payment link", "security": [ { "SecretKey": [] } ], "description": "Stops new payments. Sessions already minted from the link still complete or expire normally.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deactivated link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "401": { "description": "INVALID_API_KEY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "ALREADY_INACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/public/config": { "get": { "tags": [ "Public" ], "operationId": "getPublicConfig", "summary": "Currencies, live rates and reward tiers", "security": [], "description": "No authentication. Open CORS, safe to call from a browser.", "responses": { "200": { "description": "Current configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "type": "string" } }, "reward_percent_base": { "type": "number", "description": "Standard merchant reward, in percent of the invoice." }, "reward_percent_lana8wonder": { "type": "number", "description": "Reward for merchants enrolled in Lana8Wonder." }, "reward_percent_max": { "type": "number", "description": "Ceiling for the Abundance model." }, "fee_percent_base": { "type": "number", "deprecated": true, "description": "Deprecated alias of reward_percent_base. The percentage is a reward, not a fee." }, "fee_percent_lana8wonder": { "type": "number", "deprecated": true, "description": "Deprecated alias of reward_percent_lana8wonder." }, "exchange_rates": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Fiat per LANA, by currency." }, "rates_updated_at": { "type": "string", "nullable": true }, "brain_reachable": { "type": "boolean" } } } } } } } } } }, "webhooks": { "session.paid": { "post": { "summary": "A session was paid", "description": "Delivered to every enabled endpoint subscribed to the event.\n\nVerify the `LanaPay-Signature` header before trusting the body:\n`t=,v1=`.\nCompare with a constant-time comparison, accept **any** matching `v1=` entry, and reject a\ntimestamp more than 300 seconds from now. You must hash the **raw request bytes** — re-serialising\nthe parsed JSON changes them and the signature will never match.\n\nDelivery is at-least-once: dedupe on the event `id`. Any 2xx counts as delivered; otherwise the\ndelivery is retried after 1 m, 5 m, 30 m, 2 h, 6 h and 24 h, then marked dead.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Return any 2xx promptly. Do your slow work after responding." } } } }, "session.expired": { "post": { "summary": "A pending session passed its expires_at", "description": "No money moved. Safe to release any reserved stock.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "session.cancelled": { "post": { "summary": "A pending session was closed", "description": "Cancelled by the shopper, by you via the dashboard, or through POST /api/v1/sessions/{id}/expire.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "SecretKey": { "type": "http", "scheme": "bearer", "description": "Your secret API key, `Authorization: Bearer sk_live_…`. Server-side only — it must never appear in browser code. Create and revoke keys in the dashboard under API keys; the full value is shown once, at creation. Rate limit: 120 requests per minute per key (plus a global 1500 per 15 minutes per IP)." }, "PlatformKey": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer pk_platform_…` — the single platform-scoped key held only by shop.lanapays.us (the Lana Online Shop broker). The gateway never stores it; it is configured server-side as SHA-256 hashes (PLATFORM_API_KEY_HASHES). It may create, retrieve, list and close checkout sessions for ANY enrolled unit, naming the unit per request (`unit_id`); sessions it creates carry `api_key_id = platform`. Not valid on /api/v1/payment_links. Rate limit: 600 requests per minute (PLATFORM_RATE_PER_MIN)." } }, "schemas": { "CheckoutSession": { "type": "object", "description": "A checkout session. Denominated in FIAT only — the LANA amount is computed by the brain at payment time from the exchange rate then in force.", "properties": { "id": { "type": "string", "example": "cs_9f2kq7pxw4ln8vrt3a1b5c6d" }, "object": { "type": "string", "enum": [ "checkout_session" ] }, "url": { "type": "string", "format": "uri", "description": "Send the shopper here.", "example": "https://pay.lanapays.us/pay/pk3XualNQuBv7Ge9wS2ZdT4c8mYhJfRw" }, "status": { "type": "string", "enum": [ "pending", "paid", "expired", "cancelled" ], "description": "The internal 'paying' state is reported as 'pending'." }, "amount": { "type": "string", "pattern": "^\\d{1,6}(\\.\\d{1,2})?$", "example": "19.90", "description": "Fiat amount as a decimal string with at most 2 decimals." }, "currency": { "type": "string", "enum": [ "EUR", "GBP", "USD" ] }, "order_id": { "type": "string", "description": "Your order reference. Doubles as the payment-processor invoice number, which dedupes successful purchases per merchant." }, "description": { "type": "string", "nullable": true }, "created_via": { "type": "string", "enum": [ "api", "redirect", "link", "dashboard" ] }, "amount_source": { "type": "string", "enum": [ "api", "url_signed", "url_unsigned", "payment_link", "dashboard" ] }, "tamper_protected": { "type": "boolean", "description": "false only for unsigned GET /checkout links, where the amount travelled in a URL the shopper could edit. Always verify amount and currency server-side before fulfilling." }, "payment_link_id": { "type": "string", "nullable": true }, "return_url": { "type": "string", "nullable": true }, "cancel_url": { "type": "string", "nullable": true }, "payment": { "nullable": true, "type": "object", "description": "Present once status is paid. The payer wallet address is deliberately NOT included: a leaked secret key must not yield a list of every customer LANA address. Use tx_hash to identify the payment on-chain.", "properties": { "tx_id": { "type": "string", "nullable": true, "description": "Payment-processor transaction id." }, "tx_hash": { "type": "string", "nullable": true, "description": "LanaCoin on-chain transaction hash." }, "lana_lanoshis": { "type": "integer", "nullable": true, "description": "LANA actually paid, in lanoshis (1 LANA = 100 000 000 lanoshis)." }, "exchange_rate": { "type": "number", "nullable": true, "description": "Fiat per LANA at pay time." } } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "expires_at": { "type": "string", "nullable": true }, "paid_at": { "type": "string", "nullable": true }, "cancelled_at": { "type": "string", "nullable": true } }, "required": [ "id", "object", "url", "status", "amount", "currency", "order_id" ] }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "example": "pl_1f0c…" }, "object": { "type": "string", "enum": [ "payment_link" ] }, "code": { "type": "string", "description": "10-char code; the shareable URL is /l/{code}." }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string", "enum": [ "fixed", "open" ] }, "amount": { "type": "number", "nullable": true, "description": "Set for type=fixed." }, "currency": { "type": "string" }, "min_amount": { "type": "number", "nullable": true }, "max_amount": { "type": "number", "nullable": true }, "presets": { "type": "array", "nullable": true, "items": { "type": "number" }, "description": "Up to 4 suggested amounts, type=open only." }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "uses_count": { "type": "integer" }, "max_uses": { "type": "integer", "nullable": true }, "created_at": { "type": "string" }, "deactivated_at": { "type": "string", "nullable": true } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable code — branch on this, not on message." }, "message": { "type": "string" }, "param": { "type": "string", "description": "The offending request field, when the error is about one." }, "request_id": { "type": "string", "example": "req_a1b2c3d4e5f6a7b8", "description": "Quote this when asking for support." }, "session_id": { "type": "string", "description": "Set on ORDER_ID_CONFLICT / ORDER_ALREADY_PAID — the session already holding that order_id." } }, "required": [ "code", "message", "request_id" ] } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_2b91c4d8f7a35e60", "description": "Dedupe on this." }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string", "enum": [ "session.paid", "session.expired", "session.cancelled", "test.ping" ] }, "created_at": { "type": "string" }, "test": { "type": "boolean", "description": "Present and true only for a dashboard test delivery." }, "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/CheckoutSession" } } } } } } } }