{ "openapi": "3.1.0", "info": { "title": "NectarPay API", "version": "1.0.0", "description": "Non-custodial crypto payment API. Create invoices, track payment status, manage payment links and receive signed webhooks. Funds always settle directly to the merchant's own wallet \u2014 API keys can never move money.", "contact": { "name": "NectarPay support", "url": "https://app.nectar-pay.com/help" }, "termsOfService": "https://app.nectar-pay.com/terms" }, "servers": [ { "url": "https://app.nectar-pay.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Per-store secret key, format sk_live_\u2026 Create one at Stores \u2192 your store \u2192 API keys." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests (120 per minute per key). See Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable message." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "rate_limited", "server_error", "upstream_error", "unavailable" ] }, "retry_after_seconds": { "type": "integer" } } }, "Chain": { "type": "string", "enum": [ "btc", "lightning", "txc", "eth", "base", "tron", "sol", "doge", "ltc", "bch", "dash", "isk", "zcu" ] }, "InvoiceStatus": { "type": "string", "enum": [ "pending", "underpaid", "overpaid", "confirmed", "expired" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "chain": { "$ref": "#/components/schemas/Chain" }, "address": { "type": "string" }, "crypto_amount": { "type": "string" }, "rate": { "type": "number" }, "order_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "checkout_url": { "type": "string", "format": "uri" } } }, "CreateInvoice": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Fiat amount." }, "currency": { "type": "string", "default": "USD" }, "chain": { "$ref": "#/components/schemas/Chain" }, "order_id": { "type": "string" }, "description": { "type": "string" }, "redirect_url": { "type": "string", "format": "uri" }, "buyer_email": { "type": "string", "format": "email" }, "expires_in_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 } } }, "PaymentLink": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "cta_label": { "type": "string" }, "currency": { "type": "string" }, "preset_amounts": { "type": "array", "items": { "type": "number" } }, "allow_custom_amount": { "type": "boolean" }, "min_amount": { "type": "number" }, "max_amount": { "type": "number" }, "is_donation": { "type": "boolean" }, "active": { "type": "boolean" } } } }, "parameters": { "InvoiceId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } } }, "paths": { "/api/public/v1/me": { "get": { "operationId": "getMe", "summary": "Verify a key; returns store, key mode and webhook URL.", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/api/public/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated" }, { "name": "order_id", "in": "query", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createInvoice", "summary": "Create an invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoice" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/public/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Invoice status", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "redeliverWebhook", "summary": "Resend the webhook (?action=redeliver-webhook)", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "redeliver-webhook" ] } } ], "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/api/public/v1/invoices/{id}/email": { "post": { "operationId": "emailInvoice", "summary": "Email the payment request to the customer", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Queued" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/api/public/v1/invoices/{id}/webhooks": { "get": { "operationId": "listInvoiceWebhooks", "summary": "Webhook delivery history", "parameters": [ { "$ref": "#/components/parameters/InvoiceId" } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/rates": { "get": { "operationId": "getRates", "summary": "Live USD rates per chain", "parameters": [ { "name": "amount", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/store": { "get": { "operationId": "getStore", "summary": "Store profile, enabled chains and payment links", "responses": { "200": { "description": "OK" } } } }, "/api/public/v1/links": { "get": { "operationId": "listLinks", "summary": "List payment links", "responses": { "200": { "description": "OK" } } }, "post": { "operationId": "createLink", "summary": "Create a payment link", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "responses": { "200": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/api/public/v1/links/{slug}": { "get": { "operationId": "getLink", "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateLink", "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "operationId": "deleteLink", "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "Deleted" } } } } }, "webhooks": { "invoiceEvent": { "post": { "summary": "Signed invoice event. Settle orders on invoice.confirmed (final; sent after invoice.paid or invoice.overpaid).", "description": "Header X-TXCPay-Signature: t=,v1= where v1 = HMAC_SHA256(webhook_secret, \"{t}.{rawBody}\"). Reject if t is older than 5 minutes.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "invoice.paid", "invoice.overpaid", "invoice.confirmed", "invoice.underpaid" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "store_id": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "overpaid", "underpaid" ] }, "chain": { "type": "string" }, "address": { "type": "string" }, "fiat_amount": { "type": "number" }, "fiat_currency": { "type": "string" }, "paid_amount_usd": { "type": "number" }, "order_id": { "type": [ "string", "null" ] } } } } }, "example": { "id": "3b8f2a61-9d4e-4c1a-8f0b-2e7d5c9a1f44", "type": "invoice.confirmed", "created_at": "2026-10-03T09:22:11.482Z", "data": { "invoice_id": "7c9e6f1a-2b3d-4e5f-8a9b-0c1d2e3f4a5b", "store_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "status": "confirmed", "chain": "txc", "address": "TXc9yQ...", "fiat_amount": 49.0, "fiat_currency": "USD", "paid_amount_usd": 49.0, "order_id": "ORDER_1234" } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx" } } } } } }