{ "openapi": "3.0.3", "info": { "title": "SatsRail API", "version": "1.0.0", "description": "Non-custodial Bitcoin Lightning payment infrastructure API." }, "servers": [ { "url": "https://app.satsrail.com" } ], "paths": { "/api/v1/m/catalog": { "get": { "summary": "show", "tags": [ "Api::V1::M::Catalog" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer pk_live_YOUR_PUBLISHABLE_KEY" } ], "responses": { "200": { "description": "allows access with publishable key", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "merchant_id": { "type": "string" }, "catalog_version": { "type": "string" }, "catalog_refresh_minutes": { "type": "integer" }, "product_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "price_cents": { "type": "integer", "nullable": true }, "currency": { "type": "string", "nullable": true }, "sku": { "nullable": true }, "formatted_price": { "type": "string", "nullable": true }, "image_url": { "nullable": true }, "image_medium_url": { "nullable": true }, "position": { "type": "integer", "nullable": true } } } }, "tax_ids": { "type": "array", "items": {} } }, "required": [ "id", "name", "position", "products", "tax_ids" ] } }, "taxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rate": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "id", "name", "rate", "enabled" ] } }, "discounts": { "type": "array", "items": {} }, "livemode": { "type": "boolean" } }, "required": [ "object", "merchant_id", "catalog_version", "catalog_refresh_minutes", "product_types", "taxes", "discounts", "livemode" ] }, "example": { "object": "catalog", "merchant_id": "2657842b-5006-4e6e-8488-3158e7c4806e", "catalog_version": "2026-03-14T03:11:55Z", "catalog_refresh_minutes": 30, "product_types": [ { "id": "49708280-8d66-4cd6-9378-8e256e337160", "name": "Default", "position": 0, "products": [], "tax_ids": [] } ], "taxes": [], "discounts": [], "livemode": true } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "16801347-037f-4ccb-ae22-78100ecde612" } } } } } } } }, "/api/v1/m/invoices/generate": { "post": { "summary": "generate", "tags": [ "Api::V1::M::Invoice" ], "responses": { "201": { "description": "returns the existing invoice", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "nullable": true }, "order_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "expired": { "type": "boolean" }, "time_until_expiry": { "type": "integer" }, "metadata": { "type": "object", "properties": { "provider": { "type": "string" }, "mode": { "type": "string" } } }, "order": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string" }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_price_at_creation", "btc_usd_rate_source", "currency", "btc_fiat_price_at_creation", "metadata" ] } }, "required": [ "object", "livemode", "id", "payment_method", "amount_sats", "status", "expires_at", "paid_at", "order_id", "created_at", "updated_at", "payment_request", "payment_hash", "expired", "time_until_expiry", "metadata", "order" ] }, "example": { "object": "invoice", "livemode": true, "id": "3117b19c-4fff-4eaf-b0e4-b7406fce5d85", "payment_method": "lightning", "amount_sats": 10000, "status": "pending", "expires_at": "2026-03-14T04:11:55.467Z", "paid_at": null, "order_id": "cf1e996d-c303-46ea-b95e-6a7315689e70", "created_at": "2026-03-14T03:11:55.467Z", "updated_at": "2026-03-14T03:11:55.467Z", "payment_request": "lnbc10n1pj9q...", "payment_hash": "2eee05aec53912f0a2836d0ff78a2d934c43a2cdd02825d9e8c6fad2be86c81f", "expired": false, "time_until_expiry": 3599, "metadata": { "provider": "lnurl_demo", "mode": "mock" }, "order": { "object": "order", "livemode": true, "id": "cf1e996d-c303-46ea-b95e-6a7315689e70", "order_number": "ORD-1773457915-4", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "pending", "merchant_id": "ef16bf22-8597-49af-b4df-a00ada990124", "channel_id": null, "wallet_id": "c85c322b-878c-4e67-a264-2abf023d335f", "discount_id": null, "created_at": "2026-03-14T03:11:55.464Z", "updated_at": "2026-03-14T03:11:55.464Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457915-4", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "31be5d65-8763-4dc1-a5ff-725dae4a8720" } } } } }, "404": { "description": "returns not found error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Order not found", "status": 404, "request_id": "9bd0e4e0-7c4b-46ea-9ca6-57186ced1a2b" } } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": [ "order_id" ] }, "example": { "order_id": "cf1e996d-c303-46ea-b95e-6a7315689e70" } } } } } }, "/api/v1/m/invoices/{id}": { "get": { "summary": "show", "tags": [ "Api::V1::M::Invoice" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "857d59e6-fe7d-4929-a3d5-3b5d0e92e8d7" } ], "responses": { "200": { "description": "includes order with correct JSON structure", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "nullable": true }, "order_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "expired": { "type": "boolean" }, "time_until_expiry": { "type": "integer" }, "metadata": { "type": "object", "properties": {} }, "order": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string" }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_price_at_creation", "btc_usd_rate_source", "currency", "btc_fiat_price_at_creation", "metadata" ] } }, "required": [ "object", "livemode", "id", "payment_method", "amount_sats", "status", "expires_at", "paid_at", "order_id", "created_at", "updated_at", "payment_request", "payment_hash", "expired", "time_until_expiry", "metadata", "order" ] }, "example": { "object": "invoice", "livemode": true, "id": "371bb5ac-a9a3-4251-83e7-5c5e1b9584ee", "payment_method": "lightning", "amount_sats": 10000, "status": "pending", "expires_at": "2026-03-14T04:11:55.505Z", "paid_at": null, "order_id": "70f52843-3b70-42d8-9953-111f0e840773", "created_at": "2026-03-14T03:11:55.505Z", "updated_at": "2026-03-14T03:11:55.505Z", "payment_request": "lnbc30n1pj9q...", "payment_hash": "b0df78ea711a2db64e6eb6c552ffe00b58800e8d8406bc791e7f0afcfcacee73", "expired": false, "time_until_expiry": 3599, "metadata": {}, "order": { "object": "order", "livemode": true, "id": "70f52843-3b70-42d8-9953-111f0e840773", "order_number": "ORD-1773457915-6", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "pending", "merchant_id": "39b83ee2-3906-45c3-b7c9-d055bea10e44", "channel_id": null, "wallet_id": "c1832e80-72b1-4ae3-a49e-22e1bfffbaef", "discount_id": null, "created_at": "2026-03-14T03:11:55.502Z", "updated_at": "2026-03-14T03:11:55.502Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457915-6", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "16f5e6e8-6268-4bf4-ba10-bb6f5876909c" } } } } }, "404": { "description": "prevents access to other merchant's invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Invoice not found", "status": 404, "request_id": "fcae44b3-74ea-4021-83e8-99edb682fb00" } } } } } } } }, "/api/v1/m/invoices/{id}/qr": { "get": { "summary": "qr", "tags": [ "Api::V1::M::Invoice" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "9f024127-e229-49a6-998c-057f832241a6" } ], "responses": { "200": { "description": "generates QR code with payment_request", "content": { "image/svg+xml": { "schema": { "type": "string" }, "example": "" } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "43a12220-f3f1-4360-8d7d-c8c85f0af5ca" } } } } }, "404": { "description": "prevents access to other merchant's invoice QR", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Invoice not found", "status": 404, "request_id": "401ca537-0f23-4abe-aba1-538279b16b2a" } } } } } } } }, "/api/v1/m/invoices/{id}/status": { "get": { "summary": "status", "tags": [ "Api::V1::M::Invoice" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "4b37eb1a-c52a-49e2-a327-c9d355c8d4c4" } ], "responses": { "200": { "description": "returns expired status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "paid": { "type": "boolean" }, "expired": { "type": "boolean" }, "paid_at": { "nullable": true }, "expires_at": { "type": "string" }, "payment_method": { "type": "string" }, "payment": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "amount_sats": { "type": "integer" }, "preimage": { "type": "string" }, "confirmed_at": { "type": "string" }, "order_id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "channel_id": { "nullable": true }, "payment_hash": { "type": "string" }, "settled_at": { "type": "string" }, "btc_usd_price_at_payment": { "type": "string" }, "usd_value_at_payment": { "type": "string" }, "usd_variance_cents": { "type": "integer" }, "variance_percentage": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_payment": { "type": "string" }, "fiat_value_at_payment": { "type": "string" }, "fiat_variance_cents": { "type": "integer" }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "metadata": { "type": "object", "properties": {} }, "order": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string" }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_price_at_creation", "btc_usd_rate_source", "currency", "btc_fiat_price_at_creation", "metadata" ] } }, "required": [ "object", "livemode", "id", "amount_sats", "preimage", "confirmed_at", "order_id", "invoice_id", "created_at", "updated_at", "channel_id", "payment_hash", "settled_at", "btc_usd_price_at_payment", "usd_value_at_payment", "usd_variance_cents", "variance_percentage", "currency", "btc_fiat_price_at_payment", "fiat_value_at_payment", "fiat_variance_cents", "confirmations", "required_confirmations", "metadata", "order" ] } }, "required": [ "status", "paid", "expired", "paid_at", "expires_at", "payment_method" ] }, "example": { "status": "expired", "paid": false, "expired": true, "paid_at": null, "expires_at": "2026-03-14T02:11:55.758Z", "payment_method": "lightning", "payment": { "object": "payment", "livemode": true, "id": "fd1eba72-cc81-4267-8173-e129c6ced838", "amount_sats": 10000, "preimage": "preimage_0788fb6dc7e7b0554af6f0c90fc12b79_1", "confirmed_at": "2026-03-14T03:11:55.735Z", "order_id": "9f2a1e84-7748-41ac-aec9-44e74d44d928", "invoice_id": "7f0aecaf-d021-479f-a568-ff3a43ce40a0", "created_at": "2026-03-14T03:11:55.735Z", "updated_at": "2026-03-14T03:11:55.735Z", "channel_id": null, "payment_hash": "e838979f44ef5bc6e69005352881862ee56c0f4849a07062b91e5b46d93b47c1", "settled_at": "2026-03-14T03:11:55.735Z", "btc_usd_price_at_payment": "100000.0", "usd_value_at_payment": "10.0", "usd_variance_cents": -9000, "variance_percentage": "-90.0", "currency": "usd", "btc_fiat_price_at_payment": "100000.0", "fiat_value_at_payment": "10.0", "fiat_variance_cents": -9000, "confirmations": 0, "required_confirmations": 1, "metadata": {}, "order": { "object": "order", "livemode": true, "id": "9f2a1e84-7748-41ac-aec9-44e74d44d928", "order_number": "ORD-1773457915-18", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "paid", "merchant_id": "cd2a76bd-53f5-4461-8129-660f18f955dc", "channel_id": null, "wallet_id": "2d425f9c-7817-4818-ab9a-26547c2b1405", "discount_id": null, "created_at": "2026-03-14T03:11:55.728Z", "updated_at": "2026-03-14T03:11:55.738Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457915-18", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} } } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "28764cae-fa78-4794-a6b1-f039139cb36e" } } } } }, "404": { "description": "prevents checking status of other merchant's invoice", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Invoice not found", "status": 404, "request_id": "12544ba8-6e5c-4d45-b169-edd02844bd94" } } } } } } } }, "/api/v1/m/merchant": { "get": { "summary": "show", "tags": [ "Api::V1::M::Merchant" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "responses": { "200": { "description": "allows API access", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "business_license": { "type": "string" }, "status": { "type": "string" }, "time_zone": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tip_options": { "type": "array", "items": {} }, "logo_url": { "nullable": true }, "pos_theme": { "type": "string" }, "pos_enabled": { "type": "boolean" }, "privapaid_enabled": { "type": "boolean" }, "channels": { "type": "array", "items": {} }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operational": { "type": "boolean" }, "lightning": { "type": "object", "properties": { "lightning_address": { "type": "string" } }, "required": [ "lightning_address" ] } }, "required": [ "object", "id", "name", "status", "enabled", "position", "created_at", "updated_at", "operational", "lightning" ] } }, "taxes": { "type": "array", "items": {} }, "livemode": { "type": "boolean" } }, "required": [ "object", "id", "name", "email", "phone", "business_license", "status", "time_zone", "currency", "created_at", "updated_at", "tip_options", "logo_url", "pos_theme", "pos_enabled", "privapaid_enabled", "channels", "wallets", "taxes", "livemode" ] }, "example": { "object": "merchant", "id": "030f701e-19ec-429d-93b0-ce36a444c5da", "name": "Merchant 64", "email": "merchant64@example.com", "phone": "(555) 555-0100", "business_license": "LICENSE-001", "status": "active", "time_zone": "UTC", "currency": "usd", "created_at": "2026-03-14T03:11:56.312Z", "updated_at": "2026-03-14T03:11:56.312Z", "tip_options": [], "logo_url": null, "pos_theme": "dark", "pos_enabled": true, "privapaid_enabled": false, "channels": [], "wallets": [ { "object": "wallet", "id": "d91382af-e191-4117-9c57-7e8a657800a6", "name": "Wallet 65", "status": "active", "enabled": true, "position": 67, "created_at": "2026-03-14T03:11:56.316Z", "updated_at": "2026-03-14T03:11:56.316Z", "operational": true, "lightning": { "lightning_address": "testmerchant70@phoenix.acinq.co" } } ], "taxes": [], "livemode": true } } } }, "401": { "description": "returns 401 for GET /api/v1/merchant (token revoked on terminate)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "invalid_token", "message": "Invalid or revoked API token", "status": 401, "request_id": "74482dbb-5430-4da1-9514-d3230edbc094" } } } } }, "403": { "description": "returns 403 forbidden for GET /api/v1/merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "merchant_not_operational", "message": "Merchant account is not yet active. Configure a wallet to activate your account.", "status": 403, "request_id": "ebc6411b-bf3c-4b03-bfeb-30dc95beabd8" } } } } } } } }, "/api/v1/m/orders": { "get": { "summary": "index", "tags": [ "Api::V1::M::Order" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_YOUR_SECRET_KEY" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 10 }, { "name": "q[created_at_gteq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-03-07T03:11:56Z" }, { "name": "q[created_at_lteq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-03-14T03:11:56Z" }, { "name": "q[merchant_id_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "724f689e-1e73-4462-947a-d8ff6e05b89b" }, { "name": "q[payments_payment_type_eq]", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "q[status_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "paid" } ], "responses": { "200": { "description": "test token only sees test orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer", "nullable": true }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string", "nullable": true }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "nullable": true, "description": "The customer's email address, where the receipt goes" }, "metadata": { "type": "object", "properties": {} }, "cash_paid_at": { "type": "string" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true, "description": "API token that created this order" } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_rate_source", "currency", "metadata" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "nullable": true, "type": "integer" }, "prev_page": { "nullable": true } }, "required": [ "current_page", "per_page", "total_count", "total_pages", "next_page", "prev_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "object": "order", "livemode": false, "id": "5ae83d27-4639-416f-b06f-8550a9c9aa90", "order_number": "ORD-1773457918-114", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "pending", "merchant_id": "8e2a625e-d5c0-4654-b655-38ce54cb1f01", "channel_id": null, "wallet_id": "8c854cc8-d7d0-49eb-9c09-593bf3452d3f", "discount_id": null, "created_at": "2026-03-14T03:11:58.346Z", "updated_at": "2026-03-14T03:11:58.346Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457918-114", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} } ], "meta": { "current_page": 1, "per_page": 25, "total_count": 1, "total_pages": 1, "next_page": null, "prev_page": null } } } } }, "401": { "description": "rejects requests without Bearer prefix", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "bbb50aee-18dc-4d76-9b45-282006ba0d02" } } } } }, "403": { "description": "returns 403 forbidden for GET /api/v1/orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "merchant_not_operational", "message": "Merchant account is not yet active. Configure a wallet to activate your account.", "status": 403, "request_id": "f1365a51-322e-4cc0-a755-7170c0b39ee1" } } } } } } }, "post": { "summary": "create", "tags": [ "Api::V1::M::Order" ], "responses": { "201": { "description": "creates orders with correct livemode flag from test token", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer", "nullable": true }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string", "nullable": true }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "nullable": true, "description": "The customer's email address, where the receipt goes" }, "metadata": { "type": "object", "properties": {} }, "invoice": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "nullable": true }, "order_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "expired": { "type": "boolean" }, "time_until_expiry": { "type": "integer" }, "metadata": { "type": "object", "properties": { "mode": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "mode", "provider" ] } }, "required": [ "object", "livemode", "id", "payment_method", "amount_sats", "status", "expires_at", "paid_at", "order_id", "created_at", "updated_at", "payment_request", "payment_hash", "expired", "time_until_expiry", "metadata" ] }, "cash_paid_at": { "nullable": true, "type": "string" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true, "description": "API token that created this order" } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_rate_source", "currency", "metadata" ] }, "example": { "object": "order", "livemode": false, "id": "e6e9ba68-bde9-4938-8585-6d3df8aa5c08", "order_number": "ORD-6AE0989B55CA9F17", "total_amount_cents": 5000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 50000, "status": "pending", "merchant_id": "1ba083e9-2701-43d5-b375-cceb65ecb130", "channel_id": null, "wallet_id": "42ae58e1-896a-4476-b286-a44ad10f8986", "discount_id": null, "created_at": "2026-03-14T03:11:58.382Z", "updated_at": "2026-03-14T03:11:58.382Z", "tender_type": "bitcoin", "items": [ { "name": "Widget", "price_cents": 5000, "qty": 1 } ], "po_number": "ORD-6AE0989B55CA9F17", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {}, "invoice": { "object": "invoice", "livemode": true, "id": "fff4313b-f93e-4321-baa2-6fcfa17fbb18", "payment_method": "lightning", "amount_sats": 10000, "status": "pending", "expires_at": "2026-03-14T03:26:56.679Z", "paid_at": null, "order_id": "a2158e12-b22d-42b7-8217-ee90f3b4ff01", "created_at": "2026-03-14T03:11:56.679Z", "updated_at": "2026-03-14T03:11:56.679Z", "payment_request": "lnbc10000u1ped5914a06083b199c797e26f359383d28c9679ba5ad59f2b73cb85a69691eee4", "payment_hash": "f911c798e78ad250c5b093e3f0838245d6bf0a4004371cd6c44a68caf63c4c18", "expired": false, "time_until_expiry": 899, "metadata": { "mode": "mock", "provider": "lnurl_demo" } }, "cash_paid_at": "2026-03-14T03:11:57.031Z" } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "adb67c43-0cda-4e2b-a666-bb538df2f746" } } } } }, "422": { "description": "returns validation errors with correct structure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "details", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "status": 422, "details": [ "Total amount cents must be greater than 0" ], "request_id": "c05a415f-bcb6-4670-a408-a2477d740f4f" } } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "total_amount_cents": { "type": "integer" }, "customer_email": { "type": "string", "format": "email", "description": "The customer's email address. The receipt is sent to it once the order is paid, if the merchant sends receipts." }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "tender_type": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "total_amount_cents", "items" ] }, "generate_invoice": { "type": "boolean" }, "mark_as_paid": { "type": "boolean" } }, "required": [ "order" ] }, "example": { "order": { "total_amount_cents": 5000, "items": [ { "name": "Widget", "price_cents": 5000, "qty": 1 } ], "tender_type": "cash", "currency": "usd" }, "generate_invoice": true, "mark_as_paid": true } } } } } }, "/api/v1/m/orders/{id}": { "delete": { "summary": "destroy", "tags": [ "Api::V1::M::Order" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "68caf49a-1084-445f-9d68-4621a8ea8c3d" } ], "responses": { "204": { "description": "returns no content status" }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "d7775407-fc4d-4761-9c91-341ddf12bf2a" } } } } }, "404": { "description": "prevents cancelling other merchant's orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Order not found", "status": 404, "request_id": "86af090f-2cd0-4e1f-ae92-8c35f5caa766" } } } } } } }, "get": { "summary": "show", "tags": [ "Api::V1::M::Order" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bcb3cddc-2fc3-456a-8e93-ae9dceb3d50b" } ], "responses": { "200": { "description": "includes livemode field in order responses", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer", "nullable": true }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string", "nullable": true }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "nullable": true, "description": "The customer's email address, where the receipt goes" }, "metadata": { "type": "object", "properties": {} }, "merchant": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "business_license": { "type": "string" }, "status": { "type": "string" }, "time_zone": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tip_options": { "type": "array", "items": {} }, "logo_url": { "nullable": true }, "pos_theme": { "type": "string" }, "pos_enabled": { "type": "boolean" }, "privapaid_enabled": { "type": "boolean" }, "channels": { "type": "array", "items": {} }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operational": { "type": "boolean" }, "lightning": { "type": "object", "properties": { "lightning_address": { "type": "string" } }, "required": [ "lightning_address" ] } }, "required": [ "object", "id", "name", "status", "enabled", "position", "created_at", "updated_at", "operational", "lightning" ] } }, "taxes": { "type": "array", "items": {} } }, "required": [ "object", "id", "name", "email", "phone", "business_license", "status", "time_zone", "currency", "created_at", "updated_at", "tip_options", "logo_url", "pos_theme", "pos_enabled", "privapaid_enabled", "channels", "wallets", "taxes" ] }, "cash_paid_at": { "type": "string" }, "payment": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "amount_sats": { "nullable": true }, "preimage": { "nullable": true }, "confirmed_at": { "type": "string" }, "order_id": { "type": "string" }, "invoice_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "channel_id": { "nullable": true }, "payment_hash": { "nullable": true }, "settled_at": { "type": "string" }, "usd_value_at_payment": { "type": "string" }, "currency": { "type": "string" }, "fiat_value_at_payment": { "type": "string" }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "amount_sats", "preimage", "confirmed_at", "order_id", "invoice_id", "created_at", "updated_at", "channel_id", "payment_hash", "settled_at", "usd_value_at_payment", "currency", "fiat_value_at_payment", "confirmations", "required_confirmations", "metadata" ] }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true, "description": "API token that created this order" } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_rate_source", "currency", "metadata", "merchant" ] }, "example": { "object": "order", "livemode": true, "id": "bcb3cddc-2fc3-456a-8e93-ae9dceb3d50b", "order_number": "ORD-1773457918-117", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "pending", "merchant_id": "b9475619-be78-4b05-b040-fa85171dab1a", "channel_id": null, "wallet_id": "a405197e-6f13-42d8-bd90-901db95a8efe", "discount_id": null, "created_at": "2026-03-14T03:11:58.466Z", "updated_at": "2026-03-14T03:11:58.466Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457918-117", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {}, "merchant": { "object": "merchant", "id": "b9475619-be78-4b05-b040-fa85171dab1a", "name": "Merchant 176", "email": "merchant176@example.com", "phone": "(555) 555-0100", "business_license": "LICENSE-001", "status": "active", "time_zone": "UTC", "currency": "usd", "created_at": "2026-03-14T03:11:58.460Z", "updated_at": "2026-03-14T03:11:58.460Z", "tip_options": [], "logo_url": null, "pos_theme": "dark", "pos_enabled": true, "privapaid_enabled": false, "channels": [], "wallets": [ { "object": "wallet", "id": "a405197e-6f13-42d8-bd90-901db95a8efe", "name": "Wallet 177", "status": "active", "enabled": true, "position": 179, "created_at": "2026-03-14T03:11:58.464Z", "updated_at": "2026-03-14T03:11:58.464Z", "operational": true, "lightning": { "lightning_address": "testmerchant182@phoenix.acinq.co" } } ], "taxes": [] }, "cash_paid_at": "2026-03-14T03:11:57.078Z", "payment": { "object": "payment", "livemode": true, "id": "4fcd5112-5dc7-428b-a58a-b4c94c861721", "amount_sats": null, "preimage": null, "confirmed_at": "2026-03-14T03:11:57.078Z", "order_id": "62037323-3c46-46b8-a04d-5320808d2326", "invoice_id": null, "created_at": "2026-03-14T03:11:57.079Z", "updated_at": "2026-03-14T03:11:57.079Z", "channel_id": null, "payment_hash": null, "settled_at": "2026-03-14T03:11:57.078Z", "usd_value_at_payment": "100.0", "currency": "usd", "fiat_value_at_payment": "100.0", "confirmations": 0, "required_confirmations": 1, "metadata": {} } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "61f95450-9abf-43b1-a602-ec62b56b138e" } } } } }, "404": { "description": "live token cannot access test order by ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Order not found", "status": 404, "request_id": "0874ca32-2e29-4312-80cc-a01298370338" } } } } } } }, "patch": { "summary": "update", "tags": [ "Api::V1::M::Order" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "72aa9f7f-4751-46ad-b208-155d5e81ece3" } ], "responses": { "200": { "description": "marks cash order as paid via status update", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string", "nullable": true }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "nullable": true, "description": "The customer's email address, where the receipt goes" }, "metadata": { "type": "object", "properties": { "ref": { "type": "string" }, "note": { "type": "string" } } }, "cash_paid_at": { "type": "string" }, "merchant": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "business_license": { "type": "string" }, "status": { "type": "string" }, "time_zone": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tip_options": { "type": "array", "items": {} }, "logo_url": { "nullable": true }, "pos_theme": { "type": "string" }, "pos_enabled": { "type": "boolean" }, "privapaid_enabled": { "type": "boolean" }, "channels": { "type": "array", "items": {} }, "wallets": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operational": { "type": "boolean" }, "lightning": { "type": "object", "properties": { "lightning_address": { "type": "string" } }, "required": [ "lightning_address" ] } }, "required": [ "object", "id", "name", "status", "enabled", "position", "created_at", "updated_at", "operational", "lightning" ] } }, "taxes": { "type": "array", "items": {} } }, "required": [ "object", "id", "name", "email", "phone", "business_license", "status", "time_zone", "currency", "created_at", "updated_at", "tip_options", "logo_url", "pos_theme", "pos_enabled", "privapaid_enabled", "channels", "wallets", "taxes" ] }, "payment": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "amount_sats": { "nullable": true }, "preimage": { "nullable": true }, "confirmed_at": { "type": "string" }, "order_id": { "type": "string" }, "invoice_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "channel_id": { "nullable": true }, "payment_hash": { "nullable": true }, "settled_at": { "type": "string" }, "usd_value_at_payment": { "type": "string" }, "currency": { "type": "string" }, "fiat_value_at_payment": { "type": "string" }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "amount_sats", "preimage", "confirmed_at", "order_id", "invoice_id", "created_at", "updated_at", "channel_id", "payment_hash", "settled_at", "usd_value_at_payment", "currency", "fiat_value_at_payment", "confirmations", "required_confirmations", "metadata" ] }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true, "description": "API token that created this order" } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_rate_source", "currency", "metadata" ] }, "example": { "object": "order", "livemode": true, "id": "72aa9f7f-4751-46ad-b208-155d5e81ece3", "order_number": "ORD-1773457917-80", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100, "status": "paid", "merchant_id": "b30a692c-48f0-460f-940c-bfbca552fc17", "channel_id": null, "wallet_id": null, "discount_id": null, "created_at": "2026-03-14T03:11:57.057Z", "updated_at": "2026-03-14T03:11:57.064Z", "tender_type": "cash", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457917-80", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": { "ref": "123", "note": "sneaky" }, "cash_paid_at": "2026-03-14T03:11:57.064Z", "merchant": { "object": "merchant", "id": "b30a692c-48f0-460f-940c-bfbca552fc17", "name": "Merchant 102", "email": "merchant102@example.com", "phone": "(555) 555-0100", "business_license": "LICENSE-001", "status": "active", "time_zone": "UTC", "currency": "usd", "created_at": "2026-03-14T03:11:57.052Z", "updated_at": "2026-03-14T03:11:57.052Z", "tip_options": [], "logo_url": null, "pos_theme": "dark", "pos_enabled": true, "privapaid_enabled": false, "channels": [], "wallets": [ { "object": "wallet", "id": "a2507cb3-e5f7-40a4-abc7-a5efe52bb2c7", "name": "Wallet 104", "status": "active", "enabled": true, "position": 106, "created_at": "2026-03-14T03:11:57.056Z", "updated_at": "2026-03-14T03:11:57.056Z", "operational": true, "lightning": { "lightning_address": "testmerchant109@phoenix.acinq.co" } } ], "taxes": [] }, "payment": { "object": "payment", "livemode": true, "id": "8da30daa-e106-4496-bb1a-959d05a7c0b6", "amount_sats": null, "preimage": null, "confirmed_at": "2026-03-14T03:11:57.064Z", "order_id": "72aa9f7f-4751-46ad-b208-155d5e81ece3", "invoice_id": null, "created_at": "2026-03-14T03:11:57.065Z", "updated_at": "2026-03-14T03:11:57.065Z", "channel_id": null, "payment_hash": null, "settled_at": "2026-03-14T03:11:57.064Z", "usd_value_at_payment": "100.0", "currency": "usd", "fiat_value_at_payment": "100.0", "confirmations": 0, "required_confirmations": 1, "metadata": {} } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "53577e63-acb1-4048-8351-e83d54e02046" } } } } }, "404": { "description": "prevents updating other merchant's orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Order not found", "status": 404, "request_id": "9d6d6c8c-da3e-4e32-b12a-300ee55b2c48" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "total_amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "description": "The customer's email address. The receipt is sent to it once the order is paid, if the merchant sends receipts." }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "metadata": { "type": "object", "properties": { "ref": { "type": "string" }, "note": { "type": "string" } } }, "status": { "type": "string" }, "wallet_id": { "type": "string" }, "tender_type": { "type": "string" } } } }, "required": [ "order" ] }, "example": { "order": { "total_amount_cents": 9999, "currency": "eur", "items": [ { "name": "New Item", "price_cents": 2000, "qty": 1 } ], "metadata": { "ref": "123", "note": "sneaky" }, "status": "paid", "wallet_id": "e3099d67-a21a-47a9-ac82-dc6a0d88c168", "tender_type": "cash" } } } } } } }, "/api/v1/m/payment_requests": { "post": { "summary": "create", "tags": [ "Api::V1::M::PaymentRequest" ], "responses": { "201": { "description": "returns lightning-specific fields with correct types", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" } }, "required": [ "object", "id", "payment_method", "amount_sats", "created_at", "expires_at", "payment_request", "payment_hash" ] }, "example": { "object": "payment_request", "id": "1d36a2e1-aa00-4400-b24c-4ff451b47289", "payment_method": "lightning", "amount_sats": 10000, "created_at": "2026-03-14T03:11:57Z", "expires_at": "2026-03-14T04:11:57Z", "payment_request": "lnbc200n1pj9q...", "payment_hash": "7475af0f76afbd075f49698ea177c8b08f1cf39a15dee677064677756b3d1554" } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "aa0fd1ef-e3d6-4501-8d85-984b62d1c121" } } } } }, "422": { "description": "returns error for invalid payment method", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "details", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "status": 422, "details": [ "payment_method must be 'lightning'" ], "request_id": "ddbce1f0-142d-41bd-88af-a8e95283575f" } } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_request": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "payment_method": { "type": "string" }, "description": { "type": "string" }, "customer_email": { "type": "string", "format": "email", "description": "The customer's email address. The receipt is sent to it once the order is paid, if the merchant sends receipts." } }, "required": [ "amount_cents", "payment_method", "description" ] } }, "required": [ "payment_request" ] }, "example": { "payment_request": { "amount_cents": 10000, "payment_method": "lightning", "description": "Test payment" } } } } } } }, "/api/v1/m/payment_requests/{id}": { "get": { "summary": "show", "tags": [ "Api::V1::M::PaymentRequest" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "e39ebc0b-1dbf-4386-9daa-3d6dbfb33ba9" } ], "responses": { "200": { "description": "returns paid status with paid_at", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "status": { "type": "string" }, "paid_at": { "nullable": true, "type": "string" }, "amount_paid_sats": { "nullable": true } }, "required": [ "object", "id", "payment_method", "amount_sats", "created_at", "expires_at", "payment_request", "payment_hash", "status", "paid_at", "amount_paid_sats" ] }, "example": { "object": "payment_request", "id": "e39ebc0b-1dbf-4386-9daa-3d6dbfb33ba9", "payment_method": "lightning", "amount_sats": 10000, "created_at": "2026-03-14T03:11:57Z", "expires_at": "2026-03-14T04:11:57Z", "payment_request": "lnbc250n1pj9q...", "payment_hash": "95e9191c6bde0074eaa855d51372136cb327c1327b184aa7df85d48d9b8d64a7", "status": "paid", "paid_at": "2026-03-14T03:11:57Z", "amount_paid_sats": null } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "d7ca6e9c-66f6-44a8-b915-7b7f918863bd" } } } } }, "404": { "description": "prevents access to other merchant's payment requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Payment request not found", "status": 404, "request_id": "82e35e66-6d39-4a11-a08f-83a30ed6ba0d" } } } } } } } }, "/api/v1/m/payment_requests/{id}/status": { "get": { "summary": "status", "tags": [ "Api::V1::M::PaymentRequest" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "eeb10982-feea-478e-8bab-18a0daa27751" } ], "responses": { "200": { "description": "returns paid_at timestamp", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "paid_at": { "nullable": true, "type": "string" }, "amount_sats": { "type": "integer" }, "amount_paid_sats": { "nullable": true } }, "required": [ "id", "status", "paid_at", "amount_sats", "amount_paid_sats" ] }, "example": { "id": "eeb10982-feea-478e-8bab-18a0daa27751", "status": "paid", "paid_at": "2026-03-14T03:11:57Z", "amount_sats": 10000, "amount_paid_sats": null } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "18068f21-3a42-4c46-b1be-017b130ee80e" } } } } }, "404": { "description": "prevents access to other merchant's payment requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Payment request not found", "status": 404, "request_id": "3aa47db9-cefd-4b68-b441-23bb7137350c" } } } } } } } }, "/api/v1/m/payments": { "get": { "summary": "index", "tags": [ "Api::V1::M::Payment" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 10 }, { "name": "q[amount_sats_gteq]", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 10000 }, { "name": "q[confirmed_at_gteq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-03-07T03:11:57Z" }, { "name": "q[confirmed_at_lteq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-03-14T03:11:57Z" }, { "name": "q[order_id_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "cf9959e1-fa40-46f6-9e1f-37e46eb628c7" } ], "responses": { "200": { "description": "only returns payments for the authenticated merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "amount_sats": { "type": "integer" }, "preimage": { "type": "string" }, "confirmed_at": { "type": "string" }, "order_id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "channel_id": { "nullable": true }, "payment_hash": { "type": "string" }, "settled_at": { "type": "string" }, "btc_usd_price_at_payment": { "type": "string" }, "usd_value_at_payment": { "type": "string" }, "usd_variance_cents": { "type": "integer" }, "variance_percentage": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_payment": { "type": "string" }, "fiat_value_at_payment": { "type": "string" }, "fiat_variance_cents": { "type": "integer" }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "metadata": { "type": "object", "properties": {} }, "order": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string" }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_price_at_creation", "btc_usd_rate_source", "currency", "btc_fiat_price_at_creation", "metadata" ] }, "invoice": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "nullable": true }, "order_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "expired": { "type": "boolean" }, "time_until_expiry": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "payment_method", "amount_sats", "status", "expires_at", "paid_at", "order_id", "created_at", "updated_at", "payment_request", "payment_hash", "expired", "time_until_expiry", "metadata" ] } }, "required": [ "object", "livemode", "id", "amount_sats", "preimage", "confirmed_at", "order_id", "invoice_id", "created_at", "updated_at", "channel_id", "payment_hash", "settled_at", "btc_usd_price_at_payment", "usd_value_at_payment", "usd_variance_cents", "variance_percentage", "currency", "btc_fiat_price_at_payment", "fiat_value_at_payment", "fiat_variance_cents", "confirmations", "required_confirmations", "metadata", "order", "invoice" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "nullable": true, "type": "integer" }, "prev_page": { "nullable": true } }, "required": [ "current_page", "per_page", "total_count", "total_pages", "next_page", "prev_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "object": "payment", "livemode": true, "id": "02b006ee-4702-48fa-98f7-77b5de05058b", "amount_sats": 10000, "preimage": "preimage_9befbda3e23e242eac5fa0db8ab881ae_44", "confirmed_at": "2026-03-14T03:11:57.610Z", "order_id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d", "invoice_id": "975788bb-d881-4927-8f13-5d9cfaf5a166", "created_at": "2026-03-14T03:11:57.611Z", "updated_at": "2026-03-14T03:11:57.611Z", "channel_id": null, "payment_hash": "b33ebd4143de8da227917204b4480f38e2c66a093f7d5d07b40d1a45f69d03b6", "settled_at": "2026-03-14T03:11:57.610Z", "btc_usd_price_at_payment": "100000.0", "usd_value_at_payment": "10.0", "usd_variance_cents": -9000, "variance_percentage": "-90.0", "currency": "usd", "btc_fiat_price_at_payment": "100000.0", "fiat_value_at_payment": "10.0", "fiat_variance_cents": -9000, "confirmations": 0, "required_confirmations": 1, "metadata": {}, "order": { "object": "order", "livemode": true, "id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d", "order_number": "ORD-1773457917-104", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "paid", "merchant_id": "80161a5f-b712-4072-890b-bad1dc3f9b0a", "channel_id": null, "wallet_id": "2ce37d06-aec3-408a-8d99-619a37cef996", "discount_id": null, "created_at": "2026-03-14T03:11:57.607Z", "updated_at": "2026-03-14T03:11:57.607Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457917-104", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} }, "invoice": { "object": "invoice", "livemode": true, "id": "975788bb-d881-4927-8f13-5d9cfaf5a166", "payment_method": "lightning", "amount_sats": 10000, "status": "paid", "expires_at": "2026-03-14T04:11:57.609Z", "paid_at": null, "order_id": "5959dde2-8bcd-43d0-bbb4-6994e6bfea8d", "created_at": "2026-03-14T03:11:57.609Z", "updated_at": "2026-03-14T03:11:57.609Z", "payment_request": "lnbc380n1pj9q...", "payment_hash": "b33ebd4143de8da227917204b4480f38e2c66a093f7d5d07b40d1a45f69d03b6", "expired": false, "time_until_expiry": 3599, "metadata": {} } } ], "meta": { "current_page": 1, "per_page": 25, "total_count": 1, "total_pages": 1, "next_page": null, "prev_page": null } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "2d1f2d3e-553d-409a-851b-bd09cd51af00" } } } } } } } }, "/api/v1/m/payments/{id}": { "get": { "summary": "show", "tags": [ "Api::V1::M::Payment" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "c1ecee92-955b-4fa0-894b-20fa391c15aa" } ], "responses": { "200": { "description": "includes timestamp information with correct types", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "amount_sats": { "type": "integer" }, "preimage": { "type": "string" }, "confirmed_at": { "type": "string" }, "order_id": { "type": "string" }, "invoice_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "channel_id": { "nullable": true }, "payment_hash": { "type": "string" }, "settled_at": { "type": "string" }, "btc_usd_price_at_payment": { "type": "string" }, "usd_value_at_payment": { "type": "string" }, "usd_variance_cents": { "type": "integer" }, "variance_percentage": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_payment": { "type": "string" }, "fiat_value_at_payment": { "type": "string" }, "fiat_variance_cents": { "type": "integer" }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "metadata": { "type": "object", "properties": {} }, "order": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "total_amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "discount_amount_cents": { "type": "integer" }, "total_amount_sats": { "type": "integer" }, "status": { "type": "string" }, "merchant_id": { "type": "string" }, "channel_id": { "nullable": true }, "wallet_id": { "type": "string" }, "discount_id": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tender_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price_cents": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "name", "price_cents", "qty" ] } }, "po_number": { "type": "string" }, "btc_usd_price_at_creation": { "type": "string" }, "btc_usd_rate_source": { "type": "string" }, "currency": { "type": "string" }, "btc_fiat_price_at_creation": { "type": "string" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "order_number", "total_amount_cents", "tax_amount_cents", "discount_amount_cents", "total_amount_sats", "status", "merchant_id", "channel_id", "wallet_id", "discount_id", "created_at", "updated_at", "tender_type", "items", "po_number", "btc_usd_price_at_creation", "btc_usd_rate_source", "currency", "btc_fiat_price_at_creation", "metadata" ] }, "invoice": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "payment_method": { "type": "string" }, "amount_sats": { "type": "integer" }, "status": { "type": "string" }, "expires_at": { "type": "string" }, "paid_at": { "nullable": true }, "order_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "payment_request": { "type": "string" }, "payment_hash": { "type": "string" }, "expired": { "type": "boolean" }, "time_until_expiry": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "payment_method", "amount_sats", "status", "expires_at", "paid_at", "order_id", "created_at", "updated_at", "payment_request", "payment_hash", "expired", "time_until_expiry", "metadata" ] } }, "required": [ "object", "livemode", "id", "amount_sats", "preimage", "confirmed_at", "order_id", "invoice_id", "created_at", "updated_at", "channel_id", "payment_hash", "settled_at", "btc_usd_price_at_payment", "usd_value_at_payment", "usd_variance_cents", "variance_percentage", "currency", "btc_fiat_price_at_payment", "fiat_value_at_payment", "fiat_variance_cents", "confirmations", "required_confirmations", "metadata", "order", "invoice" ] }, "example": { "object": "payment", "livemode": true, "id": "c1ecee92-955b-4fa0-894b-20fa391c15aa", "amount_sats": 10000, "preimage": "preimage_89a7358f79c0c62abef0b1b18d504354_50", "confirmed_at": "2026-03-14T03:11:57.740Z", "order_id": "46c49a03-b055-4d86-b406-15a2c612051f", "invoice_id": "752fe94f-25e6-4b4a-9323-9801bda1c9b2", "created_at": "2026-03-14T03:11:57.741Z", "updated_at": "2026-03-14T03:11:57.741Z", "channel_id": null, "payment_hash": "5a63a65dcbb2d6d87015a34a6163e4864b39657d6843abbc878b4aec54b00ac6", "settled_at": "2026-03-14T03:11:57.740Z", "btc_usd_price_at_payment": "100000.0", "usd_value_at_payment": "10.0", "usd_variance_cents": -9000, "variance_percentage": "-90.0", "currency": "usd", "btc_fiat_price_at_payment": "100000.0", "fiat_value_at_payment": "10.0", "fiat_variance_cents": -9000, "confirmations": 0, "required_confirmations": 1, "metadata": {}, "order": { "object": "order", "livemode": true, "id": "46c49a03-b055-4d86-b406-15a2c612051f", "order_number": "ORD-1773457917-110", "total_amount_cents": 10000, "tax_amount_cents": 0, "discount_amount_cents": 0, "total_amount_sats": 100000, "status": "paid", "merchant_id": "f441a972-a1cd-47b9-8738-8ce101ba00f2", "channel_id": null, "wallet_id": "9d9411f0-0fd4-4a9c-af6d-b07390826a11", "discount_id": null, "created_at": "2026-03-14T03:11:57.736Z", "updated_at": "2026-03-14T03:11:57.736Z", "tender_type": "bitcoin", "items": [ { "name": "Item 1", "price_cents": 10000, "qty": 1 } ], "po_number": "ORD-1773457917-110", "btc_usd_price_at_creation": "100000.0", "btc_usd_rate_source": "coinbase", "currency": "usd", "btc_fiat_price_at_creation": "100000.0", "metadata": {} }, "invoice": { "object": "invoice", "livemode": true, "id": "752fe94f-25e6-4b4a-9323-9801bda1c9b2", "payment_method": "lightning", "amount_sats": 10000, "status": "paid", "expires_at": "2026-03-14T04:11:57.739Z", "paid_at": null, "order_id": "46c49a03-b055-4d86-b406-15a2c612051f", "created_at": "2026-03-14T03:11:57.739Z", "updated_at": "2026-03-14T03:11:57.739Z", "payment_request": "lnbc440n1pj9q...", "payment_hash": "5a63a65dcbb2d6d87015a34a6163e4864b39657d6843abbc878b4aec54b00ac6", "expired": false, "time_until_expiry": 3599, "metadata": {} } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "963f7bba-0407-4190-b5fc-22d345d210ab" } } } } }, "404": { "description": "prevents access to other merchant's payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Payment not found", "status": 404, "request_id": "ab3c3ee0-825a-4981-ab8c-418b9c6be7fd" } } } } } } } }, "/api/v1/m/sessions": { "post": { "summary": "create", "tags": [ "Api::V1::M::Session" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ] }, "example": { "email": "user28@example.com", "password": "password123456" } } } }, "responses": { "200": { "description": "resets failed attempts on successful login", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string" }, "merchants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logo_url": { "nullable": true }, "currency": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "name", "logo_url", "currency", "role" ] } } }, "required": [ "session_token", "merchants" ] }, "example": { "session_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJ1c2VyX2lkIjoiYjdjNDA4NGYtOWYxYi00MjRmLWE4ODMtZjQ2NWU1ZmRhZTE0IiwiZXhwIjoxNzczNDU5NzE4fSwicHVyIjoicG9zX3Nlc3Npb24ifX0=--dfc82ff6369ff136daace5c67630f30259ad9f92", "merchants": [ { "id": "c0326624-c893-4701-a99e-bea7fa0b67ca", "name": "Merchant 153", "logo_url": null, "currency": "usd", "role": "owner" } ] } } } }, "400": { "description": "returns 400 for missing credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_credentials", "message": "Email and password are required", "status": 400, "request_id": "ccfa9291-ff00-40b8-a8ff-2f03e8a0baf2" } } } } }, "401": { "description": "increments failed attempts on wrong password", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "invalid_credentials", "message": "Invalid email or password", "status": 401, "request_id": "fe508467-571a-481c-a7e0-b59759accd92" } } } } }, "423": { "description": "rejects valid credentials when account is locked", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "account_locked", "message": "Account locked due to too many failed attempts. Try again later.", "status": 423, "request_id": "bc3e1adb-52aa-4734-9418-66f12ae47bb9" } } } } } } } }, "/api/v1/m/sessions/activate": { "post": { "summary": "activate", "tags": [ "Api::V1::M::Session" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string" }, "merchant_id": { "type": "string" } }, "required": [ "session_token", "merchant_id" ] }, "example": { "session_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJ1c2VyX2lkIjoiOTZjZDY3MzEtZGJkZi00MWEwLWEwNGYtNWQ1MjgzZTk0ZTU5IiwiZXhwIjoxNzczNDU5NzE4fSwicHVyIjoicG9zX3Nlc3Npb24ifX0=--981626a7484c548066b74e2ecd5b83b6cd664e53", "merchant_id": "c378f7fe-c4ab-47b4-9660-48865734bcfb" } } } }, "responses": { "200": { "description": "still allows activation (POS available to all plans)", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "merchant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "id", "name", "currency" ] } }, "required": [ "api_key", "merchant" ] }, "example": { "api_key": "sk_live_YOUR_SECRET_KEY", "merchant": { "id": "c378f7fe-c4ab-47b4-9660-48865734bcfb", "name": "Merchant 165", "currency": "usd" } } } } }, "400": { "description": "returns 400 for missing params", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_params", "message": "Session token and merchant ID are required", "status": 400, "request_id": "850f36bb-bc37-4a84-9ff8-8b5b3cb5b5f3" } } } } }, "401": { "description": "returns 401 for invalid session token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "invalid_session", "message": "Session expired or invalid. Please sign in again.", "status": 401, "request_id": "64d617a6-8aa1-46a6-afe5-c8d73488bb6c" } } } } }, "403": { "description": "returns 403 for non-operational merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "merchant_not_operational", "message": "Merchant account is not active", "status": 403, "request_id": "772fe76a-87e9-4f15-b861-528bbf48656c" } } } } }, "404": { "description": "returns 404 for merchant with no active API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "no_api_key", "message": "No active API key found for this merchant. Create one in the dashboard.", "status": 404, "request_id": "9c510f54-7cac-471c-85b8-787f1fb3aceb" } } } } } } } }, "/api/v1/m/wallets": { "get": { "summary": "index", "tags": [ "Api::V1::M::Wallet" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "q[enabled_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true" }, { "name": "q[merchant_id_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "d81b5fe2-2df5-4709-ab99-b8a7e0c2b322" } ], "responses": { "200": { "description": "includes lightning section with lightning_address", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operational": { "type": "boolean" }, "lightning": { "type": "object", "properties": { "lightning_address": { "type": "string" } }, "required": [ "lightning_address" ] } }, "required": [ "object", "id", "name", "status", "enabled", "position", "created_at", "updated_at", "operational", "lightning" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "nullable": true }, "prev_page": { "nullable": true } }, "required": [ "current_page", "per_page", "total_count", "total_pages", "next_page", "prev_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "object": "wallet", "id": "0251fcd0-5751-4a9c-b3f1-101117555196", "name": "Wallet 189", "status": "active", "enabled": true, "position": 191, "created_at": "2026-03-14T03:11:58.590Z", "updated_at": "2026-03-14T03:11:58.590Z", "operational": true, "lightning": { "lightning_address": "shop@phoenix.acinq.co" } } ], "meta": { "current_page": 1, "per_page": 25, "total_count": 1, "total_pages": 1, "next_page": null, "prev_page": null } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "c82ccb12-025c-49f8-9ba7-fe2afba01d58" } } } } } } } }, "/api/v1/m/wallets/{id}": { "get": { "summary": "show", "tags": [ "Api::V1::M::Wallet" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "21a10ea0-c9fe-406f-a02e-713ac4ef43d8" } ], "responses": { "200": { "description": "does not include display_name, status_color, or next_payment_address", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "operational": { "type": "boolean" }, "lightning": { "type": "object", "properties": { "lightning_address": { "type": "string" } }, "required": [ "lightning_address" ] }, "last_checked_at": { "nullable": true }, "last_transaction_at": { "nullable": true }, "last_error": { "nullable": true, "type": "string" }, "consecutive_failures": { "type": "integer" } }, "required": [ "object", "id", "name", "status", "enabled", "position", "created_at", "updated_at", "operational", "lightning", "last_checked_at", "last_transaction_at", "last_error", "consecutive_failures" ] }, "example": { "object": "wallet", "id": "b93639c1-8515-4935-adf7-020415a44411", "name": "Wallet 193", "status": "active", "enabled": true, "position": 195, "created_at": "2026-03-14T03:11:58.637Z", "updated_at": "2026-03-14T03:11:58.637Z", "operational": true, "lightning": { "lightning_address": "testmerchant198@phoenix.acinq.co" }, "last_checked_at": null, "last_transaction_at": null, "last_error": null, "consecutive_failures": 0 } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "cf3d9861-7efc-4132-98a2-9c91f40647b9" } } } } }, "404": { "description": "returns 404 with correct error structure for non-existent wallet", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Wallet not found", "status": 404, "request_id": "4ff5971c-9e8b-4c91-b48b-4827488300aa" } } } } } } } }, "/api/v1/m/webhooks": { "get": { "summary": "index", "tags": [ "Api::V1::M::Webhook" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "sk_live_YOUR_SECRET_KEY" }, { "name": "q[active_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true" }, { "name": "q[merchant_id_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "example": "40cba8fd-87fc-45db-bb45-2de7fdceab8e" } ], "responses": { "200": { "description": "only returns webhooks for the authenticated merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_triggered_at": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "health_percentage": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "url", "description", "events", "active", "success_count", "failure_count", "last_triggered_at", "created_at", "updated_at", "health_percentage", "metadata" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "nullable": true }, "prev_page": { "nullable": true } }, "required": [ "current_page", "per_page", "total_count", "total_pages", "next_page", "prev_page" ] }, "available_events": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "data", "meta", "available_events" ] }, "example": { "object": "list", "data": [ { "object": "webhook", "livemode": true, "id": "f0bdc2b8-8f71-4dcd-a4ad-dc81929e651f", "url": "https://example.com/webhooks", "description": "Test Webhook", "events": [ "order.created", "invoice.paid" ], "active": true, "success_count": 0, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-03-14T03:11:58.971Z", "updated_at": "2026-03-14T03:11:58.971Z", "health_percentage": 100, "metadata": {} } ], "meta": { "current_page": 1, "per_page": 25, "total_count": 1, "total_pages": 1, "next_page": null, "prev_page": null }, "available_events": [ "order.created", "order.updated", "invoice.created", "invoice.paid", "invoice.expired", "payment.received", "payment.confirmed" ] } } } }, "401": { "description": "rejects requests without Bearer prefix", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "7edfcfc8-beb2-46e3-998e-dd8580f9a3f8" } } } } } } }, "post": { "summary": "create", "tags": [ "Api::V1::M::Webhook" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } }, "required": [ "url", "events" ] } }, "required": [ "webhook" ] }, "example": { "webhook": { "url": "https://example.com/hook", "events": [ "order.created", "order.updated", "invoice.created", "invoice.paid", "invoice.expired", "payment.received", "payment.confirmed", "merchant.plan_changed" ], "description": "My test webhook" } } } } }, "responses": { "201": { "description": "creates a webhook with all available event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_triggered_at": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "health_percentage": { "type": "integer" }, "metadata": { "type": "object", "properties": {} }, "secret_key": { "type": "string" } }, "required": [ "object", "livemode", "id", "url", "description", "events", "active", "success_count", "failure_count", "last_triggered_at", "created_at", "updated_at", "health_percentage", "metadata", "secret_key" ] }, "example": { "object": "webhook", "livemode": true, "id": "db705776-1673-4757-8732-fa46cd868d1c", "url": "https://example.com/hook", "description": null, "events": [ "order.created", "order.updated", "invoice.created", "invoice.paid", "invoice.expired", "payment.received", "payment.confirmed" ], "active": true, "success_count": 0, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-03-14T03:11:59.075Z", "updated_at": "2026-03-14T03:11:59.075Z", "health_percentage": 100, "metadata": {}, "secret_key": "whsec_YOUR_WEBHOOK_SECRET" } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "c97bfd45-ce32-42e8-9086-6f7d7ade2cdb" } } } } }, "422": { "description": "returns validation errors for invalid url format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "details", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "status": 422, "details": [ "Url is invalid" ], "request_id": "f86d4e2c-7b5e-480b-8f57-d806c467c1e8" } } } } } } } }, "/api/v1/m/webhooks/{id}": { "delete": { "summary": "destroy", "tags": [ "Api::V1::M::Webhook" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "e885ab37-4295-41e4-bebc-3287142a555f" } ], "responses": { "204": { "description": "returns no content status" }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "7d3d0bd5-c76e-4503-91d7-5fe36000093b" } } } } }, "404": { "description": "prevents deleting other merchant's webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Webhook not found", "status": 404, "request_id": "0cc205a6-58ea-4dcf-ab9f-c7369a6a7bed" } } } } } } }, "get": { "summary": "show", "tags": [ "Api::V1::M::Webhook" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "e3ae1c97-c3eb-48bc-9fcd-5d48065884db" } ], "responses": { "200": { "description": "does not expose secret_key on show", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_triggered_at": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "health_percentage": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "url", "description", "events", "active", "success_count", "failure_count", "last_triggered_at", "created_at", "updated_at", "health_percentage", "metadata" ] }, "example": { "object": "webhook", "livemode": true, "id": "982ebe1a-819e-4d95-981e-3c77eca16d23", "url": "https://example.com/webhooks", "description": "Test Webhook", "events": [ "order.created", "invoice.paid" ], "active": true, "success_count": 0, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-03-14T03:11:58.995Z", "updated_at": "2026-03-14T03:11:58.995Z", "health_percentage": 100, "metadata": {} } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "07709b2e-3c26-423c-83b7-5ba1e885fe37" } } } } }, "404": { "description": "prevents access to other merchant's webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Webhook not found", "status": 404, "request_id": "ad65b2df-2ca0-4009-90a9-4d0cfe9a194f" } } } } } } }, "patch": { "summary": "update", "tags": [ "Api::V1::M::Webhook" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "07aed364-1bd1-4311-8872-a9694627b335" } ], "responses": { "200": { "description": "does not expose secret_key on update", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "success_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_triggered_at": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "health_percentage": { "type": "integer" }, "metadata": { "type": "object", "properties": {} } }, "required": [ "object", "livemode", "id", "url", "description", "events", "active", "success_count", "failure_count", "last_triggered_at", "created_at", "updated_at", "health_percentage", "metadata" ] }, "example": { "object": "webhook", "livemode": true, "id": "1ace2467-8c77-4f12-8139-54bc9fb206c8", "url": "https://example.com/webhooks", "description": "Updated", "events": [ "order.created", "invoice.paid" ], "active": true, "success_count": 0, "failure_count": 0, "last_triggered_at": null, "created_at": "2026-03-14T03:11:59.197Z", "updated_at": "2026-03-14T03:11:59.202Z", "health_percentage": 100, "metadata": {} } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "Missing API token. Include 'Authorization: Bearer YOUR_API_KEY' header.", "status": 401, "request_id": "789a2ae5-ea67-4322-93cf-3dc612a626f2" } } } } }, "404": { "description": "prevents updating other merchant's webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Webhook not found", "status": 404, "request_id": "74ccf675-dae2-42ee-817e-991a07a37d09" } } } } }, "422": { "description": "returns validation errors for invalid events", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "details", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "status": 422, "details": [ "Events contains invalid events: fake.event" ], "request_id": "c92155ac-b609-4ec9-adac-a219dd29ef03" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "description": { "type": "string" } } } }, "required": [ "webhook" ] }, "example": { "webhook": { "url": "https://updated.example.com/hook", "events": [ "payment.confirmed" ], "active": false, "description": "Updated" } } } } } } }, "/api/v1/pub/access/verify": { "post": { "summary": "verify", "tags": [ "Api::V1::Pub::Access" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer pk_live_YOUR_PUBLISHABLE_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" } } }, "example": { "access_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJwYXltZW50X2lkIjoicGF5LXRlc3QtdXVpZCIsInJlc291cmNlX2lkIjoicHJvZF9hYmMiLCJyZXNvdXJjZV90eXBlIjoic3RyZWFtIiwiZXhwIjoxNzczNDU4NTE5fSwiZXhwIjoiMjAyNi0wMy0xNFQwMzoyMTo1OS4zMDdaIiwicHVyIjoiYWNjZXNzX3Rva2VuIn19--1c6d12e1f86a6bba3be28f425669b2a0adf2449b" } } } }, "responses": { "200": { "description": "accepts token via X-Access-Token header", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "remaining_seconds": { "type": "integer" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } }, "required": [ "valid", "remaining_seconds", "resource_id", "resource_type" ] }, "example": { "valid": true, "remaining_seconds": 600, "resource_id": "prod_abc", "resource_type": "stream" } } } }, "400": { "description": "returns 400 when access_token param is missing", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_token", "message": "access_token is required", "status": 400, "request_id": "c2b5de35-7597-4a5d-a87a-214e48fafe78" } } } } }, "401": { "description": "returns 401 without a publishable key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_key", "message": "Missing embed key. Pass embed_key param or Authorization: Bearer header.", "status": 401, "request_id": "f64110de-75e3-4bd7-85e9-dcf73eca2337" } } } } }, "402": { "description": "returns 402 for a tampered token", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "code", "message", "status" ] } }, "required": [ "valid", "error" ] }, "example": { "valid": false, "error": { "code": "access_expired", "message": "Access token has expired or is invalid. Please complete a new payment.", "status": 402 } } } } }, "403": { "description": "returns 403 when merchant has privapaid disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "forbidden", "message": "Merchant does not have content gating enabled", "status": 403, "request_id": "e7ba7706-8b81-42ec-a82c-1b443d1fed7e" } } } } } } } }, "/api/v1/pub/categories": { "get": { "summary": "index", "tags": [ "Api::V1::Pub::Category" ], "responses": { "200": { "description": "sets public cache headers", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "data" ] }, "example": { "object": "list", "data": [ "Film & Animation", "Autos & Vehicles", "Music", "Pets & Animals", "Sports", "Travel & Events", "Gaming", "People & Blogs", "Comedy", "Entertainment", "News & Politics", "Howto & Style", "Education", "Science & Technology", "Nonprofits & Activism", "Adult" ] } } } } } } }, "/api/v1/pub/channels": { "get": { "summary": "index", "tags": [ "Api::V1::Pub::Channel" ], "responses": { "200": { "description": "defaults to 24 per page", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "bio": { "type": "string" }, "videos_count": { "type": "integer" }, "nsfw": { "type": "boolean" }, "theme": { "type": "string" }, "category": { "type": "string" }, "profile_image_url": { "nullable": true }, "social_links": { "type": "object", "properties": { "twitter": { "type": "string" }, "youtube": { "type": "string" }, "instagram": { "type": "string" } } }, "merchant_name": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "language": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "slug", "name", "bio", "videos_count", "nsfw", "theme", "category", "profile_image_url", "social_links", "merchant_name", "country", "country_name", "language", "currency" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" }, "per_page": { "type": "integer" } }, "required": [ "current_page", "total_pages", "total_count", "per_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "slug": "chan-1", "name": "Channel 15", "bio": "A test channel for streaming.", "videos_count": 0, "nsfw": false, "theme": "rose", "category": "Entertainment", "profile_image_url": null, "social_links": {}, "merchant_name": "Merchant 250", "country": "IQ", "country_name": "Country 224", "language": "en", "currency": "usd" } ], "meta": { "current_page": 1, "total_pages": 1, "total_count": 1, "per_page": 24 } } } } } }, "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Gaming" }, { "name": "nsfw", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 2 }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Gaming" } ] } }, "/api/v1/pub/checkout_sessions": { "post": { "summary": "create", "tags": [ "Api::V1::Pub::CheckoutSession" ], "responses": { "201": { "description": "accepts metadata hash", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "token": { "type": "string" }, "checkout_url": { "type": "string" }, "expires_at": { "type": "string" }, "amount_cents": { "type": "integer" }, "tax_amount_cents": { "type": "integer" }, "tax_details": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "rate": { "type": "string" }, "amount_cents": { "type": "integer" } }, "required": [ "name", "rate", "amount_cents" ] } }, "currency": { "type": "string" }, "status": { "type": "string" }, "customer_email": { "nullable": true, "type": "string" }, "customer_name": { "nullable": true, "type": "string" }, "customer_phone": { "nullable": true }, "customer_address": { "nullable": true }, "checkout_mode": { "type": "string" }, "checkout_theme": { "type": "string" }, "checkout_accent_color": { "type": "string" }, "privapaid_enabled": { "type": "boolean" }, "metadata": { "type": "object", "properties": { "order_ref": { "type": "string" }, "source": { "type": "string" } } } }, "required": [ "object", "livemode", "id", "token", "checkout_url", "expires_at", "amount_cents", "tax_amount_cents", "tax_details", "currency", "status", "customer_email", "customer_name", "customer_phone", "customer_address", "checkout_mode", "checkout_theme", "checkout_accent_color", "privapaid_enabled", "metadata" ] }, "example": { "object": "checkout_session", "livemode": true, "id": "1ba2644d-ca41-479d-9689-db2e0e0b4657", "token": "cs_Ku60a_FLU38Nls2UOZyfvdjIs39RzcItqAiV0NK9IsQ", "checkout_url": "http://www.example.com/checkout/cs_Ku60a_FLU38Nls2UOZyfvdjIs39RzcItqAiV0NK9IsQ", "expires_at": "2026-03-14T03:26:55Z", "amount_cents": 5000, "tax_amount_cents": 0, "tax_details": [], "currency": "usd", "status": "pending", "customer_email": null, "customer_name": null, "customer_phone": null, "customer_address": null, "checkout_mode": "iframe", "checkout_theme": "light", "checkout_accent_color": "#e8b53c", "privapaid_enabled": false, "metadata": { "order_ref": "MY-123", "source": "website" } } } } }, "401": { "description": "requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "missing_key", "message": "Missing embed key. Pass embed_key param or Authorization: Bearer header.", "status": 401, "request_id": "4fc922bc-70bd-44c2-9b41-47deb8012627" } } } } }, "422": { "description": "returns validation error for invalid email", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "details", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "validation_error", "message": "Validation failed", "status": 422, "details": [ "Customer email is invalid" ], "request_id": "f8562aae-e2f0-405c-b0e6-bf50f239a3cf" } } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer pk_live_YOUR_PUBLISHABLE_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_session": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "product_id": { "type": "string" }, "customer_email": { "type": "string" }, "customer_name": { "type": "string" }, "metadata": { "type": "object", "properties": { "order_ref": { "type": "string" }, "source": { "type": "string" } }, "required": [ "order_ref", "source" ] } } } }, "required": [ "checkout_session" ] }, "example": { "checkout_session": { "amount_cents": 5000, "currency": "usd", "product_id": "prod_32bf92c24dbad85569bd9acd", "customer_email": "buyer@example.com", "customer_name": "Alice Smith", "metadata": { "order_ref": "MY-123", "source": "website" } } } } } } } }, "/api/v1/pub/creators": { "get": { "summary": "index", "tags": [ "Api::V1::Pub::Creator" ], "responses": { "200": { "description": "returns the same data as the channels endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "bio": { "type": "string" }, "videos_count": { "type": "integer" }, "nsfw": { "type": "boolean" }, "theme": { "type": "string" }, "category": { "type": "string" }, "profile_image_url": { "nullable": true }, "social_links": { "type": "object", "properties": {} }, "merchant_name": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "language": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "slug", "name", "bio", "videos_count", "nsfw", "theme", "category", "profile_image_url", "social_links", "merchant_name", "country", "country_name", "language", "currency" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" }, "per_page": { "type": "integer" } }, "required": [ "current_page", "total_pages", "total_count", "per_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "slug": "compat-test", "name": "Channel 16", "bio": "A test channel for streaming.", "videos_count": 0, "nsfw": false, "theme": "rose", "category": "Entertainment", "profile_image_url": null, "social_links": {}, "merchant_name": "Merchant 251", "country": "IR", "country_name": "Country 225", "language": "en", "currency": "usd" } ], "meta": { "current_page": 1, "total_pages": 1, "total_count": 1, "per_page": 24 } } } } } } } }, "/api/v1/pub/exchanges": { "get": { "summary": "index", "tags": [ "Api::V1::Pub::Exchange" ], "responses": { "200": { "description": "invalidates cache when an exchange_country is destroyed", "content": { "application/json": { "schema": { "type": "object", "properties": { "exchanges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "promoted": { "type": "boolean" }, "min_transaction_sats": { "nullable": true }, "notes": { "nullable": true }, "logo_url": { "nullable": true }, "countries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "iso_code": { "type": "string" } }, "required": [ "id", "name", "iso_code" ] } } }, "required": [ "id", "name", "url", "promoted", "min_transaction_sats", "notes", "logo_url", "countries" ] } } }, "required": [ "exchanges" ] }, "example": { "exchanges": [ { "id": "02f4199f-a5d2-4f93-ae93-581f4bafe650", "name": "Buda.com", "url": "https://buda.com", "promoted": true, "min_transaction_sats": null, "notes": null, "logo_url": null, "countries": [ { "id": "5f355627-8c07-4c5e-a8a7-2f05fe7be640", "name": "Chile", "iso_code": "CL" }, { "id": "ca256dfc-3513-419c-9e2c-5c3c50fa4925", "name": "United States", "iso_code": "US" } ] } ] } } } } } } }, "/api/v1/pub/subscription_plans": { "get": { "summary": "index", "tags": [ "Api::V1::Pub::SubscriptionPlan" ], "responses": { "200": { "description": "includes features as a hash", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "price_display": { "type": "string" }, "interval": { "type": "string" }, "max_monthly_volume_cents": { "type": "integer", "nullable": true }, "features": { "type": "object", "properties": { "basic_reports": { "type": "boolean" }, "accounting:reports": { "type": "boolean" }, "email_support": { "type": "boolean", "nullable": true }, "webhook_endpoints": { "type": "integer", "nullable": true }, "team_members": { "type": "integer", "nullable": true }, "max_monthly_transactions": { "type": "integer", "nullable": true }, "pos_access": { "type": "boolean" }, "privapaid_access": { "type": "boolean" }, "max_channels": { "type": "integer", "nullable": true }, "report_history_days": { "type": "integer", "nullable": true }, "support_tier": { "type": "string" }, "priority_support": { "type": "boolean", "nullable": true } }, "required": [ "basic_reports", "accounting:reports", "webhook_endpoints", "team_members", "max_monthly_transactions", "pos_access", "privapaid_access", "max_channels", "report_history_days", "support_tier" ] }, "feature_labels": { "type": "array", "items": { "type": "string" } }, "rate_limits": { "type": "object", "properties": { "per_api_key_per_minute": { "type": "integer" }, "per_api_key_per_hour": { "type": "integer" }, "delivery_per_order_per_hour": { "type": "integer" }, "unauthenticated_per_minute": { "type": "integer", "nullable": true } }, "required": [ "per_api_key_per_minute", "per_api_key_per_hour", "delivery_per_order_per_hour" ] } }, "required": [ "slug", "name", "description", "price_cents", "price_display", "interval", "max_monthly_volume_cents", "features", "feature_labels", "rate_limits" ] } } }, "required": [ "plans" ] }, "example": { "plans": [ { "slug": "free", "name": "Free", "description": "Get started with Bitcoin Lightning payments \u2014 no credit card required", "price_cents": 0, "price_display": "$0.00/month", "interval": "month", "max_monthly_volume_cents": 50000, "features": { "basic_reports": true, "accounting:reports": false, "email_support": true, "webhook_endpoints": 0, "team_members": 3, "max_monthly_transactions": 100, "pos_access": true, "privapaid_access": true, "max_channels": 1, "report_history_days": 30, "support_tier": "email" }, "feature_labels": [ "Basic reports", "Email support", "Point of Sale (POS)", "Privapaid", "3 team members", "100 transactions/mo", "1 channels" ], "rate_limits": { "per_api_key_per_minute": 20, "per_api_key_per_hour": 200, "delivery_per_order_per_hour": 10, "unauthenticated_per_minute": 20 } }, { "slug": "starter", "name": "Starter", "description": "For small businesses accepting Bitcoin payments", "price_cents": 2900, "price_display": "$29.00/month", "interval": "month", "max_monthly_volume_cents": 1000000, "features": { "basic_reports": true, "accounting:reports": false, "email_support": true, "webhook_endpoints": 2, "team_members": 10, "max_monthly_transactions": null, "pos_access": true, "privapaid_access": true, "max_channels": 1, "report_history_days": null, "support_tier": "email" }, "feature_labels": [ "Basic reports", "Email support", "Point of Sale (POS)", "Privapaid", "2 webhook endpoints", "10 team members", "1 channels" ], "rate_limits": { "per_api_key_per_minute": 100, "per_api_key_per_hour": 1000, "delivery_per_order_per_hour": 10 } }, { "slug": "pro", "name": "Pro", "description": "Full-featured payment processing for growing businesses", "price_cents": 9900, "price_display": "$99.00/month", "interval": "month", "max_monthly_volume_cents": 5000000, "features": { "basic_reports": true, "accounting:reports": true, "priority_support": true, "webhook_endpoints": 10, "team_members": 25, "max_monthly_transactions": null, "pos_access": true, "privapaid_access": true, "max_channels": 3, "report_history_days": null, "support_tier": "priority" }, "feature_labels": [ "Basic reports", "Accounting reports", "Priority support", "Point of Sale (POS)", "Privapaid", "10 webhook endpoints", "25 team members", "3 channels" ], "rate_limits": { "per_api_key_per_minute": 300, "per_api_key_per_hour": 5000, "delivery_per_order_per_hour": 30 } }, { "slug": "business", "name": "Business", "description": "Enterprise-grade Bitcoin payment infrastructure", "price_cents": 29900, "price_display": "$299.00/month", "interval": "month", "max_monthly_volume_cents": null, "features": { "basic_reports": true, "accounting:reports": true, "priority_support": true, "webhook_endpoints": null, "team_members": null, "max_monthly_transactions": null, "pos_access": true, "privapaid_access": true, "max_channels": 10, "report_history_days": null, "support_tier": "priority" }, "feature_labels": [ "Basic reports", "Accounting reports", "Priority support", "Point of Sale (POS)", "Privapaid", "10 channels" ], "rate_limits": { "per_api_key_per_minute": 1000, "per_api_key_per_hour": 20000, "delivery_per_order_per_hour": 100 } }, { "slug": "agency", "name": "Agency", "description": "For agencies and networks managing multiple creator channels", "price_cents": 99900, "price_display": "$999.00/month", "interval": "month", "max_monthly_volume_cents": null, "features": { "basic_reports": true, "accounting:reports": true, "priority_support": true, "webhook_endpoints": null, "team_members": null, "max_monthly_transactions": null, "pos_access": true, "privapaid_access": true, "max_channels": null, "report_history_days": null, "support_tier": "priority" }, "feature_labels": [ "Basic reports", "Accounting reports", "Priority support", "Point of Sale (POS)", "Privapaid" ], "rate_limits": { "per_api_key_per_minute": 1000, "per_api_key_per_hour": 20000, "delivery_per_order_per_hour": 100 } } ] } } } } } } }, "/api/v1/m/products": { "get": { "summary": "List products", "description": "Returns a paginated list of products for the authenticated merchant. Supports filtering by name, status, sku, and date range.", "tags": [ "Api::V1::M::Product" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 25 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 1 }, { "name": "q[name_cont]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by name (contains)" }, { "name": "q[status_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by status", "example": "active" }, { "name": "q[sku_eq]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by SKU" }, { "name": "q[created_at_gteq]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Created after (ISO 8601)" }, { "name": "q[created_at_lteq]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Created before (ISO 8601)" } ], "responses": { "200": { "description": "returns paginated list of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "livemode": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "position": { "type": "integer" }, "resource_type": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "access_duration_seconds": { "type": "integer", "nullable": true }, "product_type_id": { "type": "string", "format": "uuid", "nullable": true }, "merchant_id": { "type": "string", "format": "uuid" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "formatted_price": { "type": "string" }, "payment_link_url": { "type": "string", "nullable": true, "format": "uri", "description": "The product's payment link (/pay/:slug): a URL to send a customer that opens the hosted checkout at this price. Null while the product is not active." }, "metadata": { "type": "object" } }, "required": [ "id", "name", "slug", "price_cents", "status", "merchant_id", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_count": { "type": "integer" }, "per_page": { "type": "integer" } } } } } } } }, "401": { "description": "unauthorized \u2014 missing or invalid API token" } } }, "post": { "summary": "Create a product", "description": "Creates a new product for the authenticated merchant. The product is automatically associated with the API token used to create it.", "tags": [ "Api::V1::M::Product" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "sku": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "product_type_id": { "type": "string", "format": "uuid", "description": "Product type to file it under. Omit to use the merchant's Default type, created on first use." }, "resource_type": { "type": "string" }, "image_url": { "type": "string" }, "access_duration_seconds": { "type": "integer" }, "metadata": { "type": "object" } }, "required": [ "name", "price_cents" ] } }, "required": [ "product" ] }, "example": { "product": { "name": "Premium Content", "description": "Access to premium content", "price_cents": 5000, "sku": "PREM-001", "resource_type": "digital", "image_url": "https://example.com/image.png" } } } } }, "responses": { "201": { "description": "product created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "livemode": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "position": { "type": "integer" }, "resource_type": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "access_duration_seconds": { "type": "integer", "nullable": true }, "product_type_id": { "type": "string", "format": "uuid", "nullable": true }, "merchant_id": { "type": "string", "format": "uuid" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "formatted_price": { "type": "string" }, "payment_link_url": { "type": "string", "nullable": true, "format": "uri", "description": "The product's payment link (/pay/:slug): a URL to send a customer that opens the hosted checkout at this price. Null while the product is not active." }, "metadata": { "type": "object" } }, "required": [ "id", "name", "slug", "price_cents", "status", "merchant_id", "created_at", "updated_at" ] } } } }, "422": { "description": "validation errors" }, "401": { "description": "unauthorized \u2014 missing or invalid API token" } } } }, "/api/v1/m/products/{id}": { "get": { "summary": "Get a product", "description": "Returns a single product by slug.", "tags": [ "Api::V1::M::Product" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug", "example": "premium-content" } ], "responses": { "200": { "description": "returns the product", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "livemode": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "position": { "type": "integer" }, "resource_type": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "access_duration_seconds": { "type": "integer", "nullable": true }, "product_type_id": { "type": "string", "format": "uuid", "nullable": true }, "merchant_id": { "type": "string", "format": "uuid" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "formatted_price": { "type": "string" }, "payment_link_url": { "type": "string", "nullable": true, "format": "uri", "description": "The product's payment link (/pay/:slug): a URL to send a customer that opens the hosted checkout at this price. Null while the product is not active." }, "metadata": { "type": "object" } }, "required": [ "id", "name", "slug", "price_cents", "status", "merchant_id", "created_at", "updated_at" ] } } } }, "404": { "description": "product not found" }, "401": { "description": "unauthorized" } } }, "patch": { "summary": "Update a product", "description": "Updates an existing product by slug.", "tags": [ "Api::V1::M::Product" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug", "example": "premium-content" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "price_cents": { "type": "integer" }, "sku": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "product_type_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string" }, "image_url": { "type": "string" }, "access_duration_seconds": { "type": "integer" }, "metadata": { "type": "object" } }, "required": [ "name", "price_cents" ] } }, "required": [ "product" ] }, "example": { "product": { "name": "Premium Content", "description": "Access to premium content", "price_cents": 5000, "sku": "PREM-001", "resource_type": "digital", "image_url": "https://example.com/image.png" } } } } }, "responses": { "200": { "description": "product updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "product" }, "livemode": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "slug": { "type": "string" }, "sku": { "type": "string", "nullable": true }, "price_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "position": { "type": "integer" }, "resource_type": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "access_duration_seconds": { "type": "integer", "nullable": true }, "product_type_id": { "type": "string", "format": "uuid", "nullable": true }, "merchant_id": { "type": "string", "format": "uuid" }, "api_token_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "formatted_price": { "type": "string" }, "payment_link_url": { "type": "string", "nullable": true, "format": "uri", "description": "The product's payment link (/pay/:slug): a URL to send a customer that opens the hosted checkout at this price. Null while the product is not active." }, "metadata": { "type": "object" } }, "required": [ "id", "name", "slug", "price_cents", "status", "merchant_id", "created_at", "updated_at" ] } } } }, "404": { "description": "product not found" }, "422": { "description": "validation errors" }, "401": { "description": "unauthorized" } } }, "delete": { "summary": "Archive a product", "description": "Soft-deletes (archives) a product by slug. The product is not permanently removed.", "tags": [ "Api::V1::M::Product" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug", "example": "premium-content" } ], "responses": { "204": { "description": "product archived successfully" }, "404": { "description": "product not found" }, "401": { "description": "unauthorized" } } } }, "/api/v1/m/access/verify": { "post": { "summary": "verify", "tags": [ "Api::V1::M::Access" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "media_key_id": { "type": "string" } }, "required": [ "access_token" ] }, "example": { "access_token": "eyJfcmFpbHMiOnsiZGF0YSI6eyJvcmRlcl9pZCI6IjIxNGQ1YmU4LTA1ZDktNGJiNC04MjRmLWE0NmJhZTg0NDY0YyIsInByb2R1Y3RfaWQiOiI1ZmU3NjIzZi1mMzVkLTQ1MzktOWViZC1lNjUxMGUwZjMxMTUiLCJtZXJjaGFudF9pZCI6Ijk0Y2EzNDJhLTA2ODAtNGM0NS1iZjI5LTc1ZDU2MzRhMDBjMyIsImV4cCI6MTc5MDcwNzg3N30sImV4cCI6IjIwMjYtMDktMjlUMTg6NTE6MTcuOTc5WiIsInB1ciI6ImFjY2Vzc190b2tlbiJ9fQ--26622505cab02bb993c21b1af075be31c8ca75ff77574d77543a8bc6c0b6fb06", "media_key_id": "86471e94-02b3-4596-8b5a-fefddab8460a" } } } }, "responses": { "200": { "description": "releases a linked media key when media_key_id is named (without it, no key is returned)", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "remaining_seconds": { "type": "integer" }, "server_time": { "type": "integer" }, "expires_at": { "type": "integer" }, "product_id": { "type": "string" }, "order_id": { "type": "string" }, "media_key_id": { "type": "string" }, "key": { "type": "string" }, "key_fingerprint": { "type": "string" } }, "required": [ "valid", "remaining_seconds", "server_time", "expires_at", "product_id", "order_id" ] }, "example": { "valid": true, "remaining_seconds": 86399, "server_time": 1790621477, "expires_at": 1790707876, "product_id": "5fe7623f-f35d-4539-9ebd-e6510e0f3115", "order_id": "214d5be8-05d9-4bb4-824f-a46bae84464c", "media_key_id": "86471e94-02b3-4596-8b5a-fefddab8460a", "key": "EXAMPLEonly-media-key-base64url-32-bytes", "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136" } } } }, "402": { "description": "refuses media keys to a v1 token, which names no product", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" } }, "required": [ "code", "message", "status" ] } }, "required": [ "valid", "error" ] }, "example": { "valid": false, "error": { "code": "key_not_granted", "message": "This payment does not unlock the requested media key.", "status": 402 } } } } } } } }, "/api/v1/m/media_keys": { "get": { "summary": "index", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "responses": { "200": { "description": "lists media keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_page": { "type": "null" }, "prev_page": { "type": "null" } }, "required": [ "current_page", "per_page", "total_count", "total_pages", "next_page", "prev_page" ] } }, "required": [ "object", "data", "meta" ] }, "example": { "object": "list", "data": [ { "object": "media_key", "livemode": true, "id": "9849fec0-44ae-40ac-99ba-293bb1ee7cff", "merchant_id": "95d63ac6-1625-4105-9dad-dafe5b12a9ce", "name": "Video key", "key_fingerprint": "2736be3e2cff047837483b34d47efe4ff8811da318b56856fab2a5be8c048beb", "rotation_pending": false, "browser_delivery": false, "product_ids": [ "01109d09-a655-457a-ad78-37d62166ee9d" ], "metadata": {}, "created_at": "2026-09-28T21:18:58.454Z", "updated_at": "2026-09-28T21:18:58.454Z" } ], "meta": { "current_page": 1, "per_page": 25, "total_count": 1, "total_pages": 1, "next_page": null, "prev_page": null } } } } }, "403": { "description": "refuses keys that bridge an OAuth-connected assistant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "forbidden", "message": "Media keys are not available to OAuth-connected assistants. Use a secret key.", "status": 403, "request_id": "b4004c14-5453-4022-92e0-2f466ff2f86c" } } } } } } }, "post": { "summary": "create", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media_key": { "type": "object", "properties": { "name": { "type": "string" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "media_key": { "name": "Video key", "browser_delivery": true, "product_ids": [ "6f9d703d-09ac-4625-8cd3-3ec856f74fd2", "prod_930cf7085b64ad490e75fe0d" ] } } } } }, "responses": { "201": { "description": "links products by id or slug in the same request", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "9e5e7fe3-e975-416f-b695-56c16241cbd3", "merchant_id": "96c3e316-923e-4e8a-a86b-b16ce0aafa55", "name": null, "key_fingerprint": "aa6453240caa89e1083273f6273e314c919e7fbbae567418e904c3739efe9793", "rotation_pending": false, "browser_delivery": false, "product_ids": [ "2fa6f3b5-a44d-47f4-a41f-1eb520471f0a", "6f9d703d-09ac-4625-8cd3-3ec856f74fd2" ], "metadata": {}, "created_at": "2026-09-28T21:18:52.050Z", "updated_at": "2026-09-28T21:18:52.050Z" } } } }, "404": { "description": "creates nothing when a product is unknown or belongs to another merchant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Products not found: 11750cb2-8e4c-4758-9008-c9a13d67d4f9", "status": 404, "request_id": "0544b0df-9cf4-4b63-80f1-0657e88f04e5" } } } } } } } }, "/api/v1/m/media_keys/{id}": { "delete": { "summary": "destroy", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "5fe33e01-dcf1-485a-8a54-275baeb68180" } ], "responses": { "204": { "description": "destroys a key and its links" } } }, "get": { "summary": "show", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "not-a-uuid" } ], "responses": { "200": { "description": "lists and shows the merchant's keys with their products", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "24da3441-b528-4024-a644-92bb5128e8b5", "merchant_id": "1266078b-ab5d-46b8-bf3c-24b15bdbbe5d", "name": "Video key", "key_fingerprint": "f1e9efc16cb7e202cfd05203c19925ddae2cad821dfb8c03bc941370b755591e", "rotation_pending": false, "browser_delivery": false, "product_ids": [ "8c0b7625-0818-4920-a5df-c8895d606352", "9a092358-d58e-4825-b7be-2508efe536db" ], "metadata": {}, "created_at": "2026-09-28T21:18:53.166Z", "updated_at": "2026-09-28T21:18:53.166Z" } } } }, "404": { "description": "hides other merchants' keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Media key not found", "status": 404, "request_id": "eb9bf8e2-d090-489d-afd2-648422b2aedf" } } } } } } }, "patch": { "summary": "update", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "6f517730-8e25-40b2-b024-723419718568" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media_key": { "type": "object", "properties": { "browser_delivery": { "type": "boolean" }, "key": { "type": "string" } }, "required": [ "browser_delivery" ] } }, "required": [ "media_key" ] }, "example": { "media_key": { "browser_delivery": true, "key": "attacker-key" } } } } }, "responses": { "200": { "description": "updates a media key", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "b1d7b020-17eb-48a4-8f83-1f221e2348d7", "merchant_id": "fb5c4efa-4d5b-488b-8f18-05e51b0029ab", "name": "Video key", "key_fingerprint": "a481a639027046fd752f8c52a1c96fce1cadde7be781ca18bc41ace53022f8e5", "rotation_pending": false, "browser_delivery": true, "product_ids": [], "metadata": {}, "created_at": "2026-09-28T21:18:58.174Z", "updated_at": "2026-09-28T21:18:58.209Z" } } } }, "400": { "description": "hides other merchants' keys and needs a body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "bad_request", "message": "param is missing or the value is empty or invalid: media_key", "status": 400, "request_id": "e0ecce57-d436-4a30-925d-501566e46f18" } } } } }, "403": { "description": "requires manage access for key custody and links", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "forbidden", "message": "Insufficient permissions for this resource", "status": 403, "request_id": "35d1bf24-d261-498b-8b8f-185a16e9ef9e" } } } } } } } }, "/api/v1/m/media_keys/{id}/clear_old_key": { "post": { "summary": "clear_old_key", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "c0d8d917-e602-49cb-b93a-6ee7a3a601f6" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "rotates, keeps the previous key until cleared, and notifies webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": {} }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "c0d8d917-e602-49cb-b93a-6ee7a3a601f6", "merchant_id": "bc850edb-56fb-48db-aece-bb73ad182886", "name": "Video key", "key_fingerprint": "4d04688ea3f056330e55f2714870a4be618fa6f55ef782d318118ee504da93b7", "rotation_pending": false, "browser_delivery": false, "product_ids": [], "metadata": {}, "created_at": "2026-09-28T21:18:54.607Z", "updated_at": "2026-09-28T21:18:54.683Z" } } } } } } }, "/api/v1/m/media_keys/{id}/key": { "get": { "summary": "key", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer pk_live_YOUR_PUBLISHABLE_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1d266228-5d2b-484e-9369-db7f749cd313" } ], "responses": { "200": { "description": "returns key material only from the key endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "key_fingerprint": { "type": "string" }, "previous_key": { "type": "null" }, "previous_key_fingerprint": { "type": "null" } }, "required": [ "object", "id", "key", "key_fingerprint", "previous_key", "previous_key_fingerprint" ] }, "example": { "object": "media_key_secret", "id": "46db8bcc-10ac-47fa-98c4-d84e2a6a4aa1", "key": "EXAMPLEonly-media-key-base64url-32-bytes", "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136", "previous_key": null, "previous_key_fingerprint": null } } } }, "403": { "description": "refuses publishable keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "forbidden", "message": "Publishable keys can only access checkout session creation. Use a secret key for full API access.", "status": 403, "request_id": "9a29a0d0-ad1a-4174-bae5-08ccb954ef2f" } } } } } } } }, "/api/v1/m/media_keys/{id}/products": { "post": { "summary": "link_products", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "45ad786b-530f-424a-9ccd-3f965fd9f11f" } ], "responses": { "200": { "description": "links products to a media key", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "45ad786b-530f-424a-9ccd-3f965fd9f11f", "merchant_id": "93492e20-9ec7-4a07-a85f-f190b8a34dc6", "name": "Video key", "key_fingerprint": "bfcd0c3f43088f9ac2a69832fda5be910f5025efde7ba145dc7a78dafee4d217", "rotation_pending": false, "browser_delivery": false, "product_ids": [ "c21a8a3b-12b3-414f-b9ec-5672875d187c", "f5cce0f2-3195-4cb7-aada-771599180186" ], "metadata": {}, "created_at": "2026-09-28T21:18:59.049Z", "updated_at": "2026-09-28T21:18:59.049Z" } } } }, "400": { "description": "requires a bounded list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "invalid_request", "message": "product_ids must be a list of 1 to 100 identifiers", "status": 400, "request_id": "114beb0a-e9f2-4ba6-8b46-16f8385f2811" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "product_ids" ] }, "example": { "product_ids": [ "c21a8a3b-12b3-414f-b9ec-5672875d187c", "f5cce0f2-3195-4cb7-aada-771599180186" ] } } } } } }, "/api/v1/m/media_keys/{id}/products/{product_id}": { "delete": { "summary": "unlink_product", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "e06f85b8-9462-429c-b046-34b1d912f932" }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "589a3798-7e6d-49ff-b96d-5c6e932a7fa2" } ], "responses": { "200": { "description": "links from the key side and unlinks one product", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "livemode": { "type": "boolean" }, "id": { "type": "string" }, "merchant_id": { "type": "string" }, "name": { "type": "string" }, "key_fingerprint": { "type": "string" }, "rotation_pending": { "type": "boolean" }, "browser_delivery": { "type": "boolean" }, "product_ids": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "properties": {} }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "livemode", "id", "merchant_id", "name", "key_fingerprint", "rotation_pending", "browser_delivery", "product_ids", "metadata", "created_at", "updated_at" ] }, "example": { "object": "media_key", "livemode": true, "id": "e06f85b8-9462-429c-b046-34b1d912f932", "merchant_id": "2dc5660c-ee8d-4199-8062-0c36c2aa7253", "name": "Video key", "key_fingerprint": "554779381f4352fca9c28017544444c9938c988074365054679366126288dd96", "rotation_pending": false, "browser_delivery": false, "product_ids": [ "265b3db6-8157-4e0d-b4f4-71020b616b74" ], "metadata": {}, "created_at": "2026-09-28T21:18:55.184Z", "updated_at": "2026-09-28T21:18:55.184Z" } } } } } } }, "/api/v1/m/media_keys/{id}/rotate": { "post": { "summary": "rotate", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "a28a806e-1927-43ad-a316-b3cd70e8c00f" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "rotates a media key", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "key_fingerprint": { "type": "string" }, "previous_key": { "type": "string" }, "previous_key_fingerprint": { "type": "string" } }, "required": [ "object", "id", "key", "key_fingerprint", "previous_key", "previous_key_fingerprint" ] }, "example": { "object": "media_key_secret", "id": "a28a806e-1927-43ad-a316-b3cd70e8c00f", "key": "EXAMPLEonly-media-key-base64url-32-bytes", "key_fingerprint": "db5a28ed53da2b953bdc39f08b362317ca358042a6cc5bb4d507a59bbbc3e136", "previous_key": "EXAMPLEonly-previous-key-base64url-32-bytes", "previous_key_fingerprint": "8bc62288bb5e4910fbbd3560fbb75dcd09bc9fb9e39bf29c2dc8ab16c1603ee8" } } } } } } }, "/api/v1/m/products/{product_id}/media_keys": { "post": { "summary": "link_to_product", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2109dc69-ea0c-4f00-8b8d-6f4430f539fd" } ], "responses": { "200": { "description": "links media keys to a product", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "product_id": { "type": "string" }, "media_key_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "product_id", "media_key_ids" ] }, "example": { "object": "media_key_links", "product_id": "2109dc69-ea0c-4f00-8b8d-6f4430f539fd", "media_key_ids": [ "a1d3271a-e83a-4885-80b6-cfd4ac4767b0" ] } } } }, "404": { "description": "links nothing when any referenced key or product is not the merchant's", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "status", "request_id" ] } }, "required": [ "error" ] }, "example": { "error": { "code": "not_found", "message": "Product not found", "status": 404, "request_id": "fdfc34a6-7ecf-4543-a48b-6589bb726e23" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "media_key_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "media_key_ids" ] }, "example": { "media_key_ids": [ "a1d3271a-e83a-4885-80b6-cfd4ac4767b0" ] } } } } } }, "/api/v1/m/products/{product_id}/media_keys/{id}": { "delete": { "summary": "unlink_from_product", "tags": [ "Api::V1::M::MediaKey" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_live_YOUR_SECRET_KEY" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "067f1da0-3050-4863-9377-2e0036c5bfc4" }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "prod_72b688d24adb3768fc373240" } ], "responses": { "200": { "description": "links one product to many keys from the product side", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "product_id": { "type": "string" }, "media_key_ids": { "type": "array", "items": {} } }, "required": [ "object", "product_id", "media_key_ids" ] }, "example": { "object": "media_key_links", "product_id": "42d59560-0bba-49f2-96c1-1caac37a60de", "media_key_ids": [] } } } } } } }, "/api/v1/m/api_tokens/{id}/usage": { "get": { "summary": "Get API token usage", "description": "Returns usage statistics and rate limit configuration for a specific API token. Only active tokens owned by the authenticated merchant are accessible.", "tags": [ "Api::V1::M::ApiToken" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "example": "Bearer sk_test_..." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "API token UUID" } ], "responses": { "200": { "description": "returns token usage data", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "token_type": { "type": "string", "enum": [ "secret", "publishable" ] }, "rpm_limit": { "type": "integer", "description": "Effective requests-per-minute limit (per-token override or plan default)" }, "monthly_request_count": { "type": "integer", "description": "Number of requests made this billing period" }, "last_request_counted_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "token_type", "rpm_limit", "monthly_request_count", "created_at" ] } } } }, "404": { "description": "token not found or not owned by merchant" }, "401": { "description": "unauthorized" } } } } }, "components": { "securitySchemes": { "merchant_api_key": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_* / sk_test_*", "description": "Merchant secret API key" }, "public_embed_key": { "type": "http", "scheme": "bearer", "bearerFormat": "pk_live_*", "description": "Publishable embed key for client-side integrations" } } } }