{"openapi":"3.1.0","info":{"title":"Stablora API","version":"1.0.0-sandbox","description":"Crypto payments, user wallets, payouts and webhooks. Sandbox/testnet stage: no real funds."},"servers":[{"url":"https://localhost:3000/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Secret API key qk_test_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}},"paths":{"/payments":{"post":{"operationId":"create-payment","summary":"Create a payment","description":"Creates an invoice with its own deposit address. With `currency: \"USD\"` the coin amount is calculated from the live market price and locked for the life of the invoice — later price moves never change what the customer owes.","tags":["Payments"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference","amount","network","asset"],"properties":{"reference":{"type":"string","description":"Your unique order id (max 120). Repeating it returns the same invoice."},"amount":{"type":"string","description":"Fiat amount when `currency` is set (USD, EUR or GBP), otherwise the amount in the asset."},"currency":{"type":"string","description":"Price the invoice in fiat; the coin amount is locked at the current rate. Omit to charge a fixed crypto amount."},"network":{"type":"string","description":"Network id, e.g. `tron`, `ethereum`, `solana`, `sepolia`. See Networks & assets."},"asset":{"type":"string","description":"Asset on that network, e.g. `USDT`."},"description":{"type":"string","description":"Shown on the checkout page (max 200)."},"customerId":{"type":"string","description":"Attach the invoice to a customer (`cus_…`)."},"expirationMinutes":{"type":"integer","description":"5–1440, default 60. Funds after expiry are still credited as `late`."}}},"example":{"reference":"order-1042","amount":"49.90","currency":"USD","network":"tron","asset":"USDT","description":"Order #1042"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pay_c18df35f8fe0c08ccd846672","merchant_id":"mch_4e425c9f49d92545a65c80ce","reference":"order-1042","description":"Order #1042","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","received_units":"0","fee_bps":50,"status":"pending","created_at":"2026-09-24T11:03:41.697Z","expires_at":"2026-09-24T12:03:41.697Z","expiresAt":"2026-09-24T12:03:41.697Z","paid_at":null,"underpaid_tolerance_bps":0,"fee_payer":"merchant","base_amount_units":"49911414","amount":"49.911414","received":"0","baseAmount":"49.911414","feePayer":"merchant","underpaidTolerancePercent":0,"paymentUrl":"/pay/pay_c18df35f8fe0c08ccd846672","depositAddress":"qtest_tron_3e5f8507d9ffc1d52aaf921d1a8c3f155cd5fc54","refunded":"0","mode":"sandbox","pricing":{"currency":"USD","usdAmount":"49.9","priceUsd":"0.999771324867","priceUpdatedAt":"2026-09-24T11:02:10.000Z","quotedAt":"2026-09-24T11:03:41.693Z","lockedUntil":"2026-09-24T12:03:41.697Z","locked":true,"source":"CoinGecko"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-payments","summary":"List payments","description":"Invoices, newest first.","tags":["Payments"],"x-stablora-permission":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Filter by status."}},{"name":"customerId","in":"query","required":false,"schema":{"type":"string","description":"Only this customer."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"`nextCursor` from the previous page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"pay_c18df35f8fe0c08ccd846672","merchant_id":"mch_4e425c9f49d92545a65c80ce","reference":"order-1042","description":"Order #1042","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","received_units":"49911414","fee_bps":50,"status":"completed","created_at":"2026-09-24T11:03:41.697Z","expires_at":"2026-09-24T12:03:41.697Z","expiresAt":"2026-09-24T12:03:41.697Z","paid_at":"2026-09-24T11:03:41.744Z","underpaid_tolerance_bps":0,"fee_payer":"merchant","base_amount_units":"49911414","amount":"49.911414","received":"49.911414","baseAmount":"49.911414","feePayer":"merchant","underpaidTolerancePercent":0,"paymentUrl":"/pay/pay_c18df35f8fe0c08ccd846672","depositAddress":"qtest_tron_3e5f8507d9ffc1d52aaf921d1a8c3f155cd5fc54","refunded":"0","mode":"sandbox","pricing":{"currency":"USD","usdAmount":"49.9","priceUsd":"0.999771324867","priceUpdatedAt":"2026-09-24T11:02:10.000Z","quotedAt":"2026-09-24T11:03:41.693Z","lockedUntil":"2026-09-24T12:03:41.697Z","locked":true,"source":"CoinGecko"}}],"nextCursor":"MjAyNi0wOS0yNFQxMTowMzo0MS43MTdafHBheV8xNjVj…"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}":{"get":{"operationId":"retrieve-payment","summary":"Retrieve a payment","description":"The authoritative state of an invoice. Re-read it after a webhook before fulfilling.","tags":["Payments"],"x-stablora-permission":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payment id `pay_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pay_c18df35f8fe0c08ccd846672","merchant_id":"mch_4e425c9f49d92545a65c80ce","reference":"order-1042","description":"Order #1042","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","received_units":"49911414","fee_bps":50,"status":"completed","created_at":"2026-09-24T11:03:41.697Z","expires_at":"2026-09-24T12:03:41.697Z","expiresAt":"2026-09-24T12:03:41.697Z","paid_at":"2026-09-24T11:03:41.744Z","underpaid_tolerance_bps":0,"fee_payer":"merchant","base_amount_units":"49911414","amount":"49.911414","received":"49.911414","baseAmount":"49.911414","feePayer":"merchant","underpaidTolerancePercent":0,"paymentUrl":"/pay/pay_c18df35f8fe0c08ccd846672","depositAddress":"qtest_tron_3e5f8507d9ffc1d52aaf921d1a8c3f155cd5fc54","refunded":"0","mode":"sandbox","pricing":{"currency":"USD","usdAmount":"49.9","priceUsd":"0.999771324867","priceUpdatedAt":"2026-09-24T11:02:10.000Z","quotedAt":"2026-09-24T11:03:41.693Z","lockedUntil":"2026-09-24T12:03:41.697Z","locked":true,"source":"CoinGecko"}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"post":{"operationId":"create-quote","summary":"Preview a USD quote","description":"Shows how much of an asset a USD amount buys right now, without creating an invoice. Quotes are indicative; the invoice locks its own price at creation.","tags":["Payments"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network","asset","usdAmount"],"properties":{"network":{"type":"string","description":"Network id."},"asset":{"type":"string","description":"Asset."},"usdAmount":{"type":"string","description":"USD amount."}}},"example":{"network":"bitcoin","asset":"BTC","usdAmount":"100"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"network":"bitcoin","asset":"BTC","usdAmount":"100","usdCents":"10000","amount":"0.00119688","amountUnits":"119688","priceUsd":"83551.147838655772","priceUpdatedAt":"2026-09-24T11:02:10.000Z","quotedAt":"2026-09-24T11:03:41.731Z","quoteExpiresAt":"2026-09-24T11:04:41.731Z","source":"CoinGecko"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout-sessions":{"post":{"operationId":"create-checkout-session","summary":"Create a checkout session","description":"A USD order where the customer chooses the coin on the hosted page. When they choose, a normal locked invoice is created for that option. Redirect the customer to `url`.","tags":["Payments"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference","amount"],"properties":{"reference":{"type":"string","description":"Your order id (max 100). Idempotent."},"amount":{"type":"string","description":"Amount in `currency`."},"currency":{"type":"string","description":"Default USD."},"description":{"type":"string","description":"Shown to the customer."},"options":{"type":"array","description":"List of `{ network, asset }` to offer. Default: every coin and network your key may use (a live key: all live options; a test key: all testnets)."},"successUrl":{"type":"string","description":"Where the “Return to store” button leads after payment."},"customerId":{"type":"string","description":"Attach resulting invoices to a customer."},"expirationMinutes":{"type":"integer","description":"5–1440, default 60."}}},"example":{"reference":"cart-5531","amount":"19.99","successUrl":"https://shop.example/thanks","options":[{"network":"tron","asset":"USDT"},{"network":"bitcoin","asset":"BTC"},{"network":"solana","asset":"SOL"}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"cs_cc25b6efa956b4911ea9920a","merchant_name":"Orbit Commerce","brand":{"color":null,"supportEmail":null},"description":"cart-5531","usdAmount":"19.99","options":[{"network":"tron","asset":"USDT","networkName":"TRON","testnet":false},{"network":"bitcoin","asset":"BTC","networkName":"Bitcoin","testnet":false},{"network":"solana","asset":"SOL","networkName":"Solana","testnet":false}],"expires_at":"2026-09-24T12:03:41.800Z","expired":false,"payment":null,"url":"https://localhost:3000/checkout/cs_cc25b6efa956b4911ea9920a"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links":{"post":{"operationId":"create-payment-link","summary":"Create a payment link","description":"A reusable public link (`/l/{slug}`) for donations, social media sales or a fixed-price product. Every visitor gets their own checkout session, invoice and deposit address. Payments carry the reference `link:{slug}:…`.","tags":["Payments"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Shown on the link page (max 100)."},"amount":{"type":"string","description":"Fixed USD price. Omit to let the buyer choose."},"minAmount":{"type":"string","description":"Lowest amount when the buyer chooses (default 1)."},"maxAmount":{"type":"string","description":"Highest amount when the buyer chooses (default 10000, max 1,000,000)."},"description":{"type":"string","description":"Optional text (max 200)."},"options":{"type":"array","description":"Coins to offer, as for checkout sessions."},"successUrl":{"type":"string","description":"Return URL after payment."}}},"example":{"title":"Support the stream","minAmount":"2","maxAmount":"500"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"pl_1e7aac13b02f2ca4635607cf","slug":"xnt1_yKaKiAH","url":"/l/xnt1_yKaKiAH","title":"Support the stream","description":null,"active":true,"amount":null,"minAmount":"2","maxAmount":"500","options":[{"network":"tron","asset":"USDT"},"…"],"successUrl":null,"sessions":0,"paidCount":0,"paidUsd":"0","created_at":"2026-09-24T11:03:41.820Z"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-payment-links","summary":"List payment links","description":"All links with usage statistics: sessions started, paid count and paid USD.","tags":["Payments"],"x-stablora-permission":"read","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"pl_1e7aac13b02f2ca4635607cf","slug":"xnt1_yKaKiAH","url":"/l/xnt1_yKaKiAH","title":"Support the stream","active":true,"amount":null,"minAmount":"2","maxAmount":"500","sessions":14,"paidCount":9,"paidUsd":"212.5"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links/{id}/deactivate":{"post":{"operationId":"deactivate-payment-link","summary":"Deactivate a payment link","description":"Stops the link from accepting new buyers. Invoices already started are not affected.","tags":["Payments"],"x-stablora-permission":"payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Link id `pl_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pl_1e7aac13b02f2ca4635607cf","active":false,"…":"…"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links/{id}/activate":{"post":{"operationId":"activate-payment-link","summary":"Activate a payment link","description":"Turns a deactivated link back on. The URL stays the same.","tags":["Payments"],"x-stablora-permission":"payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Link id `pl_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pl_1e7aac13b02f2ca4635607cf","active":true,"…":"…"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/test/deposits":{"post":{"operationId":"test-deposit","summary":"Simulate a deposit (sandbox)","description":"Simulates an incoming transfer on a sandbox network. Refused on testnets — send real testnet coins there instead.","tags":["Payments"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","transactionHash"],"properties":{"amount":{"type":"string","description":"Amount in the asset."},"asset":{"type":"string","description":"Required for wallets; taken from the invoice otherwise."},"transactionHash":{"type":"string","description":"Unique id such as `sim_order_1042`. Replays are ignored."},"fromAddresses":{"type":"array","description":"Sender addresses, screened against sanctions lists — use a listed address to test `payment.held`."}}},"example":{"paymentId":"pay_c18df35f8fe0c08ccd846672","amount":"49.911414","transactionHash":"sim_order_1042"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"dep_709ecb039bb5d29ece216883","merchant_id":"mch_4e425c9f49d92545a65c80ce","wallet_id":null,"payment_id":"pay_c18df35f8fe0c08ccd846672","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","fee_units":"249558","tx_hash":"sim_order_1042","event_index":0,"created_at":"2026-09-24T11:03:41.744Z","merchant_wallet_id":null,"reversed_at":null,"reversal_reason":null,"amount":"49.911414","fee":"0.249558","net":"49.661856","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/test/deposits/{id}/reverse":{"post":{"operationId":"reverse-deposit","summary":"Simulate a reorg (sandbox)","description":"Undoes a sandbox deposit as if the block had been reorganized away, and sends `payment.reversed` (or `deposit.reversed`). Use it to test your handling.","tags":["Payments"],"x-stablora-permission":"payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Deposit id `dep_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"dep_709ecb039bb5d29ece216883","merchant_id":"mch_4e425c9f49d92545a65c80ce","wallet_id":null,"payment_id":"pay_c18df35f8fe0c08ccd846672","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","fee_units":"249558","tx_hash":"sim_order_1042","event_index":0,"created_at":"2026-09-24T11:03:41.744Z","merchant_wallet_id":null,"reversed_at":"2026-09-24T11:03:41.991Z","reversal_reason":"Simulated chain reorganization (sandbox).","amount":"49.911414","fee":"0.249558","net":"49.661856","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"post":{"operationId":"create-customer","summary":"Create a customer","description":"Idempotent by `externalId`: repeating it returns the existing customer. Different merchants can use the same `externalId` without sharing anything.","tags":["Customers & wallets"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["externalId"],"properties":{"externalId":{"type":"string","description":"Your user id (max 120)."},"name":{"type":"string","description":"Display name (max 100)."}}},"example":{"externalId":"player-8841","name":"Alex Morgan"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"cus_116f187959c5a838e125b339","merchant_id":"mch_4e425c9f49d92545a65c80ce","external_id":"player-8841","name":"Alex Morgan","created_at":"2026-09-24T11:03:41.255Z"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-customers","summary":"List customers","description":"Customers, newest first.","tags":["Customers & wallets"],"x-stablora-permission":"read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Next page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"cus_116f187959c5a838e125b339","merchant_id":"mch_4e425c9f49d92545a65c80ce","external_id":"player-8841","name":"Alex Morgan","created_at":"2026-09-24T11:03:41.255Z"}],"nextCursor":null}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallets":{"post":{"operationId":"assign-wallet","summary":"Assign a wallet","description":"Returns the customer’s permanent address on a network, creating it on first use.","tags":["Customers & wallets"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerId","network"],"properties":{"customerId":{"type":"string","description":"Customer `cus_…`."},"network":{"type":"string","description":"Network id. One address serves every asset on that network."}}},"example":{"customerId":"cus_116f187959c5a838e125b339","network":"tron"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"wal_e3410ad818b1d6e3b45a8637","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","address":"qtest_tron_4295b8b9889b70e74451d4e501739c5b7c330163","created_at":"2026-09-24T11:03:41.270Z"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-wallets","summary":"List wallets","description":"Wallets, optionally for one customer.","tags":["Customers & wallets"],"x-stablora-permission":"read","parameters":[{"name":"customerId","in":"query","required":false,"schema":{"type":"string","description":"Only this customer."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Next page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"wal_e3410ad818b1d6e3b45a8637","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","address":"qtest_tron_4295b8b9889b70e74451d4e501739c5b7c330163","created_at":"2026-09-24T11:03:41.270Z"}],"nextCursor":null}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/balances":{"get":{"operationId":"customer-balances","summary":"Customer balances","description":"A customer’s ledger balances per network and asset (per-customer balance model).","tags":["Customers & wallets"],"x-stablora-permission":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Customer `cus_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"network":"tron","asset":"USDT","decimals":6,"available":"119.4","reserved":"0"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balances":{"get":{"operationId":"balances","summary":"Balances","description":"Your total balances per network and asset. `available` can be paid out; `reserved` is held by pending payouts.","tags":["Balances & payouts"],"x-stablora-permission":"read","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"network":"tron","asset":"USDT","decimals":6,"available":"1809.816856","reserved":"50"},{"network":"bitcoin","asset":"BTC","decimals":8,"available":"0.0412","reserved":"0"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balances/unallocated":{"get":{"operationId":"unallocated-balances","summary":"Unallocated balances","description":"Only the balance that belongs to no customer: the pooled payout pool, top-ups and invoice income. With the per-customer model this is what you can withdraw for yourself.","tags":["Balances & payouts"],"x-stablora-permission":"read","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"network":"tron","asset":"USDT","decimals":6,"available":"1690.416856","reserved":"0"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits":{"get":{"operationId":"list-deposits","summary":"List deposits","description":"Every credited transfer with fee and net amount. `reversed_at` is set if a reorganization undid it.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"customerId","in":"query","required":false,"schema":{"type":"string","description":"Only this customer."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Next page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"dep_709ecb039bb5d29ece216883","merchant_id":"mch_4e425c9f49d92545a65c80ce","wallet_id":null,"payment_id":"pay_c18df35f8fe0c08ccd846672","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"49911414","fee_units":"249558","tx_hash":"sim_order_1042","event_index":0,"created_at":"2026-09-24T11:03:41.744Z","merchant_wallet_id":null,"reversed_at":null,"reversal_reason":null,"amount":"49.911414","fee":"0.249558","net":"49.661856","mode":"sandbox"}],"nextCursor":null}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/topup-wallets":{"post":{"operationId":"topup-wallet","summary":"Get a top-up wallet","description":"Your own deposit address for funding the payout pool on a network (created on first use, then reused). Top-ups carry no processing fee and emit `topup.confirmed`.","tags":["Balances & payouts"],"x-stablora-permission":"payments","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network"],"properties":{"network":{"type":"string","description":"Network id."}}},"example":{"network":"tron"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"mwl_59a8b99deaaebb5dafcf64c7","merchant_id":"mch_4e425c9f49d92545a65c80ce","network":"tron","address":"qtest_tron_9bef0c0f94c136b5dc51f3d492d49bf77c45cfde","created_at":"2026-09-24T11:03:41.928Z"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-topup-wallets","summary":"List top-up wallets","description":"All your top-up addresses.","tags":["Balances & payouts"],"x-stablora-permission":"read","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"mwl_59a8b99deaaebb5dafcf64c7","network":"tron","address":"qtest_tron_9bef0c0f94c136b5dc51f3d492d49bf77c45cfde","created_at":"2026-09-24T11:03:41.928Z"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/quote":{"post":{"operationId":"quote-payout","summary":"Quote a payout","description":"Network fee, withdrawal commission and the net amount the recipient receives. Sends nothing.","tags":["Balances & payouts"],"x-stablora-permission":"read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network","asset","amount"],"properties":{"network":{"type":"string","description":"Network id."},"asset":{"type":"string","description":"Asset."},"amount":{"type":"string","description":"Amount leaving your balance."}}},"example":{"network":"tron","asset":"USDT","amount":"50"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"network":"tron","asset":"USDT","amount":"50","networkFee":"1","withdrawalFee":"0.25","withdrawalFeeBps":50,"net":"48.75","feeLabel":"SANDBOX FIXTURE: 1 USDT network fee","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts":{"post":{"operationId":"create-payout","summary":"Create a payout","description":"Reserves the amount and either sends it (automatic approval) or waits for approval. Always send an `Idempotency-Key` and reuse it when retrying.","tags":["Balances & payouts"],"x-stablora-permission":"payouts","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","description":"Reuse the same key when retrying."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network","asset","amount","address"],"properties":{"network":{"type":"string","description":"Network id."},"asset":{"type":"string","description":"Asset."},"amount":{"type":"string","description":"Amount leaving your balance (the recipient gets `net`)."},"address":{"type":"string","description":"Destination address, validated for the network."},"customerId":{"type":"string","description":"The user being paid. Required for per-customer balances and player-protection rules."}}},"example":{"network":"tron","asset":"USDT","amount":"50","address":"TXYZ…player-wallet","customerId":"cus_116f187959c5a838e125b339"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"out_32310a196885bf86be5926a4","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","asset":"USDT","decimals":6,"amount_units":"50000000","address":"TXYZ…player-wallet","status":"pending_approval","idempotency_key":"withdrawal-8841","created_at":"2026-09-24T11:03:41.867Z","completed_at":null,"tx_hash":null,"network_fee_units":"1000000","withdrawal_fee_units":"250000","net_units":"48750000","usd_cents":"4998","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"payout","payment_id":null,"reason":null,"hold_reason":null,"amount":"50","networkFee":"1","withdrawalFee":"0.25","net":"48.75","usdValue":"49.98","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-payouts","summary":"List payouts","description":"Payouts and refunds, newest first. Poll `status=pending_approval` to build an approval queue.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"e.g. `pending_approval`, `completed`."}},{"name":"customerId","in":"query","required":false,"schema":{"type":"string","description":"Only this player/customer."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Next page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"out_32310a196885bf86be5926a4","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","asset":"USDT","decimals":6,"amount_units":"50000000","address":"TXYZ…player-wallet","status":"pending_approval","idempotency_key":"withdrawal-8841","created_at":"2026-09-24T11:03:41.867Z","completed_at":null,"tx_hash":null,"network_fee_units":"1000000","withdrawal_fee_units":"250000","net_units":"48750000","usd_cents":"4998","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"payout","payment_id":null,"reason":null,"hold_reason":"Player daily limit of 500 USD exceeded","amount":"50","networkFee":"1","withdrawalFee":"0.25","net":"48.75","usdValue":"49.98","mode":"sandbox"}],"nextCursor":null}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}":{"get":{"operationId":"retrieve-payout","summary":"Retrieve a payout","description":"Current status, fees, `hold_reason` and `tx_hash`.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payout `out_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"out_32310a196885bf86be5926a4","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","asset":"USDT","decimals":6,"amount_units":"50000000","address":"TXYZ…player-wallet","status":"completed","idempotency_key":"withdrawal-8841","created_at":"2026-09-24T11:03:41.867Z","completed_at":"2026-09-24T11:05:02.114Z","tx_hash":"sim_payout_out_32310a19","network_fee_units":"1000000","withdrawal_fee_units":"250000","net_units":"48750000","usd_cents":"4998","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"payout","payment_id":null,"reason":null,"hold_reason":null,"amount":"50","networkFee":"1","withdrawalFee":"0.25","net":"48.75","usdValue":"49.98","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}/approve":{"post":{"operationId":"approve-payout","summary":"Approve a payout","description":"Approves a `pending_approval` payout and sends it.","tags":["Balances & payouts"],"x-stablora-permission":"payouts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payout `out_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"out_32310a196885bf86be5926a4","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","asset":"USDT","decimals":6,"amount_units":"50000000","address":"TXYZ…player-wallet","status":"completed","idempotency_key":"withdrawal-8841","created_at":"2026-09-24T11:03:41.867Z","completed_at":null,"tx_hash":"sim_payout_out_32310a19","network_fee_units":"1000000","withdrawal_fee_units":"250000","net_units":"48750000","usd_cents":"4998","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"payout","payment_id":null,"reason":null,"hold_reason":null,"amount":"50","networkFee":"1","withdrawalFee":"0.25","net":"48.75","usdValue":"49.98","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}/cancel":{"post":{"operationId":"cancel-payout","summary":"Cancel a payout","description":"Cancels a payout that has not been sent yet and returns the reserved amount to the balance. Sends `payout.cancelled`.","tags":["Balances & payouts"],"x-stablora-permission":"payouts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payout `out_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"out_32310a196885bf86be5926a4","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":"cus_116f187959c5a838e125b339","network":"tron","asset":"USDT","decimals":6,"amount_units":"50000000","address":"TXYZ…player-wallet","status":"cancelled","idempotency_key":"withdrawal-8841","created_at":"2026-09-24T11:03:41.867Z","completed_at":null,"tx_hash":null,"network_fee_units":"1000000","withdrawal_fee_units":"250000","net_units":"48750000","usd_cents":"4998","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"payout","payment_id":null,"reason":null,"hold_reason":null,"amount":"50","networkFee":"1","withdrawalFee":"0.25","net":"48.75","usdValue":"49.98","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}/refunds":{"post":{"operationId":"create-refund","summary":"Refund a payment","description":"Sends funds received on an invoice back to the customer, in the same asset and network. Refunds carry no withdrawal commission; the network fee is deducted. Several partial refunds are allowed up to the amount received. `GET /payments/{id}/refunds` lists them.","tags":["Balances & payouts"],"x-stablora-permission":"payouts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payment `pay_…`."}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","description":"Reuse the same key when retrying."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","address"],"properties":{"amount":{"type":"string","description":"Amount to refund."},"address":{"type":"string","description":"Customer’s address."},"reason":{"type":"string","description":"Shown in your records (max 200)."}}},"example":{"amount":"10","address":"TCustomer…refund","reason":"Item out of stock"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"id":"out_61de27325974e48bed220dbb","merchant_id":"mch_4e425c9f49d92545a65c80ce","customer_id":null,"network":"tron","asset":"USDT","decimals":6,"amount_units":"10000000","address":"TCustomer…refund","status":"pending_approval","idempotency_key":"refund-1042-1","created_at":"2026-09-24T11:03:41.867Z","completed_at":null,"tx_hash":null,"network_fee_units":"1000000","withdrawal_fee_units":"0","net_units":"9000000","usd_cents":"999","approval":"manual","fee_label":"SANDBOX FIXTURE: 1 USDT network fee","kind":"refund","payment_id":"pay_c18df35f8fe0c08ccd846672","reason":"Item out of stock","hold_reason":null,"amount":"10","networkFee":"1","withdrawalFee":"0","net":"9","usdValue":"9.99","mode":"sandbox"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list-refunds","summary":"List refunds of a payment","description":"Refunds of one invoice plus how much is still refundable.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Payment `pay_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"refundable":"39.911414","refunded":"10","data":[{"id":"out_61de27325974e48bed220dbb","kind":"refund","status":"completed","amount":"10","net":"9","reason":"Item out of stock","…":"…"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/statement":{"get":{"operationId":"statement","summary":"Account statement","description":"Every balance movement with a running balance, from the double-entry ledger. `GET /statement.csv` with the same parameters downloads it as CSV for your accountant.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"YYYY-MM-DD (inclusive)."}},{"name":"to","in":"query","required":false,"schema":{"type":"string","description":"YYYY-MM-DD (inclusive)."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"period":"2026-09-01 → 2026-09-30","lines":[{"date":"2026-09-24T11:03:41.744Z","reference":"deposit:dep_709ecb039bb5d29ece216883","description":"Deposit received (net of processing fee)","account":"available","customerId":null,"network":"tron","asset":"USDT","amount":"49.661856","balance":"1859.478712"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{month}":{"get":{"operationId":"fee-invoice","summary":"Monthly fee invoice","description":"Processing, withdrawal and conversion fees charged in a month, per network and asset. The dashboard renders it as a printable invoice.","tags":["Balances & payouts"],"x-stablora-permission":"read","parameters":[{"name":"month","in":"path","required":true,"schema":{"type":"string","description":"`YYYY-MM`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"number":"QC-202609-4E425C9F","month":"2026-09","periodStart":"2026-09-01T00:00:00.000Z","periodEnd":"2026-10-01T00:00:00.000Z","issuedAt":"2026-09-24T11:03:41.962Z","customer":{"id":"mch_4e425c9f49d92545a65c80ce","name":"Orbit Commerce","email":"merchant@example.com"},"lines":[{"description":"Processing fee (0.5%)","network":"tron","asset":"USDT","transactions":9,"amount":"9.094558"},"…"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"operationId":"retrieve-event","summary":"Inspect an event","description":"The webhook inspector: the exact body we sent, the headers, and every delivery attempt with the URL, the signature, your server’s HTTP status, the first 2 KB of its response, the duration and any error. The dashboard shows the same under Developers → Inspect.","tags":["Webhooks"],"x-stablora-permission":"read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Event `evt_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"evt_56706555c39438cb1106801f","type":"payment.completed","status":"delivered","attempts":2,"created_at":"2026-09-24T11:03:41.745Z","delivered_at":"2026-09-24T11:03:52.310Z","next_attempt_at":null,"last_error":null,"request":{"method":"POST","headers":{"Content-Type":"application/json","Stablora-Signature":"t=…,v1=… (recomputed per attempt)","Stablora-Event-Id":"evt_56706555c39438cb1106801f"},"body":{"id":"evt_56706555c39438cb1106801f","type":"payment.completed","…":"…"}},"deliveries":[{"attempt":1,"url":"https://shop.example/webhooks/stablora","signature":"t=1790249021,v1=4f1c…","statusCode":500,"responseBody":"{\"error\":\"db down\"}","durationMs":84,"error":"Receiver returned HTTP 500.","at":"2026-09-24T11:03:42.100Z"},{"attempt":2,"url":"https://shop.example/webhooks/stablora","signature":"t=1790249032,v1=9ab2…","statusCode":200,"responseBody":"{\"ok\":true}","durationMs":41,"error":null,"at":"2026-09-24T11:03:52.310Z"}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}/replay":{"post":{"operationId":"replay-event","summary":"Replay an event","description":"Re-queues a failed or retrying event for immediate delivery (for example after fixing your endpoint).","tags":["Webhooks"],"x-stablora-permission":"payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Event `evt_…`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"ok":true}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"list-events","summary":"List events","description":"Recent events with their delivery status and last error.","tags":["Webhooks"],"x-stablora-permission":"read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"`pending`, `retry`, `delivered`, `failed`."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","description":"1–200, default 50."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","description":"Next page."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"evt_56706555c39438cb1106801f","type":"payment.completed","status":"delivered","attempts":1,"last_error":null,"created_at":"2026-09-24T11:03:41.745Z","delivered_at":"2026-09-24T11:03:42.310Z"}],"nextCursor":null}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/networks":{"get":{"operationId":"networks","summary":"Networks & assets","description":"Supported networks, their assets and finality rules. The table below is generated from the live catalogue.","tags":["Reference"],"x-stablora-permission":"read","responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"ethereum","name":"Ethereum","symbol":"ETH","family":"evm","assets":["USDT","USDC","ETH","SHIB","PEPE"],"mode":"sandbox","liveReady":false,"finality":{"confirmations":12,"note":"Wait for finalized/safe head; handle reorgs before crediting."}},"…"]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}