{"openapi":"3.1.0","info":{"title":"MG Crypto Payments API","version":"1.0.0","description":"Accept real Bitcoin payments. Create invoices and payment links, and read balances and settled payments.","contact":{"name":"MG Crypto Support","email":"support@markgroup.app","url":"https://markgroup.app/docs"}},"servers":[{"url":"https://markgroup.app/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Balance","description":"Read your settled and pending Bitcoin balance."},{"name":"Invoices","description":"Create one-time payment requests and read their status."},{"name":"Payment Links","description":"Create reusable, shareable checkout links."},{"name":"Payments","description":"Read confirmed on-chain payments you have received."}],"paths":{"/balance":{"get":{"operationId":"get-balance","summary":"Retrieve balance","description":"Returns your withdrawable (`confirmed_sats`) and total (`total_sats`) balance for the settlement asset, with a best-effort USD valuation.","tags":["Balance"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"balance","asset":"BTC","confirmed_sats":1532099,"total_sats":1664198,"confirmed_usd":1159.42}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"post":{"operationId":"create-invoice","summary":"Create an invoice","description":"Creates an invoice for a USD amount, converted to satoshis at the live BTC rate. A dedicated on-chain deposit address is minted for the invoice. If the live price is unavailable the request fails with `price_unavailable` rather than guessing a rate.","tags":["Invoices"],"security":[{"bearerAuth":[]}],"x-scope":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key so retries never create a duplicate resource.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"example":{"object":"invoice","id":"inv_3n8Kd0Qz","status":"open","asset":"BTC","amount_sats":132099,"amount_usd_quote":100,"description":"Order #1001","customer_email":"buyer@example.com","deposit_address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","tx_hash":null,"payment_link_id":null,"pay_url":"https://markgroup.app/pay/inv_3n8Kd0Qz","expires_at":"2026-09-17T18:00:00.000Z","paid_at":null,"created_at":"2026-09-16T18:00:00.000Z"}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_usd":{"type":"number","description":"Amount to charge in USD."},"description":{"type":"string","description":"Memo shown on the invoice and hosted checkout."},"customer_email":{"type":"string","description":"Customer email to associate with the invoice."},"expires_in_hours":{"type":"number","description":"Hours until the invoice expires. Omit for no expiry."}},"required":["amount_usd"]},"example":{"amount_usd":100,"description":"Order #1001","customer_email":"buyer@example.com","expires_in_hours":24}}}}},"get":{"operationId":"list-invoices","summary":"List invoices","description":"Returns a list of invoices belonging to the authenticated merchant, optionally filtered by status.","tags":["Invoices"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return, newest first.","schema":{"type":"integer","description":"Maximum number of items to return, newest first."}},{"name":"status","in":"query","required":false,"description":"Filter by lifecycle status.","schema":{"type":"string","enum":["open","paid","expired","canceled"],"description":"Filter by lifecycle status."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"list","data":[{"object":"invoice","id":"inv_3n8Kd0Qz","status":"open","asset":"BTC","amount_sats":132099,"amount_usd_quote":100,"description":"Order #1001","customer_email":"buyer@example.com","deposit_address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","tx_hash":null,"payment_link_id":null,"pay_url":"https://markgroup.app/pay/inv_3n8Kd0Qz","expires_at":"2026-09-17T18:00:00.000Z","paid_at":null,"created_at":"2026-09-16T18:00:00.000Z"}]}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}":{"get":{"operationId":"get-invoice","summary":"Retrieve an invoice","description":"Returns the invoice with the given id. Poll this endpoint to watch for `status` moving to `paid`.","tags":["Invoices"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"The invoice id.","schema":{"type":"string","description":"The invoice id."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"invoice","id":"inv_3n8Kd0Qz","status":"open","asset":"BTC","amount_sats":132099,"amount_usd_quote":100,"description":"Order #1001","customer_email":"buyer@example.com","deposit_address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","tx_hash":null,"payment_link_id":null,"pay_url":"https://markgroup.app/pay/inv_3n8Kd0Qz","expires_at":"2026-09-17T18:00:00.000Z","paid_at":null,"created_at":"2026-09-16T18:00:00.000Z"}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links":{"post":{"operationId":"create-payment-link","summary":"Create a payment link","description":"Creates a shareable checkout link. Use `fixed` mode with `amount_usd` for a set price, or `flexible` mode with optional `min_amount_usd`/`max_amount_usd` to let the payer choose. Each payment against the link generates its own invoice and address.","tags":["Payment Links"],"security":[{"bearerAuth":[]}],"x-scope":"write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key so retries never create a duplicate resource.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"example":{"object":"payment_link","id":"lnk_7Qp2Za9","status":"active","title":"Pro plan","description":"Monthly Pro subscription","amount_mode":"fixed","amount_usd":100,"min_amount_usd":null,"max_amount_usd":null,"asset":"BTC","link_url":"https://markgroup.app/link/lnk_7Qp2Za9","created_at":"2026-09-16T18:00:00.000Z"}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_mode":{"type":"string","enum":["fixed","flexible"],"description":"Pricing mode."},"amount_usd":{"type":"number","description":"Fixed price in USD. Required when `amount_mode` is `fixed`."},"min_amount_usd":{"type":"number","description":"Minimum amount (flexible mode)."},"max_amount_usd":{"type":"number","description":"Maximum amount (flexible mode)."},"title":{"type":"string","description":"Display title on checkout."},"description":{"type":"string","description":"Description shown on checkout."}}},"example":{"amount_mode":"fixed","amount_usd":100,"title":"Pro plan","description":"Monthly Pro subscription"}}}}},"get":{"operationId":"list-payment-links","summary":"List payment links","description":"Returns a list of payment links belonging to the authenticated merchant.","tags":["Payment Links"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return, newest first.","schema":{"type":"integer","description":"Maximum number of items to return, newest first."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"list","data":[{"object":"payment_link","id":"lnk_7Qp2Za9","status":"active","title":"Pro plan","description":"Monthly Pro subscription","amount_mode":"fixed","amount_usd":100,"min_amount_usd":null,"max_amount_usd":null,"asset":"BTC","link_url":"https://markgroup.app/link/lnk_7Qp2Za9","created_at":"2026-09-16T18:00:00.000Z"}]}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links/{id}":{"get":{"operationId":"get-payment-link","summary":"Retrieve a payment link","description":"Returns the payment link with the given id.","tags":["Payment Links"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[{"name":"id","in":"path","required":true,"description":"The payment link id.","schema":{"type":"string","description":"The payment link id."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"payment_link","id":"lnk_7Qp2Za9","status":"active","title":"Pro plan","description":"Monthly Pro subscription","amount_mode":"fixed","amount_usd":100,"min_amount_usd":null,"max_amount_usd":null,"asset":"BTC","link_url":"https://markgroup.app/link/lnk_7Qp2Za9","created_at":"2026-09-16T18:00:00.000Z"}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments":{"get":{"operationId":"list-payments","summary":"List payments","description":"Returns confirmed on-chain payments received by the merchant, optionally filtered to a single invoice.","tags":["Payments"],"security":[{"bearerAuth":[]}],"x-scope":"read","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return, newest first.","schema":{"type":"integer","description":"Maximum number of items to return, newest first."}},{"name":"invoice_id","in":"query","required":false,"description":"Return only payments that settled this invoice.","schema":{"type":"string","description":"Return only payments that settled this invoice."}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"object":"list","data":[{"object":"payment","id":"pay_5Rt9Bc2","invoice_id":"inv_3n8Kd0Qz","asset":"BTC","amount_sats":132099,"amount_usd_at_receipt":99.87,"tx_hash":"9f2c1a7e5b3d8c4f6a0e2d1b7c9f4a3e8d6b2c1f0a9e7d5c3b1f8a6e4d2c0b9a","created_at":"2026-09-16T18:14:22.000Z"}]}}}},"4XX":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your secret API key, sent as `Authorization: Bearer sk_live_...`."}},"schemas":{"invoice":{"type":"object","description":"A one-time request for a specific amount of Bitcoin. Creating an invoice mints a dedicated on-chain deposit address; the invoice settles when a matching payment confirms.","properties":{"object":{"type":"string","description":"Always `\"invoice\"`."},"id":{"type":"string","description":"Unique identifier for the invoice."},"status":{"type":"string","enum":["open","paid","expired","canceled"],"description":"Lifecycle state."},"asset":{"type":"string","description":"Settlement asset. Currently always `BTC`."},"amount_sats":{"type":"integer","description":"Amount due, in satoshis."},"amount_usd_quote":{"type":["number","null"],"description":"USD value quoted at creation. `null` if the price was unavailable."},"description":{"type":["string","null"],"description":"Optional memo you supplied."},"customer_email":{"type":["string","null"],"description":"Optional customer email you supplied."},"deposit_address":{"type":["string","null"],"description":"On-chain BTC address to pay. `null` for a brief moment right after creation while the address is minted."},"tx_hash":{"type":["string","null"],"description":"On-chain transaction hash once paid."},"payment_link_id":{"type":["string","null"],"description":"The payment link that generated this invoice, if any."},"pay_url":{"type":"string","description":"Hosted checkout page you can redirect customers to."},"expires_at":{"type":["string","null"],"description":"ISO 8601 expiry timestamp, if set."},"paid_at":{"type":["string","null"],"description":"ISO 8601 timestamp the invoice was paid."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp."}},"example":{"object":"invoice","id":"inv_3n8Kd0Qz","status":"open","asset":"BTC","amount_sats":132099,"amount_usd_quote":100,"description":"Order #1001","customer_email":"buyer@example.com","deposit_address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","tx_hash":null,"payment_link_id":null,"pay_url":"https://markgroup.app/pay/inv_3n8Kd0Qz","expires_at":"2026-09-17T18:00:00.000Z","paid_at":null,"created_at":"2026-09-16T18:00:00.000Z"}},"payment_link":{"type":"object","description":"A reusable, shareable checkout URL. Each visitor who pays a link gets their own invoice and address. Links can charge a fixed price or let the customer choose the amount.","properties":{"object":{"type":"string","description":"Always `\"payment_link\"`."},"id":{"type":"string","description":"Unique identifier for the link."},"status":{"type":"string","description":"Lifecycle state of the link (e.g. `active`)."},"title":{"type":["string","null"],"description":"Optional display title."},"description":{"type":["string","null"],"description":"Optional description shown on checkout."},"amount_mode":{"type":"string","enum":["fixed","flexible"],"description":"Whether the amount is fixed or chosen by the payer."},"amount_usd":{"type":["number","null"],"description":"Fixed price in USD (fixed mode only)."},"min_amount_usd":{"type":["number","null"],"description":"Minimum USD amount (flexible mode only)."},"max_amount_usd":{"type":["number","null"],"description":"Maximum USD amount (flexible mode only)."},"asset":{"type":"string","description":"Settlement asset. Currently always `BTC`."},"link_url":{"type":"string","description":"Public checkout URL to share."},"created_at":{"type":"string","description":"ISO 8601 creation timestamp."}},"example":{"object":"payment_link","id":"lnk_7Qp2Za9","status":"active","title":"Pro plan","description":"Monthly Pro subscription","amount_mode":"fixed","amount_usd":100,"min_amount_usd":null,"max_amount_usd":null,"asset":"BTC","link_url":"https://markgroup.app/link/lnk_7Qp2Za9","created_at":"2026-09-16T18:00:00.000Z"}},"payment":{"type":"object","description":"A confirmed on-chain payment received by your account, usually tied to the invoice it settled.","properties":{"object":{"type":"string","description":"Always `\"payment\"`."},"id":{"type":"string","description":"Unique identifier for the payment."},"invoice_id":{"type":["string","null"],"description":"The invoice this payment settled, if any."},"asset":{"type":"string","description":"Asset received. Currently always `BTC`."},"amount_sats":{"type":"integer","description":"Amount received, in satoshis."},"amount_usd_at_receipt":{"type":["number","null"],"description":"USD value at the time of receipt. `null` if unavailable."},"tx_hash":{"type":["string","null"],"description":"On-chain transaction hash."},"created_at":{"type":"string","description":"ISO 8601 timestamp the payment confirmed."}},"example":{"object":"payment","id":"pay_5Rt9Bc2","invoice_id":"inv_3n8Kd0Qz","asset":"BTC","amount_sats":132099,"amount_usd_at_receipt":99.87,"tx_hash":"9f2c1a7e5b3d8c4f6a0e2d1b7c9f4a3e8d6b2c1f0a9e7d5c3b1f8a6e4d2c0b9a","created_at":"2026-09-16T18:14:22.000Z"}},"balance":{"type":"object","description":"Your settled and pending Bitcoin balance.","properties":{"object":{"type":"string","description":"Always `\"balance\"`."},"asset":{"type":"string","description":"Balance asset. Currently always `BTC`."},"confirmed_sats":{"type":"integer","description":"Withdrawable, fully-confirmed balance in satoshis."},"total_sats":{"type":"integer","description":"Confirmed balance plus unconfirmed incoming credits, in satoshis."},"confirmed_usd":{"type":["number","null"],"description":"USD value of the confirmed balance. `null` if the live price is unavailable."}},"example":{"object":"balance","asset":"BTC","confirmed_sats":1532099,"total_sats":1664198,"confirmed_usd":1159.42}},"Error":{"type":"object","description":"Standard error envelope returned for every 4xx/5xx response.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","not_found","conflict","payload_too_large","rate_limited","price_unavailable","server_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}