{"openapi":"3.1.0","info":{"title":"Easy Labs API","description":"The Swagger API documentation for the Easy Labs API.","version":"0.0.9"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-easy-api-key","description":"Merchant API key. Publishable keys (pk_test_* / pk_live_*) are safe for browser/frontend use and carry a limited scope set (sessions, payment_instruments, customers, orders writes; products, product_prices, payment_links reads). Secret keys (sk_test_* / sk_live_*) grant full admin access and must only be used server-side."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase JWT bearer token for dashboard / user-scoped endpoints. Role-derived scopes: ROOT/ADMIN → full admin; USER → read-only treasury."}}},"paths":{"/v1/":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/protected":{"get":{"responses":{"200":{"description":"Default Response"}},"security":[{"bearerAuth":[]}]}},"/v1/api/analytics/transactions":{"get":{"summary":"Get transaction volume analytics","tags":["analytics"],"description":"Retrieve transaction volume and count by period","parameters":[{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"period"},{"schema":{"type":"string"},"in":"query","name":"start_date"},{"schema":{"type":"string"},"in":"query","name":"end_date"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/analytics/disputes":{"get":{"summary":"Get dispute metrics","tags":["analytics"],"description":"Retrieve dispute totals, state breakdown, and dispute rate. Dispute rate denominator = card/DEBIT sales only.","parameters":[{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"period"},{"schema":{"type":"string"},"in":"query","name":"start_date"},{"schema":{"type":"string"},"in":"query","name":"end_date"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/analytics/settlements":{"get":{"summary":"Get settlement summary","tags":["analytics"],"description":"Retrieve monthly settlement net totals","parameters":[{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"period"},{"schema":{"type":"string"},"in":"query","name":"start_date"},{"schema":{"type":"string"},"in":"query","name":"end_date"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/analytics/revenue":{"get":{"summary":"Get revenue breakdown","tags":["analytics"],"description":"Retrieve debit/credit/reversal totals and net for the requested range (default last 30 days)","parameters":[{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"period"},{"schema":{"type":"string"},"in":"query","name":"start_date"},{"schema":{"type":"string"},"in":"query","name":"end_date"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/analytics/revenue-recovery":{"get":{"summary":"Get revenue recovery analytics","tags":["analytics"],"description":"Retrieve recovery metrics for failed payment retries","parameters":[{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"period"},{"schema":{"type":"string"},"in":"query","name":"start_date"},{"schema":{"type":"string"},"in":"query","name":"end_date"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/authorizations/":{"post":{"summary":"Create an authorization","tags":["authorization"],"description":"Create a Finix authorization (auth-only — no funds captured until /:id/capture). Body mirrors Finix's /authorizations payload. The merchant defaults to the API-key/JWT context but can be overridden for sub-merchant routing.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"source":{"type":"string","minLength":1},"merchant":{"type":"string","minLength":1},"statement_descriptor":{"type":"string","minLength":1,"maxLength":22},"idempotency_id":{"type":"string","minLength":1,"maxLength":64},"tags":{"type":"object","additionalProperties":{}}},"required":["amount","currency","source"],"example":{"amount":5000,"currency":"USD","source":"PIxxxxxxxxxxxxxxxxxx","statement_descriptor":"ACME WIDGETS","tags":{"order_id":"ord_abc123"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Authorization created","data":{"id":"AUxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","source":"PIxxxxxxxxxxxxxxxxxx","merchant":"MUxxxxxxxxxxxxxxxxxx","merchant_identity":"IDxxxxxxxxxxxxxxxxxx","state":"SUCCEEDED","is_void":false,"created_at":"2026-02-27T00:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List authorizations","tags":["authorization"],"description":"Retrieve a list of authorizations for the merchant. `expand=full` joins merchants + payment_instruments + identities for the dashboard list view.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["full"]},"in":"query","name":"expand"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Authorizations retrieved successfully","data":[{"id":"AUxxxxxxxxxxxxxxxxxx","amount":10000,"amount_requested":10000,"currency":"USD","state":"SUCCEEDED","is_void":false,"merchant":"MUxxxxxxxxxxxxxxxxxx","created_at":"2026-02-27T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/authorizations/{id}":{"get":{"summary":"Get an authorization by ID","tags":["authorization"],"description":"Retrieve a single authorization by its ID. `expand=full` joins merchants + payment_instruments + identities.","parameters":[{"schema":{"type":"string","enum":["full"]},"in":"query","name":"expand"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Authorization retrieved successfully","data":{"id":"AUxxxxxxxxxxxxxxxxxx","amount":10000,"amount_requested":10000,"currency":"USD","state":"SUCCEEDED","is_void":false,"merchant":"MUxxxxxxxxxxxxxxxxxx","created_at":"2026-02-27T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/authorizations/{id}/capture":{"post":{"summary":"Capture an authorization","tags":["authorization"],"description":"Capture a previously created authorization. Amount must be > 0 and cannot exceed the authorized amount.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0}},"required":["amount"],"example":{"amount":10000}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Authorization captured successfully","data":{"id":"AUxxxxxxxxxxxxxxxxxx","amount":10000,"state":"SUCCEEDED","is_void":false,"transfer":"TRxxxxxxxxxxxxxxxxxx"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/authorizations/{id}/void":{"post":{"summary":"Void an authorization","tags":["authorization"],"description":"Void a previously created authorization, releasing the held funds.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Authorization voided successfully","data":{"id":"AUxxxxxxxxxxxxxxxxxx","amount":10000,"state":"SUCCEEDED","is_void":true,"void_state":"SUCCEEDED"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/":{"post":{"summary":"Upload a bill for processing","tags":["Bill Pay"],"description":"Upload a bill document (PDF, PNG, JPEG, WebP) via multipart/form-data with field name `file`. The file is stored and extracted; the bill is returned ready for review.","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List bill submissions","tags":["Bill Pay"],"description":"Retrieve bill submissions with pagination and optional status/date filters.","parameters":[{"schema":{"type":"string","enum":["uploaded","extracting","extracted","review","confirmed","processing","completed","failed","cancelled"]},"in":"query","name":"status"},{"schema":{"type":"string"},"in":"query","name":"from_date"},{"schema":{"type":"string"},"in":"query","name":"to_date"},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"per_page"},{"schema":{"type":"string","default":"created_at"},"in":"query","name":"sort"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"order"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/{id}":{"get":{"summary":"Get bill submission by ID","tags":["Bill Pay"],"description":"Retrieve a single bill with all details and a signed document URL.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a bill submission","tags":["Bill Pay"],"description":"Update reviewed data and/or the matched recipient for a bill submission.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reviewed_data":{"type":"object","properties":{"vendor_name":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"due_date":{"type":"string"},"invoice_number":{"type":"string"},"routing_number":{"type":"string"},"account_number":{"type":"string"},"bank_name":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"number"},"amount":{"type":"number"}}}}},"additionalProperties":true},"recipient_id":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/{id}/confirm":{"post":{"summary":"Confirm a bill payment","tags":["Bill Pay"],"description":"Confirm a bill and submit the payment to Brale on the merchant's own account. The bill must be in extracted/review/confirmed status with a matched recipient.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"type":"string"},"scheduled_date":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/{id}/confirm-2fa":{"post":{"summary":"Confirm a bill payment 2FA challenge","tags":["Bill Pay"],"description":"Submit the 2FA code (and the transaction_id returned by /confirm) to finish a payment that required two-factor authentication. On success the bill moves to processing and the payment is submitted to Brale.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":6,"maxLength":6}},"required":["transaction_id","code"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/{id}/retry-extraction":{"post":{"summary":"Retry bill extraction","tags":["Bill Pay"],"description":"Re-run extraction on a failed bill. Only bills in 'failed' status can be retried.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/billpay/{id}/cancel":{"post":{"summary":"Cancel a bill submission","tags":["Bill Pay"],"description":"Cancel a bill. A linked treasury transaction is also cancelled if it has not yet been submitted to Brale.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/checkout/":{"post":{"summary":"Create a checkout session","tags":["checkout"],"description":"Create a new checkout session for payment collection","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"customer_creation":{"type":"boolean","enum":[true]},"customer_details":{"type":"object","properties":{"type":{"type":"string","enum":["PERSONAL","BUSINESS"],"default":"PERSONAL"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"personal_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"business_name":{"type":"string"},"doing_business_as":{"type":"string"},"business_phone":{"type":"string"},"business_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"external_customer_id":{"type":"string","minLength":1},"tags":{"type":"object","additionalProperties":{}}},"required":["first_name","last_name"]},"source":{"oneOf":[{"type":"object","properties":{"tokenId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["PAYMENT_CARD"]},"name":{"type":"string"},"address":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"postal_code":{"type":"string"},"region":{"type":"string"}},"required":["postal_code"]}},"required":["tokenId","type","name"]},{"type":"object","properties":{"tokenId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["BANK_ACCOUNT"]},"accountType":{"type":"string","enum":["PERSONAL_CHECKING","PERSONAL_SAVINGS","BUSINESS_CHECKING","BUSINESS_SAVINGS"]},"name":{"type":"string"}},"required":["tokenId","type","accountType"]}]},"line_items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["price_id","quantity"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["customer_creation","customer_details","source","line_items"]},{"type":"object","properties":{"customer_creation":{"type":"boolean","default":false,"enum":[false]},"identity_id":{"type":"string"},"source":{"anyOf":[{"oneOf":[{"type":"object","properties":{"tokenId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["PAYMENT_CARD"]},"name":{"type":"string"},"address":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"postal_code":{"type":"string"},"region":{"type":"string"}},"required":["postal_code"]}},"required":["tokenId","type","name"]},{"type":"object","properties":{"tokenId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["BANK_ACCOUNT"]},"accountType":{"type":"string","enum":["PERSONAL_CHECKING","PERSONAL_SAVINGS","BUSINESS_CHECKING","BUSINESS_SAVINGS"]},"name":{"type":"string"}},"required":["tokenId","type","accountType"]}]},{"type":"string"}]},"line_items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["price_id","quantity"]}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["identity_id","source","line_items"]}],"example":{"customer_creation":false,"identity_id":"IDxxxxxxxxxxxxxxxxxx","source":{"type":"PAYMENT_CARD","tokenId":"tok_abc123","name":"John Doe","address":{"postal_code":"94105"}},"line_items":[{"price_id":"price_abc123","quantity":1}],"metadata":{"order_ref":"ORD-001"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Checkout session created","data":{"transfer":{"id":"TRxxxxxxxxxxxxxxxx","amount":1000,"currency":"USD","state":"PENDING"},"orderId":"ORD-001","subscriptions":[]}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/compliance-forms/":{"get":{"summary":"Get compliance forms","tags":["compliance-form"],"description":"Retrieve a list of compliance forms","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/compliance-forms/{id}":{"get":{"summary":"Get compliance form","tags":["compliance-form"],"description":"Retrieve a compliance form by ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/compliance-forms/{id}/sign":{"put":{"summary":"Sign compliance form","tags":["compliance-form"],"description":"Sign a PCI compliance form","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"title":{"type":"string","minLength":1}},"required":["name","title"]}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/coupons/":{"post":{"summary":"Create coupon","tags":["coupons"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"percent_off":{"type":"number","exclusiveMinimum":0,"maximum":100},"amount_off":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"duration":{"type":"string","enum":["once","repeating","forever"]},"duration_in_months":{"type":"integer","exclusiveMinimum":0},"max_redemptions":{"type":"integer","exclusiveMinimum":0},"valid_until":{"type":"string","format":"date-time"},"applies_to_products":{"type":"array","items":{"type":"string","format":"uuid"}},"metadata":{"type":"object","additionalProperties":{}},"active":{"type":"boolean"}},"required":["duration"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List coupons","tags":["coupons"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/coupons/{id}":{"get":{"summary":"Get coupon","tags":["coupons"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update coupon","tags":["coupons"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete coupon","tags":["coupons"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/":{"post":{"summary":"Create a new customer","tags":["customer"],"description":"Create a new customer","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["PERSONAL","BUSINESS"],"default":"PERSONAL"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"personal_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"business_name":{"type":"string"},"doing_business_as":{"type":"string"},"business_phone":{"type":"string"},"business_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"external_customer_id":{"type":"string","minLength":1},"tags":{"type":"object","additionalProperties":{}}},"required":["first_name","last_name"],"example":{"first_name":"John","last_name":"Doe","email":"john@example.com","phone":"1234567890","personal_address":{"line1":"123 Main St","city":"San Francisco","region":"CA","postal_code":"94105"},"tags":{"customer_type":"premium"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Customer created","data":{"id":"IDxxxxxxxxxxxxxxxxxx","entity":{"first_name":"John","last_name":"Doe","email":"john@example.com","phone":"1234567890","personal_address":{"line1":"123 Main St","city":"San Francisco","region":"CA","postal_code":"94105","country":"USA"}},"tags":{"company_id":"comp_abc123"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get all customers","tags":["customer"],"description":"Retrieve a list of customers (Finix identities) for the authenticated company. Filters: `role` (one of APPLICATION_OWNER, BENEFICIAL_OWNER, BUYER, PLATFORM_OWNER, RECIPIENT, SELLER, SENDER — values match the `finix_identity_role` DB enum); `include=instruments` (joins payment_instruments); `include_hidden=true` (returns identities tagged `hidden=true` — suppressed by default).","parameters":[{"schema":{"type":"number","minimum":0,"maximum":100},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["APPLICATION_OWNER","BENEFICIAL_OWNER","BUYER","PLATFORM_OWNER","RECIPIENT","SELLER","SENDER"]},"in":"query","name":"role"},{"schema":{"type":"string","enum":["instruments"]},"in":"query","name":"include"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"include_hidden"},{"schema":{"type":"string","minLength":1},"in":"query","name":"external_customer_id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"IDxxxxxxxxxxxxxxxxxx","entity":{"first_name":"John","last_name":"Doe","email":"john@example.com"},"tags":{"company_id":"comp_abc123"},"company_id":"comp_abc123","created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}":{"patch":{"summary":"Update a customer","tags":["customer"],"description":"Update a customer","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["PERSONAL","BUSINESS"],"default":"PERSONAL"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"personal_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"business_name":{"type":"string"},"doing_business_as":{"type":"string"},"business_phone":{"type":"string"},"business_address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}},"required":["line1","city","region","postal_code"]},"external_customer_id":{"type":"string","minLength":1},"tags":{"type":"object","additionalProperties":{}}},"example":{"first_name":"Jane","email":"jane@example.com"}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Customer updated","data":{"id":"IDxxxxxxxxxxxxxxxxxx","entity":{"first_name":"Jane","last_name":"Doe","email":"jane@example.com","phone":"0987654321"},"tags":{"company_id":"comp_abc123"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get a customer by ID","tags":["customer"],"description":"Retrieve a customer by their ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"IDxxxxxxxxxxxxxxxxxx","entity":{"first_name":"John","last_name":"Doe","email":"john@example.com","phone":"1234567890"},"tags":{"company_id":"comp_abc123"},"company_id":"comp_abc123","created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}/instruments":{"get":{"summary":"Get all payment instruments for a customer","tags":["customer"],"description":"Retrieve a list of all payment instruments for a specific customer","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"PIxxxxxxxxxxxxxxxxxx","identity_id":"IDxxxxxxxxxxxxxxxxxx","instrument_type":"PAYMENT_CARD","type":"PAYMENT_CARD","created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}/payment-methods":{"get":{"summary":"Get saved payment methods for a customer","tags":["customer"],"description":"Returns canonical Easy payment-method rows for a customer at the caller's merchant. `:id` is the `easy.customers.id` (returned from `POST /v1/api/customer`), not the Finix identity id. Pass `?include_archived=true` to include soft-deleted methods.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"include_archived"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-05-18T12:00:00.000Z","data":[{"id":"00000000-0000-0000-0000-000000000001","type":"PAYMENT_CARD","brand":"VISA","last4":"4242","exp_month":12,"exp_year":2030,"account_type":null,"is_default":true,"archived_at":null,"created_at":"2026-05-01T12:00:00.000Z","finix_payment_instrument_id":"PIxxxxxxxxxxxxxxxxxx"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}/orders":{"get":{"summary":"Get all orders for a customer","tags":["customer"],"description":"Retrieve a list of all orders for a specific customer","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"ord_abc123","order_number":"ORD-0001","subtotal_cents":5000,"total_cents":5000,"currency":"USD","source":"API","purchase_items":[],"transfer":null,"identity":null,"payment_instrument":null,"created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}/subscriptions":{"get":{"summary":"Get all subscriptions for a customer","tags":["customer"],"description":"Retrieve a list of all subscriptions for a specific customer. This endpoint exposes legacy Finix subscription payload fields and is included for migration compatibility.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["incomplete","incomplete_expired","trialing","active","past_due","unpaid","canceled","paused"]},"in":"query","name":"status"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"data":[{"id":"SUxxxxxxxxxxxxxxxxxx","status":"active","identity_id":"IDxxxxxxxxxxxxxxxxxx","instrument_id":"PIxxxxxxxxxxxxxxxxxx","items":[{"id":"SIBxxxxxxxxxxxxxxxxxx","price_id":"pp_123456","quantity":1,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","price":{"id":"pp_123456","unit_amount":2999,"currency":"USD","recurring":true,"interval":"month","interval_count":1,"pricing_model":"per_unit","trial_period_days":null}}],"current_period_start":"2026-01-01T00:00:00.000Z","current_period_end":"2026-01-31T00:00:00.000Z","trial_start":null,"trial_end":null,"billing_cycle_anchor":"2026-01-01T00:00:00.000Z","cancel_at_period_end":false,"cancel_at":null,"canceled_at":null,"pause_collection":null,"latest_invoice_id":null,"proration_behavior":"create_prorations","credit_balance":0,"pending_update":null,"description":"Starter subscription","metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"total":1,"limit":20,"offset":0},"message":"Customers subscriptions fetched"}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer/{id}/wallets":{"get":{"summary":"Get all wallets for a customer","tags":["customer"],"description":"Retrieve a list of all wallets for a specific customer","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"wa_abc123","identity_id":"IDxxxxxxxxxxxxxxxxxx","company_id":"comp_abc123","created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/public":{"get":{"summary":"Get public customer portal context","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"company_id","required":true},{"schema":{"type":"string","enum":["sandbox","production","live"]},"in":"query","name":"environment"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/request-link":{"post":{"summary":"Request customer portal magic link","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"environment":{"type":"string","enum":["sandbox","production","live"]},"destination":{"type":"string","enum":["home","payment_methods","billing_information","subscription_cancel"]},"destination_context":{"type":"object","additionalProperties":{}}},"required":["company_id","email"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/consume":{"post":{"summary":"Consume customer portal magic link","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/handoff/create":{"post":{"summary":"Create a one-time handoff code for cross-domain session transfer","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_token":{"type":"string","minLength":1},"destination":{"type":"string"}},"required":["session_token"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/handoff/exchange":{"post":{"summary":"Exchange a handoff code for a session token (single use)","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1}},"required":["code"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/me":{"get":{"summary":"Get active customer portal session","tags":["customer-portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/recovery":{"post":{"summary":"Consume a revenue recovery link into a customer portal session","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/access/sign-out":{"post":{"summary":"Sign out customer portal session","tags":["customer-portal"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/payment-methods":{"post":{"summary":"Create a payment method from an active customer portal session","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string","minLength":1},"country":{"type":"string"}},"required":["postal_code"]},"link_easy_connect":{"type":"boolean"},"easy_connect_session_token":{"type":"string","minLength":1,"maxLength":4096}},"required":["token_id","address"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/payment-methods/canonical":{"get":{"summary":"List canonical payment methods scoped to the active portal session","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"include_archived"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/payment-methods/canonical/{id}/set-default":{"post":{"summary":"Set a canonical payment method as the portal customer's default","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/payment-methods/canonical/{id}/archive":{"post":{"summary":"Soft-delete a canonical payment method (portal-scoped)","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/payment-methods/{instrumentId}":{"delete":{"summary":"Remove a payment method from an active customer portal session","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"instrumentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/subscriptions":{"get":{"summary":"List the portal customer's subscriptions (cancel page data)","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"subscription_id"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/subscriptions/{id}/cancel":{"post":{"summary":"Cancel the portal customer's subscription at period end (idempotent)","tags":["customer-portal"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal/billing-information":{"patch":{"summary":"Update billing information from an active customer portal session","tags":["customer-portal"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"billing_address":{"type":["object","null"],"properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}}},"shipping_same_as_billing":{"type":"boolean"},"shipping_address":{"type":["object","null"],"properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"}}},"tax_ids":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","minLength":1},"value":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["type","value"]}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/customer-portal-config/":{"get":{"summary":"Get customer portal config","tags":["customer-portal-config"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Patch customer portal config","tags":["customer-portal-config"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_history_enabled":{"type":"boolean"},"customer_info_enabled":{"type":"boolean"},"customer_info_name_enabled":{"type":"boolean"},"customer_info_email_enabled":{"type":"boolean"},"customer_info_billing_address_enabled":{"type":"boolean"},"customer_info_shipping_address_enabled":{"type":"boolean"},"customer_info_phone_enabled":{"type":"boolean"},"customer_info_tax_id_enabled":{"type":"boolean"},"payment_methods_enabled":{"type":"boolean"},"accepted_payment_methods":{"type":"array","items":{"type":"string"}},"payment_configuration":{"type":"string"},"cancellations_enabled":{"type":"boolean"},"cancellation_mode":{"type":"string","enum":["immediately","end_of_period"]},"cancellation_proration_enabled":{"type":"boolean"},"cancellation_reasons_enabled":{"type":"boolean"},"cancellation_reasons":{"type":"array","items":{"type":"string"}},"retention_coupon_id":{"type":["string","null"]},"subscriptions_enabled":{"type":"boolean"},"allow_plan_switch":{"type":"boolean"},"allow_quantity_updates":{"type":"boolean"},"subscription_product_ids":{"type":"array","items":{"type":"string"}},"subscription_proration_behavior":{"type":"string","enum":["none","prorate","full_difference"]},"subscription_charge_timing":{"type":"string","enum":["immediately","period_end"]},"downgrade_plan_timing":{"type":"string","enum":["immediately","period_end"]},"downgrade_interval_timing":{"type":"string","enum":["immediately","period_end"]},"promotion_codes_enabled":{"type":"boolean"},"portal_header":{"type":["string","null"]},"return_url":{"type":["string","null"]},"custom_domain_id":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/dashboard-stats/":{"get":{"summary":"Get dashboard home stats (JWT-only)","tags":["dashboard"],"description":"Wraps the `get_merchant_dashboard_data` Postgres RPC for the dashboard home view. Coin (`value_type`) is selected server-side based on the active environment.\n\n**JWT-only**: this endpoint resolves the company via the Postgres `auth.uid()` session variable, which is only populated when the caller's Bearer token is forwarded to Supabase. API-key authentication therefore returns 403.","parameters":[{"schema":{"type":"string","enum":["today","week","monthly"],"default":"today"},"in":"query","name":"timeframe"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","data":{"timeframe":"today","metrics":{},"kpis":{},"salesOvertime":[]}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/disputes/":{"get":{"summary":"Get disputes","tags":["dispute"],"description":"Retrieve a list of disputes. `state` filters by dispute lifecycle state (INQUIRY/PENDING/LOST/WON) server-side. `expand=full` joins transfers + payment_instruments + identities + merchants for the dashboard list view.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["INQUIRY","PENDING","LOST","WON"]},"in":"query","name":"state"},{"schema":{"type":"string","enum":["full"]},"in":"query","name":"expand"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"DI_abc123","amount":5000,"currency":"USD","state":"PENDING","reason":"FRAUD","respond_by":"2026-02-20T00:00:00.000Z","tags":{},"created_at":"2026-01-15T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/disputes/{id}":{"get":{"summary":"Get a dispute by ID","tags":["dispute"],"description":"Retrieve a dispute by its ID. `expand=full` joins transfers + payment_instruments + identities + merchants.","parameters":[{"schema":{"type":"string","enum":["full"]},"in":"query","name":"expand"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"DI_abc123","amount":5000,"currency":"USD","state":"PENDING","reason":"FRAUD","respond_by":"2026-02-20T00:00:00.000Z","transfer_id":"TRxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-01-15T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update dispute tags","tags":["dispute"],"description":"Update the tags of a dispute","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"object","additionalProperties":true}},"required":["tags"],"example":{"tags":{"category":"chargeback","priority":"high"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Dispute tags updated","data":{"id":"DI_abc123","tags":{"category":"chargeback","priority":"high"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/disputes/{id}/accept":{"post":{"summary":"Accept a dispute","tags":["dispute"],"description":"Accept liability for a dispute. Forwards to Finix POST /disputes/:id/accept.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/disputes/{id}/submit":{"post":{"summary":"Submit dispute evidence","tags":["dispute"],"description":"Submit previously uploaded evidence for review. Forwards to Finix POST /disputes/:id/submit.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/disputes/{id}/evidence":{"post":{"summary":"Upload dispute evidence","tags":["dispute"],"description":"Upload one evidence file for a dispute. Multipart/form-data with a `file` field. Allowed types: jpeg, png, pdf. Max 1MB per file. Call once per file.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List dispute evidence files","tags":["dispute"],"description":"Retrieve evidence files attached to a dispute (read from finix.files).","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/dunning-config/":{"post":{"summary":"Create or replace revenue recovery config","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"retry_mode":{"type":"string","enum":["smart","custom"]},"smart_retry_attempts":{"type":"integer","enum":[4,8]},"smart_retry_window":{"type":"string","enum":["1_week","2_weeks","3_weeks","1_month","2_months"]},"custom_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":3},"bank_debit_retries_enabled":{"type":"boolean"},"bank_debit_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":2},"subscription_terminal_action":{"type":"string","enum":["cancel","unpaid","past_due","pause"]},"invoice_terminal_action":{"type":"string","enum":["past_due","uncollectible"]},"payment_failed_email_enabled":{"type":"boolean"},"bank_debit_payment_failed_email_enabled":{"type":"boolean"},"email_action_required":{"type":"boolean"},"expiring_card_email_enabled":{"type":"boolean"},"card_expiry_warn_days":{"type":"integer","minimum":1,"maximum":365},"payment_failed_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"payment_failed_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiring_card_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"expiring_card_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_payment_method_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get revenue recovery config","tags":["subscriptions"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Patch revenue recovery config","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"retry_mode":{"type":"string","enum":["smart","custom"]},"smart_retry_attempts":{"type":"integer","enum":[4,8]},"smart_retry_window":{"type":"string","enum":["1_week","2_weeks","3_weeks","1_month","2_months"]},"custom_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":3},"bank_debit_retries_enabled":{"type":"boolean"},"bank_debit_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":2},"subscription_terminal_action":{"type":"string","enum":["cancel","unpaid","past_due","pause"]},"invoice_terminal_action":{"type":"string","enum":["past_due","uncollectible"]},"payment_failed_email_enabled":{"type":"boolean"},"bank_debit_payment_failed_email_enabled":{"type":"boolean"},"email_action_required":{"type":"boolean"},"expiring_card_email_enabled":{"type":"boolean"},"card_expiry_warn_days":{"type":"integer","minimum":1,"maximum":365},"payment_failed_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"payment_failed_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiring_card_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"expiring_card_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_payment_method_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/easy-connect/lookup":{"post":{"summary":"Look up an Easy Connect customer by email","tags":["easy-connect"],"description":"Returns whether the email corresponds to an enrolled customer AND is in a country eligible for Easy Connect SMS verification. Response shape is identical for unrecognized vs. recognized-but-ineligible so the endpoint can't be used to enumerate enrolled emails.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":320}},"required":["email"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/easy-connect/send-code":{"post":{"summary":"Send a verification code to the customer's phone","tags":["easy-connect"],"description":"Triggers Twilio Verify to deliver an SMS OTP. Gated by per-IP / per-email / per-phone rate limits, country eligibility, and the email-must-be-enrolled rule. Returns `{sent: true}` on success and `{sent: false}` for any rejection — never leaks which gate failed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":320},"turnstile_token":{"type":"string","minLength":1,"maxLength":4096}},"required":["email"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/easy-connect/verify":{"post":{"summary":"Verify the OTP and mint a customer-session token","tags":["easy-connect"],"description":"Checks the code against Twilio Verify. On approval, stamps `phone_verified_at` (and `email_verified_at` if not previously set) on the easy.customers row and returns a 15-minute customer-session JWT scoped to the optional embed session_id.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":320},"code":{"type":"string","pattern":"^\\d{4,8}$"},"session_id":{"type":"string","minLength":1,"maxLength":64}},"required":["email","code"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/easy-connect/payment-methods":{"get":{"summary":"List cross-merchant saved methods for the authenticated customer","tags":["easy-connect"],"description":"Returns canonical payment methods for the customer encoded in the customer-session JWT (Authorization: Bearer). Display metadata only — the per-merchant Finix PI id is intentionally omitted here; the iframe materializes it on demand at transfer time. Pass ?include_archived=true to include soft-deleted methods.","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"include_archived"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/easy-connect/refresh":{"post":{"summary":"Refresh the customer-session token","tags":["easy-connect"],"description":"Slides the customer-session JWT window. Requires Authorization: Bearer <token>. Enforces a 30-minute hard cap on the refresh chain — beyond that the customer must re-OTP.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/email-logs/":{"get":{"summary":"List outbound emails","tags":["email-logs"],"description":"List emails the platform sent on this company's behalf, with their delivery status. Scoped to the calling company and the current environment.","parameters":[{"schema":{"type":"string","enum":["sent","failed","refused","delivered","delayed","bounced","complained"]},"in":"query","name":"status"},{"schema":{"type":"string","maxLength":120},"in":"query","name":"event_name"},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/":{"post":{"summary":"Create an embedded checkout session","tags":["embedded-checkout"],"description":"Creates a new embedded checkout session. Returns a client_secret that the merchant passes to their frontend to render the checkout form in an iframe.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["price_id","quantity"]},"minItems":1},"mode":{"type":"string","enum":["payment","subscription"],"default":"payment"},"return_url":{"type":"string","format":"uri"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"customer_email":{"type":"string","format":"email"},"metadata":{"type":"object","additionalProperties":{}},"payment_methods":{"type":"array","items":{"type":"string","enum":["card","crypto"]},"minItems":1,"default":["card"]},"easy_customer_id":{"type":"string","format":"uuid"},"allow_saved_methods":{"type":"boolean"},"save_card_default":{"type":"boolean"}},"required":["line_items"],"example":{"line_items":[{"price_id":"price_abc123","quantity":1}],"mode":"payment","success_url":"https://merchant.com/success?session_id={SESSION_ID}","cancel_url":"https://merchant.com/cancel","customer_email":"customer@example.com"}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-03-13T12:00:00.000Z","message":"Embedded checkout session created","data":{"id":"ecs_abc123","client_secret":"ecs_abc123_secret_xyz789","url":"https://checkout.itseasy.co/embed?session=ecs_abc123","amount_total":2000,"currency":"USD","status":"open","expires_at":"2026-03-14T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/validate":{"post":{"summary":"Validate an embedded checkout session","tags":["embedded-checkout"],"description":"Validates a client_secret and returns session data needed to render the checkout form. No API key required — the client_secret serves as the auth token.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_secret":{"type":"string","minLength":1,"maxLength":300},"parent_origin":{"type":"string","format":"uri","maxLength":500}},"required":["client_secret"],"example":{"client_secret":"ecs_abc123_secret_xyz789"}}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/{id}":{"get":{"summary":"Retrieve an embedded checkout session","tags":["embedded-checkout"],"description":"Retrieves the current status of an embedded checkout session. Use this after payment to verify the session completed.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/confirm":{"post":{"summary":"Confirm payment for an embedded checkout session","tags":["embedded-checkout"],"description":"Processes payment for an embedded checkout session. Called by the checkout iframe's server action with the client_secret and tokenized payment details.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_secret":{"type":"string","minLength":1,"maxLength":300},"source":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["PAYMENT_CARD"]},"tokenId":{"type":"string","minLength":1,"maxLength":500},"name":{"type":"string","maxLength":200},"address":{"type":"object","additionalProperties":{"type":"string","maxLength":200}},"accountType":{"type":"string","maxLength":50}},"required":["type","tokenId"]},{"type":"object","properties":{"type":{"type":"string","enum":["BANK_ACCOUNT"]},"tokenId":{"type":"string","minLength":1,"maxLength":500},"name":{"type":"string","maxLength":200},"address":{"type":"object","additionalProperties":{"type":"string","maxLength":200}},"accountType":{"type":"string","maxLength":50}},"required":["type","tokenId"]},{"type":"object","properties":{"type":{"type":"string","enum":["EXISTING_PAYMENT_INSTRUMENT"]},"paymentInstrumentId":{"type":"string","minLength":1,"maxLength":200}},"required":["type","paymentInstrumentId"]},{"type":"object","properties":{"type":{"type":"string","enum":["EASY_PAYMENT_METHOD"]},"easyPaymentMethodId":{"type":"string","format":"uuid"}},"required":["type","easyPaymentMethodId"]}]},"customer_details":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":["string","null"],"pattern":"^[+\\d\\s()-]*$","maxLength":30},"personal_address":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},"required":["first_name","last_name","email"]},"customer_session_token":{"type":"string","minLength":1,"maxLength":4096},"enrollment":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"phone":{"type":"string","minLength":4,"maxLength":20}},"required":["country","phone"]}},"required":["client_secret","source","customer_details"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"410":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/{id}/crypto-status":{"get":{"summary":"Get crypto payment status for a checkout session","tags":["embedded-checkout"],"description":"Returns the crypto payment reference status for this session. No API key required — the session ID serves as identification.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/embedded-checkout/config":{"get":{"summary":"Get embedded checkout configuration","tags":["embedded-checkout"],"description":"Retrieves the embedded checkout configuration for this company, including allowed origins.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"allowed_origins":{"type":"array","items":{"type":"string"}},"allow_saved_methods":{"type":"boolean"},"enable_easy_connect":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","company_id","allowed_origins","allow_saved_methods","enable_easy_connect","created_at","updated_at"]},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp","data"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update embedded checkout configuration","tags":["embedded-checkout"],"description":"Updates the embedded checkout configuration for this company. Requires API key with WRITE_SETTINGS scope.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Array of allowed origins for embedded checkout iframe. Supports exact match (https://checkout.acmecorp.com) and wildcard subdomains (https://*.acmecorp.com). Empty array disables embedding."},"allow_saved_methods":{"type":"boolean","description":"Default for the saved-methods picker on embedded checkout. Sessions can override per-session."},"enable_easy_connect":{"type":"boolean","description":"Per-company toggle for the Easy Connect email-first cross-merchant flow."}},"example":{"allowed_origins":["https://checkout.acmecorp.com","https://*.acmecorp.com"]}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"company_id":{"type":"string","format":"uuid"},"allowed_origins":{"type":"array","items":{"type":"string"}},"allow_saved_methods":{"type":"boolean"},"enable_easy_connect":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","company_id","allowed_origins","allow_saved_methods","enable_easy_connect","created_at","updated_at"]},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp","data"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/files/":{"get":{"summary":"List merchant files","tags":["files"],"description":"List files attached to the authenticated merchant from the local Finix mirror.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/files/{id}":{"get":{"summary":"Get a file by ID","tags":["files"],"description":"Retrieve a file's metadata. Scoped to the authenticated merchant via ownership of the linked resource.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/files/{id}/upload":{"post":{"summary":"Upload file content","tags":["files"],"description":"Upload binary content to a pre-existing file record. The file must already exist (Finix or webhook creates these). Multipart/form-data with a `file` field. Allowed types: jpeg, png, pdf. Max 5MB.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/":{"post":{"summary":"Create a new invoice","tags":["invoices"],"description":"Create a new invoice with line items. Invoice number is auto-generated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"currency":{"type":"string","default":"USD"},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"default":"send_invoice"},"from_company_name":{"type":"string"},"from_email":{"type":"string","format":"email"},"from_address":{"type":"object","additionalProperties":{}},"from_tax_id":{"type":"string"},"from_phone":{"type":"string"},"from_logo_url":{"type":"string","format":"uri"},"to_company_name":{"type":"string"},"to_contact_name":{"type":"string"},"to_email":{"type":"string","format":"email"},"to_address":{"type":"object","additionalProperties":{}},"to_tax_id":{"type":"string"},"to_phone":{"type":"string"},"buyer_id":{"type":"string","format":"uuid"},"tax_rate":{"type":"number","minimum":0,"maximum":100},"discount_amount":{"type":"integer","minimum":0},"discount_type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"due_date":{"type":"string","minLength":1},"issue_date":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"auto_reminders":{"type":"boolean"},"is_recurring":{"type":"boolean"},"recurrence_interval":{"type":"string","enum":["WEEKLY","BIWEEKLY","MONTHLY","QUARTERLY","YEARLY"]},"recurrence_end_date":{"type":"string"},"recurrence_auto_send":{"type":"boolean"},"recurring_parent_id":{"type":"string","format":"uuid"},"template_id":{"type":"string"},"custom_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"value":{"type":"string"}},"required":["name","value"]}},"tax_ids":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string","enum":["merchant","customer"]},"type":{"type":"string","minLength":1},"value":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["type","value"]}},"pdf_page_size":{"type":"string","enum":["LETTER","A4"]},"include_payment_page_link":{"type":"boolean"},"include_pdf_payment_link":{"type":"boolean"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":"string"},"scheduled_finalize_at":{"type":"string"},"scheduled_charge_at":{"type":"string"},"shipping_rate_id":{"type":"string"},"shipping_rate_label":{"type":"string"},"shipping_amount":{"type":"integer","minimum":0},"default_payment_instrument_id":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"unit_price":{"type":"integer","minimum":0},"product_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer","minimum":0},"price_id":{"type":"string"},"coupon_ids":{"type":"array","items":{"type":"string"}},"discountable":{"type":"boolean"},"manual_tax_rate":{"type":"number","minimum":0,"maximum":100},"supply_start_date":{"type":"string"},"supply_end_date":{"type":"string"}},"required":["description","quantity","unit_price"]},"minItems":1},"branding_overrides":{"type":["object","null"],"properties":{"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":["string","null"],"format":"uri"},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500}}}},"required":["to_email","due_date","items"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List invoices","tags":["invoices"],"description":"Retrieve invoices with pagination and optional status/date filters.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["DRAFT","OPEN","SENT","VIEWED","OVERDUE","PARTIALLY_PAID","PAID","UNPAID","VOID","VOIDED"]},"in":"query","name":"status"},{"schema":{"type":"string","enum":["charge_automatically","send_invoice"]},"in":"query","name":"collection_method"},{"schema":{"type":"string"},"in":"query","name":"due_date_from"},{"schema":{"type":"string"},"in":"query","name":"due_date_to"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/next-number":{"get":{"summary":"Get next invoice number","tags":["invoices"],"description":"Returns the next sequential invoice number in the canonical `INV-NNN` format for the authenticated company.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}":{"get":{"summary":"Get invoice by ID","tags":["invoices"],"description":"Retrieve a single invoice with all line items.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a draft invoice","tags":["invoices"],"description":"Update an invoice. Only DRAFT invoices can be modified.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"currency":{"type":"string","default":"USD"},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"default":"send_invoice"},"from_company_name":{"type":"string"},"from_email":{"type":"string","format":"email"},"from_address":{"type":"object","additionalProperties":{}},"from_tax_id":{"type":"string"},"from_phone":{"type":"string"},"from_logo_url":{"type":"string","format":"uri"},"to_company_name":{"type":"string"},"to_contact_name":{"type":"string"},"to_address":{"type":"object","additionalProperties":{}},"to_tax_id":{"type":"string"},"to_phone":{"type":"string"},"buyer_id":{"type":"string","format":"uuid"},"tax_rate":{"type":"number","minimum":0,"maximum":100},"discount_amount":{"type":"integer","minimum":0},"discount_type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"issue_date":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"auto_reminders":{"type":"boolean"},"is_recurring":{"type":"boolean"},"recurrence_interval":{"type":"string","enum":["WEEKLY","BIWEEKLY","MONTHLY","QUARTERLY","YEARLY"]},"recurrence_end_date":{"type":"string"},"recurrence_auto_send":{"type":"boolean"},"recurring_parent_id":{"type":"string","format":"uuid"},"template_id":{"type":"string"},"custom_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"value":{"type":"string"}},"required":["name","value"]}},"tax_ids":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string","enum":["merchant","customer"]},"type":{"type":"string","minLength":1},"value":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["type","value"]}},"pdf_page_size":{"type":"string","enum":["LETTER","A4"]},"include_payment_page_link":{"type":"boolean"},"include_pdf_payment_link":{"type":"boolean"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":"string"},"scheduled_finalize_at":{"type":"string"},"scheduled_charge_at":{"type":"string"},"shipping_rate_id":{"type":"string"},"shipping_rate_label":{"type":"string"},"shipping_amount":{"type":"integer","minimum":0},"default_payment_instrument_id":{"type":"string"},"branding_overrides":{"type":["object","null"],"properties":{"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":["string","null"],"format":"uri"},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500}}},"to_email":{"type":"string","format":"email"},"due_date":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"unit_price":{"type":"integer","minimum":0},"product_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer","minimum":0},"price_id":{"type":"string"},"coupon_ids":{"type":"array","items":{"type":"string"}},"discountable":{"type":"boolean"},"manual_tax_rate":{"type":"number","minimum":0,"maximum":100},"supply_start_date":{"type":"string"},"supply_end_date":{"type":"string"}},"required":["description","quantity","unit_price"]}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/send":{"post":{"summary":"Send an invoice","tags":["invoices"],"description":"Send or schedule a request-payment invoice email.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to_email":{"type":"string","format":"email"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"include_payment_page_link":{"type":"boolean"},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":["string","null"]}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/pay":{"post":{"summary":"Pay an outstanding invoice","tags":["invoices"],"description":"Collect payment for an invoice with a Finix payment instrument.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instrument_id":{"type":"string","minLength":1},"amount":{"type":"integer","exclusiveMinimum":0},"idempotency_key":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/remind":{"post":{"summary":"Send invoice reminder","tags":["invoices"],"description":"Send a payment reminder for SENT or OVERDUE invoices.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/void":{"post":{"summary":"Void an invoice","tags":["invoices"],"description":"Void an invoice. Cannot void paid invoices.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/pdf":{"get":{"summary":"Get invoice data for PDF","tags":["invoices"],"description":"Returns invoice data as JSON for client-side PDF generation.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/view":{"get":{"summary":"View invoice (public)","tags":["invoices"],"description":"Public endpoint for recipients to view their invoice. Updates last_viewed_at.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/invoices/{id}/pdf/download":{"get":{"summary":"Download invoice PDF (public)","tags":["invoices"],"description":"Public endpoint to download a generated invoice PDF. Returns a redirect to a signed URL.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/merchant/":{"get":{"summary":"Get the authenticated merchant","tags":["merchant"],"description":"Returns the merchant record for the authenticated context (joined with its primary identity). Scoped to the active environment.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","data":{"id":"MUxxxxxxxxxxxxxxxxxx","merchant_name":"Acme Widgets","identity_id":"IDxxxxxxxxxxxxxxxxxx","identity":{"id":"IDxxxxxxxxxxxxxxxxxx","entity":{"business_name":"Acme Widgets, Inc."}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/orders/":{"get":{"summary":"Get orders","tags":["order"],"description":"Retrieve a list of orders","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"ord_abc123","order_number":"ORD-0001","subtotal_cents":5000,"total_cents":5000,"currency":"USD","source":"API","purchase_items":[],"transfer":null,"identity":null,"payment_instrument":null,"tags":{},"created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/orders/{id}":{"get":{"summary":"Get an order by ID","tags":["order"],"description":"Retrieve an order by its ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"ord_abc123","order_number":"ORD-0001","subtotal_cents":5000,"total_cents":5000,"currency":"USD","source":"API","purchase_items":[],"transfer":null,"identity":null,"payment_instrument":null,"tags":{},"created_at":"2026-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update order tags","tags":["order"],"description":"Update the tags of an order","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"object","additionalProperties":true}},"required":["tags"],"example":{"tags":{"category":"electronics","priority":"high"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Order tags updated","data":{"id":"ord_abc123","tags":{"category":"electronics","priority":"high"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment/":{"post":{"summary":"Create a payment (customer charge)","tags":["payment"],"description":"Charge a customer's payment instrument. Body mirrors Finix's POST /transfers payload. The merchant defaults to the API-key/JWT context but can be overridden for sub-merchant routing.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"source":{"type":"string","minLength":1},"merchant":{"type":"string","minLength":1},"statement_descriptor":{"type":"string","minLength":1,"maxLength":22},"idempotency_id":{"type":"string","minLength":1,"maxLength":64},"tags":{"type":"object","additionalProperties":{}}},"required":["amount","currency","source"],"example":{"amount":5000,"currency":"USD","source":"PIxxxxxxxxxxxxxxxxxx","tags":{"order_id":"ord_abc123"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment created","data":{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"PENDING","identity_id":"IDxxxxxxxxxxxxxxxxxx","payment_instrument_id":"PIxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List payments","tags":["payment"],"description":"Retrieve a list of payments. Filters: `type` (DEBIT/CREDIT/REVERSAL/FEE/ADJUSTMENT/DISPUTE/RESERVE/SETTLEMENT/UNKNOWN), `subtype`, `parent_transfer`, `source`, `merchant` (override scoping; must be company-owned). `scope=company` widens scoping from the auth context's primary merchant to all the company's merchants. `expand` accepts comma-separated keys: merchant, merchant_identity, instrument, parent.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["DEBIT","CREDIT","REVERSAL","FEE","ADJUSTMENT","DISPUTE","RESERVE","SETTLEMENT","UNKNOWN"]},"in":"query","name":"type"},{"schema":{"type":"string","enum":["API","APPLICATION_FEE","DISPUTE","MERCHANT_CREDIT","MERCHANT_CREDIT_ADJUSTMENT","MERCHANT_DEBIT","MERCHANT_DEBIT_ADJUSTMENT","PLATFORM_CREDIT","PLATFORM_CREDIT_ADJUSTMENT","PLATFORM_DEBIT","PLATFORM_DEBIT_ADJUSTMENT","PLATFORM_FEE","SETTLEMENT_MERCHANT","SETTLEMENT_NOOP","SETTLEMENT_PARTNER","SETTLEMENT_PLATFORM","SPLIT_PAYOUT","SPLIT_PAYOUT_ADJUSTMENT","SYSTEM"]},"in":"query","name":"subtype"},{"schema":{"type":"string"},"in":"query","name":"parent_transfer"},{"schema":{"type":"string"},"in":"query","name":"source"},{"schema":{"type":"string"},"in":"query","name":"merchant"},{"schema":{"type":"string","enum":["merchant","company"]},"in":"query","name":"scope"},{"schema":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","CANCELED","UNKNOWN","REVERSED","RETURNED"]},"in":"query","name":"state"},{"schema":{"type":"string"},"in":"query","name":"expand"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"SUCCEEDED","identity_id":"IDxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-01-15T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment/{id}":{"get":{"summary":"Get a payment by ID","tags":["payment"],"description":"Retrieve a payment by its ID. `expand` accepts comma-separated keys: merchant, merchant_identity, instrument, parent. `scope=company` widens scoping from the auth context's primary merchant to all the company's merchants.","parameters":[{"schema":{"type":"string"},"in":"query","name":"expand"},{"schema":{"type":"string","enum":["merchant","company"]},"in":"query","name":"scope"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"SUCCEEDED","identity_id":"IDxxxxxxxxxxxxxxxxxx","payment_instrument_id":"PIxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-01-15T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update payment tags","tags":["payment"],"description":"Update the tags of a payment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"object","additionalProperties":true}},"required":["tags"],"example":{"tags":{"order_id":"ord_abc123","customer_type":"premium"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment tags updated","data":{"id":"TRxxxxxxxxxxxxxxxxxx","tags":{"order_id":"ord_abc123","customer_type":"premium"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment/{id}/reversals":{"post":{"summary":"Create a refund (reversal)","tags":["payment"],"description":"Create a reversal (refund) for a succeeded payment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refund_amount":{"type":"integer","exclusiveMinimum":0},"tags":{"type":"object","additionalProperties":{"type":"string"}}},"required":["refund_amount"],"example":{"refund_amount":5000,"tags":{"reason":"customer_request"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Refund created successfully","data":{"id":"TRxxxxxxxxxxxxxxxxxx","type":"REVERSAL","amount":5000,"state":"PENDING","tags":{"reason":"customer_request"},"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-instruments/":{"post":{"summary":"Create a payment instrument (Basis Theory proxy)","tags":["payment-instrument"],"description":"Create a payment instrument from a Basis Theory token. Browser uses the BT SDK to tokenize a card, then sends `{tokenId, identityId, type, ...}` here. The route forwards through the BT proxy to Finix; raw PAN data never touches easy-api.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"tokenId":{"type":"string"},"identityId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["PAYMENT_CARD"]},"name":{"type":"string"},"address":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"postal_code":{"type":"string"},"region":{"type":"string"}},"required":["postal_code"]},"enrollment":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"}},"required":["country","phone"]}},"required":["tokenId","identityId","type","name"]},{"type":"object","properties":{"tokenId":{"type":"string"},"identityId":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"type":{"type":"string","enum":["BANK_ACCOUNT"]},"accountType":{"type":"string","enum":["PERSONAL_CHECKING","PERSONAL_SAVINGS","BUSINESS_CHECKING","BUSINESS_SAVINGS"]},"name":{"type":"string"}},"required":["tokenId","identityId","type","accountType"]}],"example":{"type":"PAYMENT_CARD","tokenId":"tok_abc123","identityId":"IDxxxxxxxxxxxxxxxxxx","name":"John Doe","address":{"postal_code":"94105"},"tags":{"customer_type":"premium"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment instrument created","data":{"id":"PIxxxxxxxxxxxxxxxxxx","identity_id":"IDxxxxxxxxxxxxxxxxxx","instrument_type":"PAYMENT_CARD","type":"PAYMENT_CARD","created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List payment instruments","tags":["payment-instrument"],"description":"List payment instruments scoped to the authenticated company. Optional filters: `identity_id` (single id), `type` (PAYMENT_CARD/BANK_ACCOUNT), `role` (filters via the joined identity's `identity_roles`; values match the `finix_identity_role` DB enum). `include=identity` expands the joined identity row (default: only `company_id` is returned). Reads from the local Finix mirror (no PAN data exposed).","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string","minLength":1},"in":"query","name":"identity_id"},{"schema":{"type":"string","enum":["PAYMENT_CARD","BANK_ACCOUNT"]},"in":"query","name":"type"},{"schema":{"type":"string","enum":["APPLICATION_OWNER","BENEFICIAL_OWNER","BUYER","PLATFORM_OWNER","RECIPIENT","SELLER","SENDER"]},"in":"query","name":"role"},{"schema":{"type":"string","enum":["identity"]},"in":"query","name":"include"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-instruments/{id}":{"get":{"summary":"Get a payment instrument by ID","tags":["payment-instrument"],"description":"Retrieve a single payment instrument's metadata. Scoped to the authenticated company via the identity → company_id chain. `include=identity` expands the joined identity row (default returns only `company_id` from the join).","parameters":[{"schema":{"type":"string","enum":["identity"]},"in":"query","name":"include"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a payment instrument","tags":["payment-instrument"],"description":"Update editable fields (tags, address, etc.) on a payment instrument.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"attempt_bank_account_validation_check":{"type":"boolean"},"account_updater_enabled":{"type":"boolean"},"network_token_enabled":{"type":"boolean"},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["line1","line2","city","region","postal_code","country"]},"verify_payment_card":{"type":"boolean"},"merchant":{"type":"string"},"name":{"type":"string"},"tags":{"type":"object","additionalProperties":true}},"example":{"tags":{"status":"verified"}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment instrument updated","data":{"id":"PIxxxxxxxxxxxxxxxxxx","identity_id":"IDxxxxxxxxxxxxxxxxxx","instrument_type":"PAYMENT_CARD","type":"PAYMENT_CARD","updated_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-link/":{"post":{"summary":"Create a payment link","tags":["payment-link"],"description":"Create a payment link","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":"string"},"amount_type":{"type":"string","enum":["FIXED","VARIABLE"]},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"product_prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"adjustable":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}}},"required":["id","quantity"]},"minItems":1}},"required":["product_prices"]},"default":[]},"min_amount":{"type":"integer","exclusiveMinimum":0},"max_amount":{"type":"integer","exclusiveMinimum":0},"allowed_payment_methods":{"type":"array","items":{"type":"string","enum":["PAYMENT_CARD","BANK_ACCOUNT"]},"minItems":1,"default":["PAYMENT_CARD"]},"payment_limit":{"type":"integer","exclusiveMinimum":0},"payment_frequency":{"type":"string","enum":["ONE_TIME","RECURRING"]},"is_multiple_use":{"type":"boolean"},"collect_buyer_details":{"type":"string","enum":["email","more"],"default":"email"},"branding":{"type":"object","properties":{"brand_color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#ffffff"},"accent_color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#0B5DBC"},"logo":{"type":"string","format":"uri"},"icon":{"type":"string","format":"uri"},"logo_alternative_text":{"type":"string"},"button_font_color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#FFFFFF"}}},"branding_overrides":{"type":["object","null"],"properties":{"logo_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"brand_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]}}},"additional_details":{"type":"object","properties":{"collect_name":{"type":"boolean","default":false},"collect_email":{"type":"boolean","default":true},"collect_phone":{"type":"boolean","default":false},"collect_billing_address":{"type":"boolean","default":false},"collect_shipping_address":{"type":"boolean","default":false},"success_return_url":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"}]},"unsuccessful_return_url":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"}]},"expired_session_url":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"}]},"terms_of_service_url":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"}]},"expiration_in_minutes":{"type":"integer","minimum":1,"maximum":1576800,"default":43200},"send_receipt":{"type":"boolean","default":false},"send_receipt_to_self":{"type":"boolean","default":false},"receipt_destinations":{"type":"array","items":{"type":"string","format":"email"},"maxItems":20}}},"tags":{"type":"object","additionalProperties":{"type":"string"},"default":{}}},"required":["amount_type"],"example":{"nickname":"Premium Widget Payment","amount_type":"FIXED","products":[{"id":"prod_abc123","product_prices":[{"id":"price_abc123","quantity":1,"adjustable":false}]}],"allowed_payment_methods":["PAYMENT_CARD"],"collect_buyer_details":"email","additional_details":{"terms_of_service_url":"https://example.com/terms"}}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment link created","data":{"id":"pl_abc123","url":"https://pay.example.com/pl_abc123","amount_cents":5000,"currency":"USD","status":"ACTIVE","created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List payment links","tags":["payment-link"],"description":"Retrieve a paginated list of payment links scoped to the authenticated company.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"pl_abc123","link_url":"https://pay.example.com/pl_abc123","state":"ACTIVE","nickname":"Premium Widget Payment","created_at":"2026-02-06T12:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-link/{id}":{"get":{"summary":"Retrieve a payment link","tags":["payment-link"],"description":"Retrieve a single payment link by ID. Scoped to the authenticated company.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"pl_abc123","link_url":"https://pay.example.com/pl_abc123","state":"ACTIVE","nickname":"Premium Widget Payment","payment_link_items":[],"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a payment link","tags":["payment-link"],"description":"Update editable fields on a payment link (nickname, state, expiration, etc.). Scoped to the authenticated company. Passing `items` REPLACES the link's product items wholesale (FIXED links only): every `price_id` must belong to the caller's company, `amount_details.total_amount` is recomputed from the new prices, and old items are deleted. Past payments are unaffected — only future charges use the new prices.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"type":["string","null"]},"state":{"type":"string","enum":["DRAFT","ACTIVE","INACTIVE","EXPIRED"]},"link_expires_at":{"type":["string","null"]},"payment_limit":{"type":["integer","null"],"exclusiveMinimum":0},"is_multiple_use":{"type":"boolean"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"additional_details":{"type":["object","null"],"additionalProperties":{}},"branding_overrides":{"type":["object","null"],"additionalProperties":{}},"tags":{"type":["object","null"],"additionalProperties":{}},"items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"adjustable":{"type":"boolean"}},"required":["price_id"]},"minItems":1}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Deactivate a payment link","tags":["payment-link"],"description":"Soft-deletes a payment link by setting state=INACTIVE. To re-activate, call PATCH /:id with state=ACTIVE.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-link/{id}/payments":{"get":{"summary":"List payments for a payment link","tags":["payment-link"],"description":"Retrieve the orders (payment attempts) that were created against this payment link. Includes purchase items per order, plus the linked Finix transfer as a nested `transfer: { id, state, amount, currency } | null` object (null when no transfer exists yet). Scoped to the authenticated company.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"ord_abc123","payment_link_id":"pl_abc123","transfer_id":"TRxxxxxxxxxxxxxxxxxx","total_cents":5000,"currency":"USD","created_at":"2026-02-06T12:00:00.000Z","purchase_items":[{"id":"pi_abc","price_id":"price_abc","quantity":1,"unit_amount_cents":5000,"currency":"USD"}],"transfer":{"id":"TRxxxxxxxxxxxxxxxxxx","state":"SUCCEEDED","amount":5000,"currency":"USD"}}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-methods/{id}/set-default":{"post":{"summary":"Set a payment method as the customer's default","tags":["payment-method"],"description":"Flips `is_default = true` for this customer **at your merchant account only**. Cards can be shared across merchants via Easy Connect, so the default is per-merchant: this never changes which card is default anywhere else, and any prior default of yours for the same customer is cleared in the same operation. Returns 400 if the method is archived at your merchant account.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-methods/{id}/archive":{"post":{"summary":"Soft-delete a payment method","tags":["payment-method"],"description":"Removes the payment method **from your merchant account only**, and clears its default flag there if set. Cards can be shared across merchants via Easy Connect, so this never removes the card from another merchant. Idempotent — calling on an already-archived method returns the existing row. The row itself is preserved, not deleted, so historical transfer joins still resolve.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/payment-methods/{id}":{"patch":{"summary":"Update payment-method display metadata","tags":["payment-method"],"description":"Patch the display metadata on a canonical payment method. Today only `exp_month` / `exp_year` are mutable (for issuer-driven card reissues). Card brand / last4 / type are derived from the underlying Finix PI and not patchable here.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exp_month":{"type":"integer","minimum":1,"maximum":12},"exp_year":{"type":"integer","minimum":2025,"maximum":2100}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/product-prices/":{"get":{"summary":"Get all product prices","tags":["product"],"description":"Retrieve a list of all product prices. Each row embeds the parent product's `default_price_id` (under `products`) and a precomputed `is_default` boolean.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"price_abc123","product_id":"prod_abc123","currency":"USD","unit_amount":2500,"recurring":false,"active":true,"description":"One-time purchase","created_at":"2026-01-01T00:00:00.000Z","is_default":true}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"post":{"summary":"Create a new product price","tags":["product"],"description":"Create a new product price. The target `product_id` must belong to the caller's company in the current environment; otherwise 404.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recurring":{"type":"boolean","default":false},"product_id":{"type":"string","minLength":1},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"unit_amount":{"type":"integer","minimum":0},"interval":{"type":"string","enum":["day","week","month","year"]},"interval_count":{"type":"integer","minimum":1},"pricing_model":{"type":"string","enum":["per_unit","tiered_volume","tiered_graduated","package","metered","flat_rate","customer_defined"]},"package_size":{"type":"integer","exclusiveMinimum":0},"tiers":{"type":"array","items":{"type":"object","properties":{"up_to":{"type":["integer","null"],"exclusiveMinimum":0},"unit_amount":{"type":"integer","minimum":0},"flat_amount":{"type":"integer","minimum":0}},"required":["up_to","unit_amount","flat_amount"]},"minItems":1},"usage_aggregation":{"type":"string","enum":["sum","max","last_during_period","count"]},"tiers_mode":{"type":"string","enum":["graduated","volume"]},"custom_amount_min":{"type":"integer","minimum":0},"custom_amount_max":{"type":"integer","minimum":0},"custom_amount_preset":{"type":"integer","minimum":0},"custom_amount_set_by":{"type":"string","enum":["merchant","buyer"]},"trial_period_days":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":{}},"active":{"type":"boolean"},"description":{"type":"string"}},"required":["product_id"],"example":{"product_id":"prod_abc123","currency":"USD","unit_amount":2500,"recurring":false,"active":true,"description":"One-time purchase"}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product price created","data":{"id":"price_abc123","product_id":"prod_abc123","currency":"USD","unit_amount":2500,"recurring":false,"active":true,"description":"One-time purchase","metadata":{},"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/product-prices/{id}":{"get":{"summary":"Get a product price by ID","tags":["product"],"description":"Retrieve a product price by its ID. The response embeds the parent product's `default_price_id` (under `products`) and a precomputed `is_default` boolean.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"price_abc123","product_id":"prod_abc123","currency":"USD","unit_amount":2500,"recurring":false,"active":true,"description":"One-time purchase","metadata":{},"created_at":"2026-01-01T00:00:00.000Z","is_default":true,"products":{"company_id":"comp_abc123","default_price_id":"price_abc123"}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a product price","tags":["product"],"description":"Update a product price by its ID. Setting `active: false` on the parent product's default price returns 409 DEFAULT_PRICE_CONFLICT, and on a price still referenced by a live payment link/subscription returns 409 PRICE_REFERENCED with `details.references` (same guards as the archive endpoint).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{}},"active":{"type":"boolean"},"description":{"type":"string"}},"example":{"active":true,"description":"Updated description","metadata":{"key":"value"}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product price updated","data":{"id":"price_abc123","product_id":"prod_abc123","active":true,"description":"Updated description","metadata":{"key":"value"},"updated_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/product-prices/{id}/references":{"get":{"summary":"List live references to a product price","tags":["product"],"description":"List every live object that still charges off this price: items on payment links in state ACTIVE/DRAFT (`payment_link`), items on subscriptions whose status is not canceled/incomplete_expired (`subscription`), and legacy Finix subscription plans (`subscription_plan`). Historical purchases are excluded (amounts are snapshotted at charge time). A price with one or more references cannot be archived — repoint each reference first. `item_id` is the join-row id used for repointing (payment_link_items.id / subscription_items.id — the latter goes in PATCH /subscriptions/:id `remove_items`).","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product price references retrieved successfully","data":{"references":[{"type":"payment_link","id":"pl_abc123","name":"Premium Widget Payment","item_id":"pli_abc123","current_price_id":"price_abc123"},{"type":"subscription","id":"sub_abc123","name":"Subscription sub_abc1","item_id":"si_abc123","current_price_id":"price_abc123"}]}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/product-prices/{id}/archive":{"patch":{"summary":"Archive a product price","tags":["product"],"description":"Archive a product price by its ID. Returns 409 DEFAULT_PRICE_CONFLICT if it is the parent product's default price, or 409 PRICE_REFERENCED (with `details.references`) if it is still referenced by a live payment link, subscription, or legacy subscription plan — see GET /:id/references.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product price archived","data":{"id":"price_abc123","active":false,"archived_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/":{"post":{"summary":"Create a new product","tags":["product"],"description":"Create a new product","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{}},"image_url":{"type":"string"},"default_price_id":{"type":"string"},"statement_descriptor":{"type":"string"},"unit_label":{"type":"string"}},"required":["name","active"],"example":{"name":"Premium Widget","description":"A high-quality widget","active":true,"metadata":{},"image_url":"https://example.com/widget.png"}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product created","data":{"id":"prod_abc123","name":"Premium Widget","description":"A high-quality widget","active":true,"metadata":{},"image_url":"https://example.com/widget.png","created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get all products","tags":["product"],"description":"Retrieve a list of products. `status` filters: `active` (active=true, deleted_at IS NULL), `archived` (deleted_at IS NOT NULL — products soft-archived via PATCH /:id/archive), `inactive` (active=false, deleted_at IS NULL — manual deactivation without archiving). `include=prices` expands `prices` from id-only to full price rows.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["active","archived","inactive"]},"in":"query","name":"status"},{"schema":{"type":"string","enum":["prices"]},"in":"query","name":"include"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"prod_abc123","name":"Premium Widget","description":"A high-quality widget","active":true,"metadata":{},"image_url":"https://example.com/widget.png","created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{id}":{"get":{"summary":"Get a product by ID","tags":["product"],"description":"Retrieve a product by its ID. `include=prices` expands `prices` from id-only to full price rows.","parameters":[{"schema":{"type":"string","enum":["prices"]},"in":"query","name":"include"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"prod_abc123","name":"Premium Widget","description":"A high-quality widget","active":true,"metadata":{},"image_url":"https://example.com/widget.png","default_price_id":"price_abc123","created_at":"2026-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a product","tags":["product"],"description":"Update a product by its ID","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{}},"image_url":{"type":["string","null"]},"default_price_id":{"type":"string"},"statement_descriptor":{"type":["string","null"]},"unit_label":{"type":["string","null"]}},"example":{"name":"Updated Widget","description":"An updated high-quality widget"}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product updated","data":{"id":"prod_abc123","name":"Updated Widget","description":"An updated high-quality widget","active":true,"updated_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete a product (soft-delete)","tags":["product"],"description":"Soft-deletes a product by setting `deleted_at` and `active=false`. Use PATCH /:id/restore to undo.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{productId}/prices":{"get":{"summary":"Get all prices for a product","tags":["products"],"description":"Retrieve all price variants for a specific product","parameters":[{"schema":{"type":"string"},"in":"path","name":"productId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"product":{"id":"prod_abc123","name":"Premium Widget"},"prices":[{"id":"price_abc123","unit_amount":2500,"currency":"USD","recurring":false}]}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{productId}/prices/{priceId}":{"get":{"summary":"Get product by product ID and price ID","tags":["products"],"description":"Returns the product (including its `default_price_id`) with the requested price under `price_data`, which carries a precomputed `is_default` boolean.","parameters":[{"schema":{"type":"string"},"in":"path","name":"productId","required":true},{"schema":{"type":"string"},"in":"path","name":"priceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"prod_abc123","name":"Premium Widget","description":"A high-quality widget","default_price_id":"price_abc123","price_data":{"id":"price_abc123","unit_amount":2500,"currency":"USD","recurring":false,"is_default":true}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{id}/archive":{"patch":{"summary":"Archive a product","tags":["product"],"description":"Archive a product by its ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Product archived","data":{"id":"prod_abc123","active":false,"archived_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{id}/restore":{"patch":{"summary":"Restore an archived product","tags":["product"],"description":"Restores a soft-deleted product back to the Active state: atomically clears `deleted_at` AND sets `active = true`.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{id}/unarchive":{"patch":{"summary":"Unarchive a product (atomic)","tags":["product"],"description":"Atomically clears `deleted_at` AND sets `active = true`. Use this instead of `PATCH /:id/restore` followed by `PATCH /:id` with `active: true` — separate calls leave a brief window where the product is restored-but-inactive.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/products/{id}/clone":{"post":{"summary":"Clone a product","tags":["product"],"description":"Duplicates a product (and its prices) into the same or another environment. Cross-environment cloning requires the API key to have access to the target environment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target_environment":{"type":"string","enum":["sandbox","production","live"]}}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/promotion-codes/":{"post":{"summary":"Create promotion code","tags":["promotion-codes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"coupon_id":{"type":"string","format":"uuid"},"code":{"type":"string","minLength":1},"active":{"type":"boolean"},"max_redemptions":{"type":"integer","exclusiveMinimum":0},"valid_until":{"type":"string","format":"date-time"},"first_time_only":{"type":"boolean"},"minimum_amount":{"type":"integer","exclusiveMinimum":0},"metadata":{"type":"object","additionalProperties":{}}},"required":["coupon_id","code"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List promotion codes","tags":["promotion-codes"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/promotion-codes/{id}":{"get":{"summary":"Get promotion code","tags":["promotion-codes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update promotion code","tags":["promotion-codes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete promotion code","tags":["promotion-codes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/promotion-codes/validate":{"post":{"summary":"Validate promotion code","tags":["promotion-codes"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1},"identity_id":{"type":"string"},"amount":{"type":"integer","minimum":0}},"required":["code"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/receipts/":{"post":{"summary":"Create a receipt for a transfer","tags":["receipt"],"description":"Send a buyer-facing receipt for a completed transfer. The referenced transfer must belong to the caller's merchant.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"entity_id":{"type":"string","minLength":1},"send_receipt_to_buyer":{"type":"boolean"},"requested_delivery_methods":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["EMAIL"]},"destinations":{"type":"array","items":{"type":"string","format":"email"},"minItems":1}},"required":["type","destinations"]}}},"required":["entity_id"],"example":{"entity_id":"TRxxxxxxxxxxxxxxxxxx","send_receipt_to_buyer":true,"requested_delivery_methods":[{"type":"EMAIL","destinations":["buyer@example.com"]}]}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/revenue-recovery-automations/":{"get":{"summary":"List revenue recovery automations","tags":["subscriptions"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"post":{"summary":"Create revenue recovery automation","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"trigger_type":{"type":"string","enum":["invoice_due_date_upcoming","invoice_finalized","invoice_overdue","subscription_payment_failed","subscription_canceled"]},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["invoice_amount","invoice_metadata","product_on_invoice"]},"operator":{"type":"string","enum":["more_than","less_than"]},"amount_cents":{"type":"integer","minimum":1},"key":{"type":"string"},"value":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email_team_member","mark_invoice_uncollectible"]},"delay_days":{"type":"integer","minimum":0},"recipient_user_id":{"type":"string"},"recipient_email":{"type":"string","nullable":true},"recipient_name":{"type":"string","nullable":true},"note":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false}},"active":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/revenue-recovery-automations/{id}":{"patch":{"summary":"Update revenue recovery automation","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"trigger_type":{"type":"string","enum":["invoice_due_date_upcoming","invoice_finalized","invoice_overdue","subscription_payment_failed","subscription_canceled"]},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["invoice_amount","invoice_metadata","product_on_invoice"]},"operator":{"type":"string","enum":["more_than","less_than"]},"amount_cents":{"type":"integer","minimum":1},"key":{"type":"string"},"value":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email_team_member","mark_invoice_uncollectible"]},"delay_days":{"type":"integer","minimum":0},"recipient_user_id":{"type":"string"},"recipient_email":{"type":"string","nullable":true},"recipient_name":{"type":"string","nullable":true},"note":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false}},"active":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete revenue recovery automation","tags":["subscriptions"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/revenue-recovery-automations/{id}/runs":{"get":{"summary":"List revenue recovery automation runs","tags":["subscriptions"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/revenue-recovery-automations/{id}/simulate":{"post":{"summary":"Simulate a revenue recovery automation (dry run)","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"test_invoice_id":{"type":"string"},"test_subscription_id":{"type":"string"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/revenue-recovery-config/":{"post":{"summary":"Create or replace revenue recovery config","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"retry_mode":{"type":"string","enum":["smart","custom"]},"smart_retry_attempts":{"type":"integer","enum":[4,8]},"smart_retry_window":{"type":"string","enum":["1_week","2_weeks","3_weeks","1_month","2_months"]},"custom_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":3},"bank_debit_retries_enabled":{"type":"boolean"},"bank_debit_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":2},"subscription_terminal_action":{"type":"string","enum":["cancel","unpaid","past_due","pause"]},"invoice_terminal_action":{"type":"string","enum":["past_due","uncollectible"]},"payment_failed_email_enabled":{"type":"boolean"},"bank_debit_payment_failed_email_enabled":{"type":"boolean"},"email_action_required":{"type":"boolean"},"expiring_card_email_enabled":{"type":"boolean"},"card_expiry_warn_days":{"type":"integer","minimum":1,"maximum":365},"payment_failed_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"payment_failed_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiring_card_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"expiring_card_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_payment_method_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get revenue recovery config","tags":["subscriptions"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Patch revenue recovery config","tags":["subscriptions"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"retry_mode":{"type":"string","enum":["smart","custom"]},"smart_retry_attempts":{"type":"integer","enum":[4,8]},"smart_retry_window":{"type":"string","enum":["1_week","2_weeks","3_weeks","1_month","2_months"]},"custom_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":3},"bank_debit_retries_enabled":{"type":"boolean"},"bank_debit_retry_schedule":{"type":"array","items":{"type":"integer","minimum":1},"minItems":0,"maxItems":2},"subscription_terminal_action":{"type":"string","enum":["cancel","unpaid","past_due","pause"]},"invoice_terminal_action":{"type":"string","enum":["past_due","uncollectible"]},"payment_failed_email_enabled":{"type":"boolean"},"bank_debit_payment_failed_email_enabled":{"type":"boolean"},"email_action_required":{"type":"boolean"},"expiring_card_email_enabled":{"type":"boolean"},"card_expiry_warn_days":{"type":"integer","minimum":1,"maximum":365},"payment_failed_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"payment_failed_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiring_card_recovery_page_mode":{"type":"string","enum":["hosted","custom_link"]},"expiring_card_custom_link_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_payment_method_message":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}},"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]}]}},"/v1/api/sandbox-test-recipients/":{"get":{"summary":"List sandbox test recipients","tags":["sandbox-test-recipients"],"description":"Addresses permitted to receive real mail from this company's sandbox environment.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"post":{"summary":"Add a sandbox test recipient","tags":["sandbox-test-recipients"],"description":"Adds an address and emails it a verification link. The address receives no sandbox mail until verified.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":254}},"required":["email"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/sandbox-test-recipients/resend":{"post":{"summary":"Resend a verification email","tags":["sandbox-test-recipients"],"description":"The recipient id goes in the BODY, not the path. A caller that sends something other than an id — an email address, say — would otherwise write personal data into access logs, referrer headers and every proxy in between, where it long outlives the request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/sandbox-test-recipients/verify":{"get":{"summary":"Verify a sandbox test recipient","tags":["sandbox-test-recipients"],"parameters":[{"schema":{"type":"string","minLength":16,"maxLength":200},"in":"query","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/sandbox-test-recipients/{id}":{"delete":{"summary":"Remove a sandbox test recipient","tags":["sandbox-test-recipients"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/sessions/":{"post":{"summary":"Create a session","tags":["sessions"],"description":"Create a session","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nonce":{"type":"string","minLength":1}},"required":["nonce"],"example":{"nonce":"random-nonce-string-from-client"}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Session created","data":{"id":"sess_abc123","nonce":"random-nonce-string","expires_at":"2026-02-06T13:00:00.000Z","created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/settlements/":{"get":{"summary":"Get settlements","tags":["settlement"],"description":"Retrieve a list of settlements","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"STxxxxxxxxxxxxxxxxxx","status":"PENDING","net_amount":50000,"total_amount":52500,"total_fees":2500,"currency":"USD","transfer_count":25,"created_at":"2026-01-31T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/settlements/{id}":{"get":{"summary":"Get a settlement by ID","tags":["settlement"],"description":"Retrieve a settlement by its ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"STxxxxxxxxxxxxxxxxxx","status":"PENDING","net_amount":50000,"total_amount":52500,"total_fees":2500,"currency":"USD","transfer_count":25,"funding_transfers":[],"created_at":"2026-01-31T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Close a settlement","tags":["settlement"],"description":"Close a settlement by its ID","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Settlement closed","data":{"id":"STxxxxxxxxxxxxxxxxxx","status":"CLOSED","closed_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/settlements/{id}/fund":{"post":{"summary":"Fund a settlement (Finix→Brale instant payout)","tags":["settlement"],"description":"Initiate an instant payout against a settlement. Wraps Finix's `POST /settlements/{id}/funding_transfer_attempts`. The destination must be a payment instrument owned by the authenticated company (debit card, typically a Brale-issued one). `amount` is in cents and cannot exceed the settlement's `net_amount`. This is the Finix→Brale movement that was missing from the API surface — see `tasks/transfer-endpoint-gap.md`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instrument_id":{"type":"string","minLength":1},"amount":{"type":"integer","exclusiveMinimum":0}},"required":["instrument_id","amount"],"example":{"instrument_id":"PIxxxxxxxxxxxxxxxxxx","amount":50000}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-27T00:00:00.000Z","message":"Settlement funding transfer attempt created successfully","data":{"id":"FTRxxxxxxxxxxxxxxxxxx","settlement_id":"STxxxxxxxxxxxxxxxxxx","instrument_id":"PIxxxxxxxxxxxxxxxxxx","amount":50000,"state":"PENDING","created_at":"2026-02-27T00:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscription-plans/":{"post":{"summary":"Create a subscription plan (legacy compatibility)","tags":["subscription-plan"],"description":"Legacy compatibility endpoint for legacy Finix plan APIs. New integrations should use product-first price creation (`/v1/api/product-prices`) plus subscription item setup.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan_name":{"type":"string","minLength":1},"nickname":{"type":"string"},"description":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"billing_interval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","QUARTERLY","SEMI_ANNUALLY","ANNUALLY","YEARLY"]},"product_price_id":{"type":"string","format":"uuid"},"billing_defaults":{"type":"object","properties":{"collection_method":{"type":"string","enum":["BILL_AUTOMATICALLY","SEND_INVOICE"]},"send_invoice":{"type":"boolean"},"send_receipt":{"type":"boolean"}},"required":["collection_method"]},"trial_defaults":{"type":"object","properties":{"interval_type":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"interval_count":{"type":"string"}},"required":["interval_type","interval_count"]},"discount_phase_defaults":{"type":"object","properties":{"amount":{"type":"number"},"billing_interval_count":{"type":"number"}}},"tags":{"type":"object","additionalProperties":{"type":"string"}}},"required":["plan_name","amount","currency","billing_interval"],"example":{"plan_name":"Premium Monthly","amount":2999,"currency":"USD","billing_interval":"MONTHLY","description":"Monthly premium subscription"}}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Subscription plan created","data":{"id":"SPxxxxxxxxxxxxxxxxxx","name":"Premium Monthly","amount":2999,"currency":"USD","billing_interval":"MONTHLY","billing_interval_count":1,"trial_period_days":14,"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get subscription plans (legacy compatibility)","tags":["subscription-plan"],"description":"Legacy compatibility endpoint for legacy Finix plan IDs. New integrations should rely on product/price-first endpoints for recurring setup.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"SPxxxxxxxxxxxxxxxxxx","name":"Premium Monthly","amount":2999,"currency":"USD","billing_interval":"MONTHLY","billing_interval_count":1,"created_at":"2026-01-01T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscription-plans/{id}":{"get":{"summary":"Get a subscription plan by ID (legacy compatibility)","tags":["subscription-plan"],"description":"Legacy compatibility endpoint for legacy Finix plan IDs. `include=prices` joins product_prices linked to the plan via finix_subscription_plan_id (dashboard catalog detail view).","parameters":[{"schema":{"type":"string","enum":["prices"]},"in":"query","name":"include"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"SPxxxxxxxxxxxxxxxxxx","name":"Premium Monthly","amount":2999,"currency":"USD","billing_interval":"MONTHLY","billing_interval_count":1,"trial_period_days":14,"created_at":"2026-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a subscription plan (legacy compatibility)","tags":["subscription-plan"],"description":"Legacy compatibility endpoint for legacy Finix plan records. For new flows, update price-level catalog data instead.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"billing_interval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","QUARTERLY","SEMI_ANNUALLY","ANNUALLY","YEARLY"]},"product_price_id":{"type":"string"},"description":{"type":["string","null"]},"nickname":{"type":["string","null"]},"plan_name":{"type":"string"},"state":{"type":"string","enum":["ACTIVE","INACTIVE"]},"tags":{"type":"object","additionalProperties":{"type":"string"}},"trial_defaults":{"type":"object","properties":{"interval_type":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"interval_count":{"type":"string"}},"required":["interval_type","interval_count"]},"billing_defaults":{"type":"object","properties":{"collection_method":{"type":"string","enum":["BILL_AUTOMATICALLY","SEND_INVOICE"]},"send_invoice":{"type":"boolean"},"send_receipt":{"type":"boolean"}},"required":["collection_method"]}},"example":{"plan_name":"Premium Monthly Updated","amount":3499}}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Subscription plan updated","data":{"id":"SPxxxxxxxxxxxxxxxxxx","name":"Premium Monthly Updated","updated_at":"2026-02-06T12:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/":{"post":{"summary":"Create a subscription","tags":["subscriptions"],"description":"Create a new Easy-native subscription. Requires a trial or instrument_id.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"identity_id":{"type":"string","minLength":1},"instrument_id":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0,"default":1},"custom_amount_cents":{"type":"integer","minimum":0}},"required":["price_id"]},"minItems":1},"proration_behavior":{"type":"string","enum":["create_prorations","none","always_invoice"]},"billing_cycle_anchor":{"type":"string","format":"date-time"},"trial_period_days":{"type":"integer","exclusiveMinimum":0,"maximum":730},"trial_end":{"type":"string","format":"date-time"},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["identity_id","items"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List subscriptions","tags":["subscriptions"],"description":"List all subscriptions with optional filters","parameters":[{"schema":{"type":"string","enum":["incomplete","incomplete_expired","trialing","active","past_due","unpaid","canceled","paused"]},"in":"query","name":"status"},{"schema":{"type":"string"},"in":"query","name":"identity_id"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}":{"get":{"summary":"Get a subscription","tags":["subscriptions"],"description":"Retrieve a subscription with expanded items and prices","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a subscription","tags":["subscriptions"],"description":"Update items, instrument, cancellation schedule, or metadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0,"default":1},"custom_amount_cents":{"type":"integer","minimum":0}},"required":["price_id"]}},"remove_items":{"type":"array","items":{"type":"string","format":"uuid"}},"proration_behavior":{"type":"string","enum":["create_prorations","none","always_invoice"]},"instrument_id":{"type":"string"},"cancel_at_period_end":{"type":"boolean"},"trial_end":{"anyOf":[{"type":"string","enum":["now"]},{"type":"string","format":"date-time"}]},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Cancel a subscription","tags":["subscriptions"],"description":"Cancel immediately (?at_period_end=false default) or at period end","parameters":[{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"at_period_end"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/proration-preview":{"get":{"summary":"Preview proration for subscription updates","tags":["subscriptions"],"description":"Preview proration impact for proposed item changes without applying updates.","parameters":[{"schema":{"type":"string"},"in":"query","name":"items"},{"schema":{"type":"string"},"in":"query","name":"remove_items"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"proration_date"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/pause":{"post":{"summary":"Pause a subscription","tags":["subscriptions"],"description":"Pause payment collection with behavior: void, keep_as_draft, or mark_uncollectible","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"behavior":{"type":"string","enum":["void","keep_as_draft","mark_uncollectible"]},"resumes_at":{"type":"string","format":"date-time"}},"required":["behavior"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/resume":{"post":{"summary":"Resume a subscription","tags":["subscriptions"],"description":"Resume payment collection and process paused-period draft invoices when applicable","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/items":{"post":{"summary":"Add item to subscription","tags":["subscriptions"],"description":"Add a new price item to an existing subscription","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"price_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0,"default":1},"custom_amount_cents":{"type":"integer","minimum":0}},"required":["price_id"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/one-time-charges":{"post":{"summary":"Create one-time charge for subscription","tags":["subscriptions"],"description":"Creates a one-time invoice line item for a subscription without altering recurring items.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"price_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0,"default":1},"description":{"type":"string"},"due_date":{"type":"string","format":"date-time"}},"required":["price_id"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/items/{item_id}":{"patch":{"summary":"Update subscription item quantity","tags":["subscriptions"],"description":"Update the quantity of a subscription line item","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["quantity"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"item_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Remove subscription item","tags":["subscriptions"],"description":"Remove a line item from a subscription (cannot remove the last item)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"item_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/discounts":{"post":{"summary":"Apply discount to subscription","tags":["subscriptions"],"description":"Apply a coupon or promotion code to the subscription or a specific subscription item.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"coupon_id":{"type":"string","format":"uuid"},"promotion_code":{"type":"string","minLength":1},"subscription_item_id":{"type":"string","format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List subscription discounts","tags":["subscriptions"],"description":"List active discounts attached to a subscription.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/discounts/{discount_id}":{"delete":{"summary":"Remove subscription discount","tags":["subscriptions"],"description":"Remove a discount from a subscription.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"discount_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/price-changes":{"post":{"summary":"Schedule a subscription price change","tags":["subscriptions"],"description":"Schedule a merchant-initiated price change for an existing subscriber. The customer is notified by email (with a cancel link) ahead of the effective date; the new price applies at the next renewal on or after effective_at with no mid-cycle proration. effective_at must respect the minimum notice window (default 30 days).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_price_id":{"type":"string","format":"uuid"},"subscription_item_id":{"type":"string","format":"uuid"},"effective_at":{"type":"string","format":"date-time"},"grandfather_all":{"type":"boolean"},"exempt_subscription_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["new_price_id","effective_at"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List scheduled price changes","tags":["subscriptions"],"description":"List scheduled price changes for a subscription, optionally filtered by status.","parameters":[{"schema":{"type":"string","enum":["scheduled","notified","applying","applied","skipped","canceled","failed"]},"in":"query","name":"status"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{id}/price-changes/{change_id}":{"delete":{"summary":"Cancel a scheduled price change","tags":["subscriptions"],"description":"Cancel a scheduled price change while it is still in the 'scheduled' or 'notified' state. Changes that are applying or applied cannot be canceled.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"change_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{subscription_id}/usage":{"post":{"summary":"Report metered usage","tags":["subscriptions"],"description":"Report usage for a metered subscription item. Supports increment and set actions with optional idempotency key.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"subscription_item_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":0},"timestamp":{"type":"string","format":"date-time"},"action":{"type":"string","enum":["increment","set"],"default":"increment"},"idempotency_key":{"type":"string","maxLength":255}},"required":["subscription_item_id","quantity"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"subscription_id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{subscription_id}/usage/summary":{"get":{"summary":"Get usage summary","tags":["subscriptions"],"description":"Aggregate metered usage for the current billing period and return estimated amounts using the pricing engine.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"subscription_item_id"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"as_of"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"subscription_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/subscriptions/{subscription_id}/usage/reconciliation":{"get":{"summary":"Reconcile usage billing for a period","tags":["subscriptions"],"description":"Compare reported usage against billed totals and surface mismatch categories.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"subscription_item_id"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"period_start"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"period_end"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"subscription_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/tax/calculate":{"post":{"summary":"Calculate sales tax","tags":["tax"],"description":"Wave-1 ZIP-level tax calculation with nexus enforcement","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"shipping":{"type":"integer","minimum":0,"default":0},"to_address":{"type":"object","properties":{"zip":{"type":"string","minLength":5},"state":{"type":"string","minLength":2,"maxLength":2}},"required":["zip","state"]},"line_items":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"product_tax_code":{"type":"string","default":"general"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["amount"]},"default":[]},"customer_tax_exempt":{"type":"boolean","default":false}},"required":["to_address"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/test/":{"get":{"summary":"Test","tags":["test"],"description":"Test","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/transfer/":{"post":{"summary":"Create a transfer (deprecated alias)","tags":["transfer"],"description":"**Deprecated** — use `/v1/api/payment` instead. This path is kept for SDK back-compat and will be removed in a future major release. Both paths share the same handlers; only the URL differs.\n\nCharge a customer's payment instrument. Body mirrors Finix's POST /transfers payload. The merchant defaults to the API-key/JWT context but can be overridden for sub-merchant routing.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"source":{"type":"string","minLength":1},"merchant":{"type":"string","minLength":1},"statement_descriptor":{"type":"string","minLength":1,"maxLength":22},"idempotency_id":{"type":"string","minLength":1,"maxLength":64},"tags":{"type":"object","additionalProperties":{}}},"required":["amount","currency","source"],"example":{"amount":5000,"currency":"USD","source":"PIxxxxxxxxxxxxxxxxxx","tags":{"order_id":"ord_abc123"}}}}},"required":true},"deprecated":true,"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment created","data":{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"PENDING","identity_id":"IDxxxxxxxxxxxxxxxxxx","payment_instrument_id":"PIxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get transfers (deprecated alias)","tags":["transfer"],"description":"**Deprecated** — use `/v1/api/payment` instead. This path is kept for SDK back-compat and will be removed in a future major release. Both paths share the same handlers; only the URL differs.\n\nRetrieve a list of payments. Filters: `type` (DEBIT/CREDIT/REVERSAL/FEE/ADJUSTMENT/DISPUTE/RESERVE/SETTLEMENT/UNKNOWN), `subtype`, `parent_transfer`, `source`, `merchant` (override scoping; must be company-owned). `scope=company` widens scoping from the auth context's primary merchant to all the company's merchants. `expand` accepts comma-separated keys: merchant, merchant_identity, instrument, parent.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["DEBIT","CREDIT","REVERSAL","FEE","ADJUSTMENT","DISPUTE","RESERVE","SETTLEMENT","UNKNOWN"]},"in":"query","name":"type"},{"schema":{"type":"string","enum":["API","APPLICATION_FEE","DISPUTE","MERCHANT_CREDIT","MERCHANT_CREDIT_ADJUSTMENT","MERCHANT_DEBIT","MERCHANT_DEBIT_ADJUSTMENT","PLATFORM_CREDIT","PLATFORM_CREDIT_ADJUSTMENT","PLATFORM_DEBIT","PLATFORM_DEBIT_ADJUSTMENT","PLATFORM_FEE","SETTLEMENT_MERCHANT","SETTLEMENT_NOOP","SETTLEMENT_PARTNER","SETTLEMENT_PLATFORM","SPLIT_PAYOUT","SPLIT_PAYOUT_ADJUSTMENT","SYSTEM"]},"in":"query","name":"subtype"},{"schema":{"type":"string"},"in":"query","name":"parent_transfer"},{"schema":{"type":"string"},"in":"query","name":"source"},{"schema":{"type":"string"},"in":"query","name":"merchant"},{"schema":{"type":"string","enum":["merchant","company"]},"in":"query","name":"scope"},{"schema":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","CANCELED","UNKNOWN","REVERSED","RETURNED"]},"in":"query","name":"state"},{"schema":{"type":"string"},"in":"query","name":"expand"}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":[{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"SUCCEEDED","identity_id":"IDxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-01-15T00:00:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/transfer/{id}":{"get":{"summary":"Get a transfer by ID (deprecated alias)","tags":["transfer"],"description":"**Deprecated** — use `/v1/api/payment` instead. This path is kept for SDK back-compat and will be removed in a future major release. Both paths share the same handlers; only the URL differs.\n\nRetrieve a payment by its ID. `expand` accepts comma-separated keys: merchant, merchant_identity, instrument, parent. `scope=company` widens scoping from the auth context's primary merchant to all the company's merchants.","parameters":[{"schema":{"type":"string"},"in":"query","name":"expand"},{"schema":{"type":"string","enum":["merchant","company"]},"in":"query","name":"scope"},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","data":{"id":"TRxxxxxxxxxxxxxxxxxx","amount":5000,"currency":"USD","state":"SUCCEEDED","identity_id":"IDxxxxxxxxxxxxxxxxxx","payment_instrument_id":"PIxxxxxxxxxxxxxxxxxx","tags":{},"created_at":"2026-01-15T00:00:00.000Z","updated_at":"2026-01-15T00:00:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update transfer tags (deprecated alias)","tags":["transfer"],"description":"**Deprecated** — use `/v1/api/payment` instead. This path is kept for SDK back-compat and will be removed in a future major release. Both paths share the same handlers; only the URL differs.\n\nUpdate the tags of a payment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"object","additionalProperties":true}},"required":["tags"],"example":{"tags":{"order_id":"ord_abc123","customer_type":"premium"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Payment tags updated","data":{"id":"TRxxxxxxxxxxxxxxxxxx","tags":{"order_id":"ord_abc123","customer_type":"premium"}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/transfer/{id}/reversals":{"post":{"summary":"Create a refund (deprecated alias)","tags":["transfer"],"description":"**Deprecated** — use `/v1/api/payment` instead. This path is kept for SDK back-compat and will be removed in a future major release. Both paths share the same handlers; only the URL differs.\n\nCreate a reversal (refund) for a succeeded payment.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refund_amount":{"type":"integer","exclusiveMinimum":0},"tags":{"type":"object","additionalProperties":{"type":"string"}}},"required":["refund_amount"],"example":{"refund_amount":5000,"tags":{"reason":"customer_request"}}}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"],"example":{"success":true,"timestamp":"2026-02-06T12:00:00.000Z","message":"Refund created successfully","data":{"id":"TRxxxxxxxxxxxxxxxxxx","type":"REVERSAL","amount":5000,"state":"PENDING","tags":{"reason":"customer_request"},"created_at":"2026-02-06T12:00:00.000Z"}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/transfer-attempts/":{"get":{"summary":"List transfer attempts","tags":["transfer-attempts"],"description":"Every checkout attempt on this company's payment links, newest first. Pass `payment_link_id` to scope to one link. Scoped to the calling company and the current environment.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"payment_link_id"},{"schema":{"type":"string","enum":["PROCESSING","PENDING","SUCCEEDED","FAILED","ABANDONED"]},"in":"query","name":"state"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"is_authorization"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before"},{"schema":{"type":"string","maxLength":200},"in":"query","name":"search"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"post":{"summary":"Open a transfer attempt","tags":["transfer-attempts"],"description":"Records that a buyer has submitted a payment, before any processor call is made. Company and environment come from the caller's context, never the body.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment_link_id":{"type":"string","format":"uuid"},"merchant_id":{"type":"string","minLength":1},"amount":{"type":"integer","minimum":0},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"payment_method":{"type":"string","minLength":1},"is_authorization":{"type":"boolean","default":false}},"required":["payment_link_id","merchant_id","amount","currency","payment_method"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/transfer-attempts/{id}":{"get":{"summary":"Retrieve a transfer attempt","tags":["transfer-attempts"],"description":"One attempt in full: its outcome, the failure detail if it failed, and the transfer, authorization and order it resolved to.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a transfer attempt","tags":["transfer-attempts"],"description":"Records a milestone or finalizes an attempt. Scoped to the calling company and environment, so an attempt belonging to another tenant is not found rather than updated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["PROCESSING","PENDING","SUCCEEDED","FAILED","ABANDONED"]},"identity_id":{"type":"string"},"payment_instrument_id":{"type":"string"},"order_id":{"type":"string","format":"uuid"},"transfer_id":{"type":"string"},"authorization_id":{"type":"string"},"failure_code":{"type":"string"},"failure_message":{"type":"string"},"user_message":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/send":{"post":{"summary":"Initiate a send money operation","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string","format":"uuid"},"amount":{"type":"integer","exclusiveMinimum":0},"source_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"memo":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":2000}},"required":["recipient_id","amount","source_account_id","method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/send/confirm":{"post":{"summary":"Confirm a send operation (with optional 2FA code)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"security_code":{"type":"string","minLength":6,"maxLength":6}},"required":["transaction_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/send/deferred":{"post":{"summary":"Pre-fill a payment attached to a pending recipient invitation","tags":["treasury"],"description":"Creates a payment that stays pending until the invited recipient submits their bank details via POST /recipients/accept-invite, at which point it executes automatically (or falls back to the normal approval flow if security rules require it at that time). Requires an existing, non-expired pending invitation for the recipient (create one first via POST /recipients/:id/invite) — a missing recipient returns 404, but a missing/expired invitation returns 400 (NO_PENDING_INVITATION), not 404, since it's a client-correctable sequencing error rather than a missing resource. A duplicate active deferred send for the same invitation returns 409.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string","format":"uuid"},"amount":{"type":"integer","exclusiveMinimum":0},"source_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"memo":{"type":"string","maxLength":500},"notes":{"type":"string","maxLength":2000}},"required":["recipient_id","amount","source_account_id","method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/send/cancel":{"post":{"summary":"Cancel a pending send operation","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"}},"required":["transaction_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transfer":{"post":{"summary":"Initiate a fund transfer (internal or external)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"source_account_id":{"type":"string","minLength":1},"destination_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"notes":{"type":"string","maxLength":2000}},"required":["amount","source_account_id","destination_account_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transfer/confirm":{"post":{"summary":"Confirm an external transfer (with optional 2FA code)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"security_code":{"type":"string","minLength":6,"maxLength":6}},"required":["transaction_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/deposit/bank-pull":{"post":{"summary":"Pull funds from a linked bank account (ACH)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"destination_account_id":{"type":"string","minLength":1},"source_linked_account_id":{"type":"string","minLength":1},"amount":{"type":"integer","exclusiveMinimum":0},"idempotency_id":{"type":"string","minLength":1,"maxLength":64}},"required":["destination_account_id","source_linked_account_id","amount"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/funding/plaid-link-token":{"get":{"summary":"Create a Brale Plaid Link token for linking a funding bank account","tags":["treasury"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/funding/reauth-link-token":{"post":{"summary":"Create a Plaid update link token to re-authenticate a linked funding bank","tags":["treasury"],"description":"Mints a Brale update link token for the merchant's active funding address. Opening Plaid Link with it runs the streamlined re-auth flow and updates the existing address in place, preserving its address_id.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/funding/register":{"post":{"summary":"Register a Plaid-linked bank account with Brale for ACH funding","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"public_token":{"type":"string","minLength":1},"institution_id":{"type":"string","maxLength":255},"institution_name":{"type":"string","maxLength":255},"account_mask":{"type":"string","maxLength":32},"account_subtype":{"type":"string","maxLength":64}},"required":["public_token"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/funding/automation":{"post":{"summary":"Provision (idempotently) a Brale push-funding automation — a virtual bank account that auto-mints","tags":["treasury"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get the merchant's push-funding automation wire instructions (ACH + wire deposit details)","tags":["treasury"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/withdraw":{"post":{"summary":"Initiate a withdrawal to an external bank","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"source_account_id":{"type":"string","minLength":1},"destination_external_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"notes":{"type":"string","maxLength":2000}},"required":["amount","source_account_id","destination_external_account_id","method"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/withdraw/confirm":{"post":{"summary":"Confirm a withdrawal (with optional 2FA code)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"security_code":{"type":"string","minLength":6,"maxLength":6}},"required":["transaction_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transactions/export":{"get":{"summary":"Export transactions as CSV","tags":["treasury"],"description":"Download a CSV file of transactions matching the provided filters. Capped at 10,000 rows.","parameters":[{"schema":{"type":"string","enum":["send","transfer","deposit","withdraw"]},"in":"query","name":"type"},{"schema":{"type":"string","enum":["pending","initiated","processing","completed","failed","cancelled"]},"in":"query","name":"status"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"date_from"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"date_to"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"amount_min"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"amount_max"},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"keyword"},{"schema":{"type":"string","enum":["date","amount"],"default":"date"},"in":"query","name":"sort_by"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"sort_order"}],"responses":{"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transactions":{"get":{"summary":"List treasury transactions with cursor-based pagination","tags":["treasury"],"description":"Returns paginated transactions with filters for type, status, date range, amount range, and keyword search.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"before"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["send","transfer","deposit","withdraw"]},"in":"query","name":"type"},{"schema":{"type":"string","enum":["pending","initiated","processing","completed","failed","cancelled"]},"in":"query","name":"status"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"date_from"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"date_to"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"from_date"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"to_date"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"amount_min"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"amount_max"},{"schema":{"type":"string","minLength":1,"maxLength":200},"in":"query","name":"keyword"},{"schema":{"type":"string","enum":["date","amount"],"default":"date"},"in":"query","name":"sort_by"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"sort_order"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transactions/{id}":{"get":{"summary":"Get full transaction detail with settlement breakdown","tags":["treasury"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update transaction metadata (category, receipt)","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string","maxLength":100},"receipt_url":{"type":"string","format":"uri","maxLength":2048}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/transactions/{id}/settlement":{"get":{"summary":"Get settlement/fees breakdown for a transaction","tags":["treasury"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/dashboard/summary":{"get":{"summary":"Get treasury dashboard summary","tags":["treasury"],"description":"Returns current balance, last 10 transactions, and period summary (total in/out/net change).","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"in":"query","name":"period_days"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients":{"post":{"summary":"Create a recipient with payment methods","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","format":"email"},"type":{"type":"string","enum":["person","business"],"default":"person"},"payment_methods":{"type":"array","items":{"type":"object","properties":{"method_type":{"type":"string","enum":["ach","wire"]},"routing_number":{"type":"string","pattern":"^\\d{9}$"},"account_number":{"type":"string","minLength":4,"maxLength":17},"account_type":{"type":"string","enum":["checking","savings"]}},"required":["method_type","account_number","account_type"]},"maxItems":5,"default":[]},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["name"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List recipients","tags":["treasury"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","minLength":1},"in":"query","name":"search"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/import":{"post":{"summary":"Bulk import recipients from CSV","tags":["treasury"],"description":"Upload a CSV file with columns: name, email, bank_name, routing_number, account_number, account_type (checking/savings), notes. Each row is validated, account numbers are tokenized via Basis Theory, and duplicates are detected by email or routing+account number. Maximum 1000 rows per batch. Rows that fail tokenization are skipped (fail-closed).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/duplicates":{"get":{"summary":"Detect potential duplicate recipients","tags":["treasury"],"description":"Scans the company's recipients for likely duplicates by exact email, fuzzy name match (Levenshtein distance ≤ 2), and shared bank account (routing + last4). Returns grouped matches with a confidence score (high/medium/low).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/duplicates/dismissed":{"get":{"summary":"List dismissed duplicate pairs","tags":["treasury"],"description":"Returns every recipient pair a user has marked 'not a duplicate' for this company, excluding pairs where either recipient has since been merged/soft-deleted.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/duplicates/dismiss":{"post":{"summary":"Dismiss a specific recipient pair as not a duplicate","tags":["treasury"],"description":"Marks exactly this pair as not a duplicate — does not merge, delete, or otherwise affect either recipient. Future duplicate scans skip this pair entirely, though each recipient can still independently match OTHER recipients. Requires a JWT-authenticated user session.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id_a":{"type":"string","format":"uuid"},"recipient_id_b":{"type":"string","format":"uuid"}},"required":["recipient_id_a","recipient_id_b"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Undo a duplicate-pair dismissal","tags":["treasury"],"description":"Removes a previous dismissal, so this pair can resurface in future duplicate scans. Returns 404 if no dismissal exists for this pair — unlike the POST endpoint's 404 (which means one of the recipients doesn't exist), this endpoint does not re-validate recipient existence, only that a dismissal row is present.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id_a":{"type":"string","format":"uuid"},"recipient_id_b":{"type":"string","format":"uuid"}},"required":["recipient_id_a","recipient_id_b"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/merge":{"post":{"summary":"Merge duplicate recipients into a primary","tags":["treasury"],"description":"Re-points transaction history and payment methods from the duplicate recipients onto the primary, then soft-deletes the duplicates (recording merged_into_id).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"primary_id":{"type":"string","format":"uuid"},"duplicate_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":20}},"required":["primary_id","duplicate_ids"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}":{"get":{"summary":"Get a recipient by ID","tags":["treasury"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a recipient","tags":["treasury"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","format":"email"},"type":{"type":"string","enum":["person","business"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete a recipient","tags":["treasury"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}/payment-methods":{"post":{"summary":"Add a payment method to a recipient","tags":["treasury"],"description":"Adds a bank account (ACH or wire) to an existing recipient. The account number is tokenized via Basis Theory before storage.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"method_type":{"type":"string","enum":["ach","wire"]},"account_type":{"type":"string","enum":["checking","savings"]},"bt_token_id":{"type":"string"},"account_number_last4":{"type":"string","minLength":4,"maxLength":4},"routing_number":{"type":"string","pattern":"^\\d{9}$"},"account_number":{"type":"string","minLength":4,"maxLength":17}},"required":["method_type","account_type"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}/invite":{"post":{"summary":"Send invitation email to a recipient","tags":["treasury"],"description":"Sends a one-time invite email to the recipient so they can self-serve submit their banking details. Revokes any prior pending invitation for the same recipient. Token expires in 72 hours.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/invitations":{"get":{"summary":"List recipient invitations","tags":["treasury"],"description":"Returns all invitations sent by this company, with status and expiry.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["pending","completed","expired"]},"in":"query","name":"status"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/accept-invite":{"post":{"summary":"Accept recipient invitation (public)","tags":["treasury"],"description":"Public endpoint. Validates invitation token, accepts banking details submitted by the recipient, tokenizes account number via Basis Theory, and marks invitation as completed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1},"account_type":{"type":"string","enum":["checking","savings"]},"bank_name":{"type":"string","maxLength":255},"bt_token_id":{"type":"string"},"account_number_last4":{"type":"string","minLength":4,"maxLength":4},"routing_number":{"type":"string","pattern":"^\\d{9}$"},"account_number":{"type":"string","minLength":4,"maxLength":17}},"required":["token","account_type"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/invite/{token}":{"get":{"summary":"Get recipient invitation status (public)","tags":["treasury"],"description":"Public endpoint. Resolves a token to its invitation status (valid/expired/accepted/not_found) and, when valid, the company name and recipient name — used by the accept-invite page to render the correct state and merchant branding before the recipient submits anything. Also returns `payment` — the deferred send attached to the invitation as `{ amount_cents, currency, memo }` — for valid and accepted invitations only, and only while the send has not reached a terminal failure; `null` in every other case. Note that `memo` is merchant-authored and recipient-visible.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/tax-report":{"get":{"summary":"Get tax compliance report for all recipients","tags":["treasury","tax-documents"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":50},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["not_requested","requested","received","expired","verified"]},"in":"query","name":"w9_status"},{"schema":{"type":"boolean"},"in":"query","name":"needs_renewal","description":"Filter recipients whose W-9 expires within 30 days"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}/tax-info":{"post":{"summary":"Update tax information for a recipient","tags":["treasury","tax-documents"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tax_id_type":{"type":"string","enum":["ssn","ein","itin","none"]},"tax_id":{"type":"string","minLength":4,"maxLength":11,"description":"Raw tax ID (SSN/EIN/ITIN). Will be tokenized — never stored raw."},"w9_status":{"type":"string","enum":["not_requested","requested","received","expired","verified"]},"w9_received_at":{"type":"string","format":"date-time"},"w9_expires_at":{"type":"string","format":"date-time"}},"required":["tax_id_type"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"Get tax information for a recipient","tags":["treasury","tax-documents"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}/request-w9":{"post":{"summary":"Send a W-9 request email to a recipient","tags":["treasury","tax-documents"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/plaid/link-token":{"post":{"summary":"Get a Plaid Link token for recipient self-service","tags":["treasury","recipient-plaid"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"invitation_token":{"type":"string","minLength":1}},"required":["invitation_token"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uri","maxLength":2048},"in":"query","name":"redirect_uri"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/plaid/exchange":{"post":{"summary":"Exchange Plaid public token for recipient bank linking","tags":["treasury","recipient-plaid"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"invitation_token":{"type":"string","minLength":1},"public_token":{"type":"string","minLength":1},"account_id":{"type":"string","minLength":1},"institution_name":{"type":"string","maxLength":255},"account_name":{"type":"string","maxLength":255},"account_mask":{"type":"string","maxLength":10}},"required":["invitation_token","public_token","account_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recipients/{id}/auto-pay":{"post":{"summary":"Create auto-pay schedule for a recipient","tags":["treasury","auto-pay"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"frequency":{"type":"string","enum":["one-time","weekly","monthly"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"source_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"memo":{"type":"string","maxLength":500}},"required":["amount","frequency","start_date","source_account_id","method"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/bank-accounts/link-token":{"get":{"summary":"Get a Plaid Link token","tags":["treasury","bank-accounts"],"description":"Returns a short-lived Plaid Link token for initializing the Plaid Link SDK. Must be used promptly. Requires write scope as it initiates the linking flow. Pass redirect_uri (allowlisted server-side) to support OAuth-only institutions.","parameters":[{"schema":{"type":"string","format":"uri","maxLength":2048},"in":"query","name":"redirect_uri"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/bank-accounts/link":{"post":{"summary":"Link a bank account via Plaid","tags":["treasury","bank-accounts"],"description":"Exchanges a Plaid processor token for a Finix payment instrument and persists the linked bank account. Idempotent on finix_instrument_id — re-linking returns the existing record.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plaid_processor_token":{"type":"string","minLength":1},"institution_name":{"type":"string","maxLength":255},"account_name":{"type":"string","maxLength":255},"account_mask":{"type":"string","maxLength":10}},"required":["plaid_processor_token"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/bank-accounts":{"get":{"summary":"List linked bank accounts","tags":["treasury","bank-accounts"],"description":"Returns all active bank accounts linked via Plaid, scoped to current environment and company. Supports pagination.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/bank-accounts/{id}":{"delete":{"summary":"Deactivate a linked bank account","tags":["treasury","bank-accounts"],"description":"Soft-deletes a linked bank account. Record is preserved for audit. Idempotent — deactivating an already-inactive account returns success.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recurring-payments":{"post":{"summary":"Create a recurring payment","tags":["treasury","recurring-payments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string","format":"uuid"},"amount":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","enum":["USD"],"default":"USD"},"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly"]},"source_account_id":{"type":"string","minLength":1},"method":{"type":"string","enum":["wire","ach","same_day_ach","rtp"]},"memo":{"type":"string","maxLength":500}},"required":["recipient_id","amount","frequency","source_account_id","method"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List recurring payments","tags":["treasury","recurring-payments"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["active","paused","cancelled"]},"in":"query","name":"status"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/recurring-payments/{id}":{"get":{"summary":"Get a recurring payment by ID","tags":["treasury","recurring-payments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"patch":{"summary":"Update a recurring payment (pause, resume, cancel, edit)","tags":["treasury","recurring-payments"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"status":{"type":"string","enum":["active","paused","cancelled"]},"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly"]},"memo":{"type":"string","maxLength":500}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Cancel a recurring payment","tags":["treasury","recurring-payments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/auto-transfer-rules":{"post":{"summary":"Create an auto-transfer rule","tags":["treasury","auto-transfer-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rule_type":{"type":"string","enum":["balance_threshold","schedule"]},"trigger_condition":{"type":"object","additionalProperties":{},"description":"Trigger condition configuration"},"transfer_amount":{"type":"integer","exclusiveMinimum":0},"transfer_type":{"type":"string","enum":["internal","external"]},"source_account_id":{"type":"string","minLength":1},"destination_account_id":{"type":"string","minLength":1}},"required":["rule_type","trigger_condition","transfer_amount","transfer_type","source_account_id","destination_account_id"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List auto-transfer rules","tags":["treasury","auto-transfer-rules"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["active","paused"]},"in":"query","name":"status"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/auto-transfer-rules/{id}":{"patch":{"summary":"Update an auto-transfer rule","tags":["treasury","auto-transfer-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"trigger_condition":{"type":"object","additionalProperties":{}},"transfer_amount":{"type":"integer","exclusiveMinimum":0},"status":{"type":"string","enum":["active","paused"]}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete an auto-transfer rule","tags":["treasury","auto-transfer-rules"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/security-rules":{"post":{"summary":"Create a security rule (budget, approval, time restriction)","tags":["treasury","security-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rule_type":{"type":"string","enum":["budget","approval","time_restriction"]},"config":{"type":"object","additionalProperties":{},"description":"Rule configuration (shape depends on rule_type)"},"applies_to_user_id":{"type":["string","null"],"format":"uuid"}},"required":["rule_type","config"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List security rules","tags":["treasury","security-rules"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["budget","approval","time_restriction"]},"in":"query","name":"rule_type"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/security-rules/{id}":{"patch":{"summary":"Update a security rule","tags":["treasury","security-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","additionalProperties":{}},"status":{"type":"string","enum":["active","paused"]},"applies_to_user_id":{"type":["string","null"],"format":"uuid"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete a security rule","tags":["treasury","security-rules"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/security-rules/simulate":{"post":{"summary":"Dry-run a hypothetical transaction against the company's security rules","tags":["treasury","security-rules"],"description":"Evaluates a hypothetical transaction against the company's live, enabled, transaction-subject security rules using the same pure evaluator that gates real payments. Writes nothing — no transaction, approval request, or audit log row is created. Lets a merchant see what a rule would do before turning it on. Note: `method`, `transaction_type`, and `currency` default to concrete values (\"ach\"/\"send\"/\"USD\") here, unlike the live gate's empty-string defaults — an omitted `method` therefore DOES exercise method-scoped rules (as \"ach\"), it does not skip them the way an empty string would under scope's \"empty = any\" matching.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","minimum":0},"method":{"type":"string","default":"ach"},"transaction_type":{"type":"string","default":"send"},"currency":{"type":"string","default":"USD"},"environment":{"type":["string","null"],"default":null},"recipient_id":{"type":["string","null"],"format":"uuid","default":null},"payment_method_id":{"type":["string","null"],"format":"uuid","default":null},"category":{"type":["string","null"],"default":null},"at":{"type":"string","format":"date-time"}},"required":["amount_cents"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/approval-requests":{"post":{"summary":"Create an approval request for a gated transaction","tags":["treasury","security-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","format":"uuid"},"security_rule_id":{"type":"string","format":"uuid"}},"required":["transaction_id","security_rule_id"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/approval-requests/{id}/resolve":{"post":{"summary":"Approve or deny an approval request","tags":["treasury","security-rules"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve","deny"]},"reason":{"type":"string","maxLength":500}},"required":["action"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/payout-links":{"get":{"summary":"List payout links","tags":["treasury","payout-link"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","enum":["active","pending_approval","processing","completed","expired","cancelled","rejected"]},"in":"query","name":"status"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/payout-link/generate":{"post":{"summary":"Generate a shareable payout link","tags":["treasury","payout-link"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","enum":["USD"],"default":"USD"},"recipient_name":{"type":"string","maxLength":255},"memo":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":1000},"expires_in_days":{"type":"integer","minimum":1,"maximum":90},"send_immediately":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/payout-link/{token}":{"get":{"summary":"Get payout link details (public)","tags":["treasury","payout-link"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/payout-link/{token}/submit":{"post":{"summary":"Submit banking details via payout link (public)","tags":["treasury","payout-link"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"email":{"type":"string","format":"email"},"routing_number":{"type":"string","pattern":"^\\d{9}$"},"bt_token_id":{"type":"string","minLength":1},"account_number_last4":{"type":"string","pattern":"^\\d{4}$"},"account_type":{"type":"string","enum":["checking","savings"]},"bank_name":{"type":"string","maxLength":255}},"required":["name","email","routing_number","bt_token_id","account_number_last4","account_type"]}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/payout-links/{token}":{"patch":{"summary":"Deactivate (expire) a payout link","tags":["treasury","payout-link"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["expired"]}},"required":["status"]}}},"required":true},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/categories":{"get":{"summary":"List transaction categories","tags":["treasury","categories"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"post":{"summary":"Create a custom transaction category","tags":["treasury","categories"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"string","maxLength":20}},"required":["name"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/categories/{id}":{"delete":{"summary":"Delete a custom transaction category","tags":["treasury","categories"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/treasury/categories/{id}/usage":{"get":{"summary":"Get usage count for a category","tags":["treasury","categories"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/verifications/":{"post":{"summary":"Trigger a verification run","tags":["verification"],"description":"Triggers a Finix verification run on the authenticated company's merchant. Admin-only. Forwards to Finix POST /merchants/:merchant_id/verifications.","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List verifications","tags":["verification"],"description":"List verification runs recorded for the authenticated merchant. Reads from the local Finix mirror table.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/":{"post":{"summary":"Register a webhook endpoint","tags":["webhooks"],"description":"Register a new webhook endpoint to receive real-time event notifications. The secret is returned only once — store it securely.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","description":"One of: \"*\" (all events), payment.created, payment.updated, refund.created, refund.updated, authorization.created, authorization.updated, subscription.created, subscription.updated, subscription.deleted, subscription.paused, subscription.resumed, subscription.trial_will_end, subscription.pending_update_applied, subscription.price_change.scheduled, subscription.price_change.canceled, subscription.price_change.applied, invoice.created, invoice.finalized, invoice.paid, invoice.payment_failed, invoice.upcoming, invoice.voided, invoice.marked_uncollectible, revenue_recovery.action_completed, coupon.created, coupon.updated, coupon.deleted, promotion_code.created, promotion_code.updated, promotion_code.deleted, customer.created, customer.updated, settlement.created, dispute.created, dispute.updated, checkout.session.completed, checkout.session.crypto_confirmed, test.webhook"},"default":["*"]}},"required":["url"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"get":{"summary":"List webhook endpoints","tags":["webhooks"],"description":"List all webhook endpoints for your company. Secrets are never returned.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/event-types":{"get":{"summary":"List subscribable webhook event types","tags":["webhooks"],"description":"Every event type you can subscribe an endpoint to. This is the catalog the API dispatches from, so it cannot drift from what is actually sent.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/{id}/send-test":{"post":{"summary":"Send a test event to a webhook endpoint","tags":["webhooks"],"description":"Emit a `test.webhook` event so you can verify your endpoint's signature checking and response handling before relying on real events. Delivered through the same queue and signed with the same secrets as any other event, so a successful test proves the real path.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/{id}/rotate-secret":{"post":{"summary":"Rotate a webhook endpoint's signing secret","tags":["webhooks"],"description":"Issue a new signing secret for this endpoint and retire the current one. During the overlap window BOTH secrets verify — deliveries carry one sha256= entry per valid secret, so you can deploy the new one without dropping events. Set overlap_hours to 0 to revoke the old secret immediately, which is what you want if it leaked. The new secret is returned only once.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"overlap_hours":{"type":"integer","minimum":0,"maximum":168,"default":24}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/deliveries":{"get":{"summary":"List webhook deliveries","tags":["webhooks"],"description":"List webhook deliveries for all company endpoints with optional filtering.","parameters":[{"schema":{"type":"string"},"in":"query","name":"event_type"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"in":"query","name":"success"},{"schema":{"type":"integer","exclusiveMinimum":0},"in":"query","name":"attempt"},{"schema":{"type":"integer","exclusiveMinimum":0},"in":"query","name":"attempt_number"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"endpoint_id"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"in":"query","name":"include_counts"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/{id}/deliveries":{"get":{"summary":"List webhook deliveries","tags":["webhooks"],"description":"List delivery attempts for a webhook endpoint with optional filtering.","parameters":[{"schema":{"type":"string"},"in":"query","name":"event_type"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"in":"query","name":"success"},{"schema":{"type":"integer","exclusiveMinimum":0},"in":"query","name":"attempt"},{"schema":{"type":"integer","exclusiveMinimum":0},"in":"query","name":"attempt_number"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_after"},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"created_before"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"in":"query","name":"limit"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/api/webhooks/{id}":{"patch":{"summary":"Update a webhook endpoint","tags":["webhooks"],"description":"Update the webhook URL, subscribed events, or active state.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","description":"One of: \"*\" (all events), payment.created, payment.updated, refund.created, refund.updated, authorization.created, authorization.updated, subscription.created, subscription.updated, subscription.deleted, subscription.paused, subscription.resumed, subscription.trial_will_end, subscription.pending_update_applied, subscription.price_change.scheduled, subscription.price_change.canceled, subscription.price_change.applied, invoice.created, invoice.finalized, invoice.paid, invoice.payment_failed, invoice.upcoming, invoice.voided, invoice.marked_uncollectible, revenue_recovery.action_completed, coupon.created, coupon.updated, coupon.deleted, promotion_code.created, promotion_code.updated, promotion_code.deleted, customer.created, customer.updated, settlement.created, dispute.created, dispute.updated, checkout.session.completed, checkout.session.crypto_confirmed, test.webhook"}},"active":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]},"delete":{"summary":"Delete a webhook endpoint","tags":["webhooks"],"description":"Permanently delete a webhook endpoint.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"apiKey":[]}]}},"/v1/auth/admin/onboarding-complete":{"post":{"summary":"Complete onboarding","tags":["admin"],"description":"Complete onboarding","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string"}},"required":["company_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/admin/link-existing-merchant":{"post":{"summary":"Link an existing Finix merchant + Brale account to a company","tags":["admin"],"description":"Admin/Root only. Links an already-existing Finix merchant and Brale account (both already under our own Finix Application / Brale org) to a company by writing the same fields normal provisioning would: merchant_id, finix_status, brale_account_id, brale_status, primary crypto + payout address ids, plus the finix.identities/merchants + brale_addresses mirror rows. Validates every id against live Finix/Brale before writing; idempotent. Targets the API instance's own environment (sandbox vs live).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid"},"finix_merchant_id":{"type":"string","minLength":1},"brale_account_id":{"type":"string","minLength":1}},"required":["company_id","finix_merchant_id","brale_account_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/admin/companies/{id}/brale-webhook-subscription":{"post":{"summary":"Backfill a company's Brale webhook subscription","tags":["admin"],"description":"Admin/Root only. Idempotently provisions the per-business Brale webhook subscription for the company's current-environment Brale account. Used to backfill merchants created before per-business webhooks existed. No-op when an active subscription already exists.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/attachments/upload":{"post":{"summary":"Upload an attachment","tags":["attachments"],"description":"Multipart upload. Required fields: `file` (binary), `context` (e.g. `treasury_transaction`), `sessionId` (caller-provided grouping key). Limits: 10MB, MIME in {application/pdf, image/jpeg, image/png, image/webp}. Returns `{path, name, size, type, context}`.","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/attachments/sign":{"get":{"summary":"Generate a signed URL for an attachment","tags":["attachments"],"description":"Returns a 1-hour signed URL for the given storage path. Ownership is enforced by checking that the first path segment matches the caller's company_id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"path","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/attachments/":{"delete":{"summary":"Delete an attachment","tags":["attachments"],"description":"Removes an attachment from storage. The first path segment must equal the caller's company_id.","parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"path","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/":{"get":{"summary":"Get company branding","tags":["branding"],"description":"Retrieve the current branding configuration for the authenticated user's company. Always returns fully merged result (EASY_DEFAULTS applied for missing fields). `is_custom: false` means the company has not set any branding yet.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update company branding","tags":["branding"],"description":"Partially update branding for the authenticated user's company. Only provided fields are overwritten. Surface objects (checkout, email, etc.) are field-level merged — you can pass `{ checkout: { button_color: '#...' } }` without affecting other checkout fields. Changes are written to the audit log automatically.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"secondary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"prefer_icon":{"type":"boolean"},"checkout":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"background_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]},"logo_position":{"type":["string","null"],"enum":["top","top-left","hidden"]},"display_mode":{"type":["string","null"],"enum":["embedded","hosted"]},"show_name":{"type":["boolean","null"]}}},"invoice":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"format":{"type":["string","null"],"enum":["pdf","payment_page","both"]},"footer_text":{"type":["string","null"],"maxLength":500},"company_name_override":{"type":["string","null"],"maxLength":100},"company_address_override":{"type":["string","null"],"maxLength":500}}},"email":{"type":"object","properties":{"enabled":{"type":"boolean"},"from_name":{"type":["string","null"],"maxLength":100},"from_email":{"type":["string","null"],"format":"email"},"custom_domain":{"type":["string","null"],"maxLength":255},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"header_text":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"support_email":{"type":["string","null"],"format":"email"},"unsubscribe_link":{"type":"boolean"}}},"customer_portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]},"company_name_override":{"type":["string","null"],"maxLength":100}}},"portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]},"company_name_override":{"type":["string","null"],"maxLength":100}}},"identity":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]}}},"payouts":{"type":"object","properties":{"enabled":{"type":"boolean"},"display_name":{"type":["string","null"],"maxLength":100},"use_global_colors":{"type":"boolean"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"show_name":{"type":["boolean","null"]},"company_address":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"company_name_override":{"type":["string","null"],"maxLength":100},"company_address_override":{"type":["string","null"],"maxLength":500}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/reset-to-defaults":{"post":{"summary":"Reset branding to Easy defaults","tags":["branding"],"description":"Clears all custom branding for the company (sets companies.branding = NULL). The GET endpoint will return EASY_DEFAULTS after this call. A full-clear entry is written to the audit log.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/reset":{"post":{"summary":"Reset branding to Easy defaults (deprecated alias)","tags":["branding"],"description":"@deprecated — use POST /api/auth/branding/reset-to-defaults instead. This alias exists for backward compatibility with FE consumers that call /reset. Behaviour is identical to /reset-to-defaults.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/audit":{"get":{"summary":"Get branding audit log","tags":["branding"],"description":"Returns the last 100 branding change events for this company. Each entry includes the changed_by user, changed_at timestamp, and a field-path diff of what changed.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/fonts/list":{"get":{"summary":"List available fonts","tags":["branding"],"description":"Returns the list of fonts available for branding customization. Each entry includes the font id (used in API), display name, and Google Fonts URL (null for system/native fonts).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/validate":{"post":{"summary":"Validate branding color or logo URL","tags":["branding"],"description":"Validate one or more branding inputs without saving anything. Pass `color` to confirm a hex color is valid. Pass `foreground_color` + `background_color` together to get a WCAG contrast ratio. Pass `logo_url` to verify the URL is reachable and returns an image MIME type. At least one field is required.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"foreground_color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"background_color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/preview/checkout":{"post":{"summary":"Preview checkout branding","tags":["branding"],"description":"Render a server-side HTML snapshot of the checkout surface with the provided (unsaved) branding applied. Pass the current draft branding from the editor. Result is cached for 60 seconds per unique payload.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"secondary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"prefer_icon":{"type":"boolean"},"checkout":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"background_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]},"logo_position":{"type":["string","null"],"enum":["top","top-left","hidden"]},"display_mode":{"type":["string","null"],"enum":["embedded","hosted"]},"show_name":{"type":["boolean","null"]}}},"invoice":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"format":{"type":["string","null"],"enum":["pdf","payment_page","both"]},"footer_text":{"type":["string","null"],"maxLength":500}}},"email":{"type":"object","properties":{"enabled":{"type":"boolean"},"from_name":{"type":["string","null"],"maxLength":100},"from_email":{"type":["string","null"],"format":"email"},"custom_domain":{"type":["string","null"],"maxLength":255},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"header_text":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"support_email":{"type":["string","null"],"format":"email"},"unsubscribe_link":{"type":"boolean"}}},"customer_portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"identity":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]}}},"payouts":{"type":"object","properties":{"enabled":{"type":"boolean"},"display_name":{"type":["string","null"],"maxLength":100},"use_global_colors":{"type":"boolean"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"show_name":{"type":["boolean","null"]},"company_address":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500}}}}},"context":{"type":"object","properties":{"mobile":{"type":"boolean","default":false}},"default":{}}},"required":["branding"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/preview/invoice":{"post":{"summary":"Preview invoice branding","tags":["branding"],"description":"Render a server-side HTML snapshot of the invoice surface. `format` controls whether a payment CTA button is included. Result is cached for 60 seconds per unique payload.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"secondary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"prefer_icon":{"type":"boolean"},"checkout":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"background_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]},"logo_position":{"type":["string","null"],"enum":["top","top-left","hidden"]},"display_mode":{"type":["string","null"],"enum":["embedded","hosted"]},"show_name":{"type":["boolean","null"]}}},"invoice":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"format":{"type":["string","null"],"enum":["pdf","payment_page","both"]},"footer_text":{"type":["string","null"],"maxLength":500}}},"email":{"type":"object","properties":{"enabled":{"type":"boolean"},"from_name":{"type":["string","null"],"maxLength":100},"from_email":{"type":["string","null"],"format":"email"},"custom_domain":{"type":["string","null"],"maxLength":255},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"header_text":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"support_email":{"type":["string","null"],"format":"email"},"unsubscribe_link":{"type":"boolean"}}},"customer_portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"identity":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]}}},"payouts":{"type":"object","properties":{"enabled":{"type":"boolean"},"display_name":{"type":["string","null"],"maxLength":100},"use_global_colors":{"type":"boolean"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"show_name":{"type":["boolean","null"]},"company_address":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500}}}}},"format":{"type":"string","enum":["pdf","payment_page","both"],"default":"payment_page"},"context":{"type":"object","properties":{"mobile":{"type":"boolean","default":false}},"default":{}}},"required":["branding"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/preview/email":{"post":{"summary":"Preview email branding","tags":["branding"],"description":"Render a server-side HTML snapshot of a transactional email with the provided branding. `email_type` controls which email template is shown: receipt | login | invoice (default).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"secondary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"prefer_icon":{"type":"boolean"},"checkout":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"background_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]},"logo_position":{"type":["string","null"],"enum":["top","top-left","hidden"]},"display_mode":{"type":["string","null"],"enum":["embedded","hosted"]},"show_name":{"type":["boolean","null"]}}},"invoice":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"format":{"type":["string","null"],"enum":["pdf","payment_page","both"]},"footer_text":{"type":["string","null"],"maxLength":500}}},"email":{"type":"object","properties":{"enabled":{"type":"boolean"},"from_name":{"type":["string","null"],"maxLength":100},"from_email":{"type":["string","null"],"format":"email"},"custom_domain":{"type":["string","null"],"maxLength":255},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"header_text":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"support_email":{"type":["string","null"],"format":"email"},"unsubscribe_link":{"type":"boolean"}}},"customer_portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"identity":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]}}},"payouts":{"type":"object","properties":{"enabled":{"type":"boolean"},"display_name":{"type":["string","null"],"maxLength":100},"use_global_colors":{"type":"boolean"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"show_name":{"type":["boolean","null"]},"company_address":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500}}}}},"email_type":{"type":"string","enum":["receipt","login","invoice"],"default":"invoice"},"context":{"type":"object","properties":{"mobile":{"type":"boolean","default":false}},"default":{}}},"required":["branding"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/preview/portal":{"post":{"summary":"Preview customer portal branding","tags":["branding"],"description":"Render a server-side HTML snapshot of the customer portal with the provided branding. Supports light / dark / auto themes via `branding.customer_portal.theme`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"secondary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"prefer_icon":{"type":"boolean"},"checkout":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"background_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]},"logo_position":{"type":["string","null"],"enum":["top","top-left","hidden"]},"display_mode":{"type":["string","null"],"enum":["embedded","hosted"]},"show_name":{"type":["boolean","null"]}}},"invoice":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"format":{"type":["string","null"],"enum":["pdf","payment_page","both"]},"footer_text":{"type":["string","null"],"maxLength":500}}},"email":{"type":"object","properties":{"enabled":{"type":"boolean"},"from_name":{"type":["string","null"],"maxLength":100},"from_email":{"type":["string","null"],"format":"email"},"custom_domain":{"type":["string","null"],"maxLength":255},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"header_text":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500},"support_email":{"type":["string","null"],"format":"email"},"unsubscribe_link":{"type":"boolean"}}},"customer_portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"portal":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"show_name":{"type":["boolean","null"]},"company_name":{"type":["string","null"],"maxLength":100},"company_url":{"type":["string","null"],"format":"uri"},"theme":{"type":["string","null"],"enum":["light","dark","auto"]}}},"identity":{"type":"object","properties":{"enabled":{"type":"boolean"},"use_global_colors":{"type":"boolean"},"primary_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]}}},"payouts":{"type":"object","properties":{"enabled":{"type":"boolean"},"display_name":{"type":["string","null"],"maxLength":100},"use_global_colors":{"type":"boolean"},"logo_display":{"type":["string","null"],"enum":["logo","icon","hidden"]},"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"show_name":{"type":["boolean","null"]},"company_address":{"type":["string","null"],"maxLength":500},"footer_text":{"type":["string","null"],"maxLength":500}}}}},"context":{"type":"object","properties":{"mobile":{"type":"boolean","default":false}},"default":{}}},"required":["branding"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/email/verify-domain":{"post":{"summary":"Register custom email sending domain","tags":["branding"],"description":"Register or replace the custom email sending domain for this company. Returns SPF and DKIM DNS records to add. After adding DNS records, use GET to poll verification status. Limited to 5 requests per minute to prevent domain-change spam.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"custom_domain":{"type":"string","pattern":"^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$","minLength":1,"maxLength":255}},"required":["custom_domain"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"get":{"summary":"Get domain verification status","tags":["branding"],"description":"Returns the current email domain verification record for this company. Poll this endpoint after adding DNS records to check if verification has succeeded. Status values: pending | verified | failed.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/email/test":{"post":{"summary":"Send a branding test email","tags":["branding"],"description":"Send a live test email using the company's saved branding settings. The email is rendered with the currently persisted branding (not a draft). Save changes with PATCH /branding before calling this. `email_type` selects the template: receipt | login | invoice (default). Limited to 3 requests per minute per user.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email"},"email_type":{"type":"string","enum":["receipt","login","invoice"],"default":"invoice"}},"required":["to"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/payment-link/{id}":{"get":{"summary":"Get payment link branding override","tags":["branding"],"description":"Returns the effective branding for a payment link using the precedence chain: per-resource override → company branding → EASY_DEFAULTS. `override` is the raw stored override (null if none). `has_override` is true if any override fields are stored.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update payment link branding override","tags":["branding"],"description":"Partially update the branding override for a payment link. Merges with existing override at field level (same semantics as PATCH /branding). Override fields take precedence over company branding. Returns effective branding after update. Alias: `brand_color` → `primary_color` (legacy SDK compatibility).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"logo_url":{"type":["string","null"],"format":"uri"},"favicon_url":{"type":["string","null"],"format":"uri"},"brand_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"button_text_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"font_family":{"type":["string","null"],"enum":["inter","system","georgia","be-vietnam-pro","bitter","chakra-petch","crimson-text","dm-mono","epilogue","exchange","garamond","inconsolata","jetbrains-mono","jost","jura","lato","merriweather","monospace","mont","montserrat","mulish","newsreader","nunito","open-sans","poppins","public-sans","roboto","source-code-pro","space-mono","syne","work-sans"]},"button_border_radius":{"type":["string","null"],"enum":["rectangular","rounded","pill"]}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"Clear payment link branding override","tags":["branding"],"description":"Remove all branding overrides for a payment link. After this call, the link renders with pure company branding (no resource-level overrides). Returns effective branding (= company branding merged with EASY_DEFAULTS).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/branding/invoice/{id}":{"get":{"summary":"Get invoice branding override","tags":["branding"],"description":"Returns the effective branding for an invoice using the precedence chain: per-resource override → company branding → EASY_DEFAULTS. `override` is the raw stored override (null if none). `has_override` is true if any override fields are stored.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update invoice branding override","tags":["branding"],"description":"Partially update the branding override for an invoice. Merges with existing override at field level. Override fields take precedence over company branding. Returns effective branding after update. Alias support (BRD-002b): `company_name_override` → `company_name`, `company_address_override` → `company_address`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":["string","null"],"format":"uri"},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500},"company_name_override":{"type":["string","null"],"maxLength":100},"company_address_override":{"type":["string","null"],"maxLength":500}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"Clear invoice branding override","tags":["branding"],"description":"Remove all branding overrides for an invoice. After this call, the invoice renders with pure company branding. Returns effective branding (= company branding merged with EASY_DEFAULTS).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/checkout-slug/":{"get":{"summary":"Get checkout slug","tags":["checkout-slug"],"description":"Returns the company's checkout slug and the branded URLs ({slug}.easy-checkout.link, {slug}.easy-payment.link, {slug}.easy-portal.link).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update checkout slug","tags":["checkout-slug"],"description":"Update the company's checkout slug. Must be lowercase alphanumeric with hyphens, 1-63 chars, cannot start/end with a hyphen, and must not be reserved.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":63}},"required":["slug"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/comm-prefs/":{"get":{"summary":"Get communication preferences","tags":["comm-prefs"],"description":"Fetch the authenticated user's communication preferences. Response includes current channel values and per-channel policy (locked/lock_reason). Locked channels are forced-on for owner/super-admin roles and cannot be disabled.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update communication preferences","tags":["comm-prefs"],"description":"Partially update communication preferences. Only provided fields are changed. Writes to locked channels return 403 LOCKED_CHANNEL_WRITE. Returns updated values + policy matrix.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email_product_updates":{"type":"boolean"},"email_security_alerts":{"type":"boolean"},"email_billing_notifications":{"type":"boolean"},"email_marketing":{"type":"boolean"},"email_weekly_digest":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/":{"post":{"summary":"Create a new company","tags":["companies"],"description":"This endpoint allows users to create a new company by providing the necessary details in the request body. The request must adhere to the CompaniesPostBody schema. The response includes success or error details based on the request validity and authentication status.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/onboarding-complete":{"post":{"summary":"Complete onboarding","tags":["companies"],"description":"Complete onboarding","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"company_id":{"type":"string"}},"required":["company_id"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/addresses":{"get":{"summary":"Get the authenticated user's company addresses","tags":["companies"],"description":"Returns active treasury addresses for the current environment plus the rolodex of cross-company saved addresses. Replaces the dashboard's direct Supabase reads (Phase 3.2).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/ensure-provisioned":{"get":{"summary":"Ensure company accounts are fully provisioned","tags":["companies"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/search":{"get":{"summary":"Search opt-in companies (rolodex directory)","tags":["companies"],"description":"Phase 3.4. Returns up to 20 companies whose name matches `q` AND have `discoverable=true` AND are brale_status_complete for the active environment. Caller's own company must be brale_status_complete for this env. Excludes the caller's company.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/saved-addresses":{"post":{"summary":"Add a company's primary address to caller's rolodex","tags":["companies"],"description":"Phase 3.4. Server resolves the target company's primary crypto address for the current environment, then inserts into `company_saved_addresses` with the caller's company_id. Writes an audit log entry.","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/discoverable":{"patch":{"summary":"Toggle the caller company's directory discoverability","tags":["companies"],"description":"Phase 3.4. Updates the caller company's `discoverable` flag. When true, the company appears in the rolodex search results (subject to brale_status_complete).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/profile":{"patch":{"summary":"Update the caller company's public Easy-profile fields","tags":["companies"],"description":"Phase 3.4 follow-up. Partial update — only fields present in the body are touched. Passing null (or an empty string) clears a field back to its default (registered `name` for display_name; no bio / no logo for the others). Body: `{display_name?, bio?, logo_url?}`.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/notification-preferences":{"get":{"summary":"List company notification preferences (per-event)","tags":["companies"],"description":"Phase 3.3. Returns rows from `company_notification_events` for the caller's company. Auto-seeds defaults (all events enabled, caller's email as the only recipient) on first read.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Upsert company notification preferences","tags":["companies"],"description":"Phase 3.3. Body: `{events: [{event_name, enabled?, emails?}]}`. Upserts each event row. Returns the full refreshed event list for the company.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/email-settings":{"get":{"summary":"Get email settings (sender identity + sandbox redirect + customizations)","tags":["companies"],"description":"Returns the company's sender identity (from name / from address / reply-to), its sandbox redirect settings, and the array of per-email-type customizations. Coalesced into a single response so the dashboard renders them on one round trip. `sandbox_redirect.resolved` is where unmatched sandbox mail will actually go right now — computed by the same resolver the send path uses — and is null when the setting is off or nothing resolves.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update email sender identity and sandbox redirect","tags":["companies"],"description":"Partial update — only fields present in the body are touched. Passing null clears a field back to the platform default. Sending from a custom address requires domain verification, which is wired separately. A non-null `sandbox_redirect_email` must already be a VERIFIED sandbox test recipient for the company, or the company creator's own login address (which is stored as null so it never goes stale); anything else is rejected with UNVERIFIED_REDIRECT_DESTINATION.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/companies/email-customizations":{"patch":{"summary":"Upsert per-email-type customizations","tags":["companies"],"description":"Body: `{customizations: [{email_type, subject_override?, custom_intro?, custom_footer?, enabled?}]}`. Upserts each entry by (company_id, email_type). Existing fields not present in the patch are preserved. Returns the refreshed customizations for the patched types.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/custom-domains/":{"post":{"summary":"Add a custom domain (dashboard)","tags":["custom-domains-dashboard"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"type":"string","minLength":4,"maxLength":253,"description":"Fully-qualified domain name (e.g. pay.merchant.com)"},"domain_type":{"type":"string","enum":["checkout","payment","portal"],"default":"checkout","description":"Purpose of the custom domain"}},"required":["hostname"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"get":{"summary":"List custom domains (dashboard)","tags":["custom-domains-dashboard"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/custom-domains/{id}":{"delete":{"summary":"Delete custom domain (dashboard)","tags":["custom-domains-dashboard"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/custom-domains/{id}/verify":{"post":{"summary":"Verify custom domain (dashboard)","tags":["custom-domains-dashboard"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"502":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/":{"post":{"summary":"Create a new invoice","tags":["invoices"],"description":"Create a new invoice with line items. Invoice number is auto-generated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"currency":{"type":"string","default":"USD"},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"default":"send_invoice"},"from_company_name":{"type":"string"},"from_email":{"type":"string","format":"email"},"from_address":{"type":"object","additionalProperties":{}},"from_tax_id":{"type":"string"},"from_phone":{"type":"string"},"from_logo_url":{"type":"string","format":"uri"},"to_company_name":{"type":"string"},"to_contact_name":{"type":"string"},"to_email":{"type":"string","format":"email"},"to_address":{"type":"object","additionalProperties":{}},"to_tax_id":{"type":"string"},"to_phone":{"type":"string"},"buyer_id":{"type":"string","format":"uuid"},"tax_rate":{"type":"number","minimum":0,"maximum":100},"discount_amount":{"type":"integer","minimum":0},"discount_type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"due_date":{"type":"string","minLength":1},"issue_date":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"auto_reminders":{"type":"boolean"},"is_recurring":{"type":"boolean"},"recurrence_interval":{"type":"string","enum":["WEEKLY","BIWEEKLY","MONTHLY","QUARTERLY","YEARLY"]},"recurrence_end_date":{"type":"string"},"recurrence_auto_send":{"type":"boolean"},"recurring_parent_id":{"type":"string","format":"uuid"},"template_id":{"type":"string"},"custom_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"value":{"type":"string"}},"required":["name","value"]}},"tax_ids":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string","enum":["merchant","customer"]},"type":{"type":"string","minLength":1},"value":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["type","value"]}},"pdf_page_size":{"type":"string","enum":["LETTER","A4"]},"include_payment_page_link":{"type":"boolean"},"include_pdf_payment_link":{"type":"boolean"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":"string"},"scheduled_finalize_at":{"type":"string"},"scheduled_charge_at":{"type":"string"},"shipping_rate_id":{"type":"string"},"shipping_rate_label":{"type":"string"},"shipping_amount":{"type":"integer","minimum":0},"default_payment_instrument_id":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"unit_price":{"type":"integer","minimum":0},"product_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer","minimum":0},"price_id":{"type":"string"},"coupon_ids":{"type":"array","items":{"type":"string"}},"discountable":{"type":"boolean"},"manual_tax_rate":{"type":"number","minimum":0,"maximum":100},"supply_start_date":{"type":"string"},"supply_end_date":{"type":"string"}},"required":["description","quantity","unit_price"]},"minItems":1},"branding_overrides":{"type":["object","null"],"properties":{"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":["string","null"],"format":"uri"},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500}}}},"required":["to_email","due_date","items"]}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"get":{"summary":"List invoices","tags":["invoices"],"description":"Retrieve invoices with pagination and optional status/date filters.","parameters":[{"schema":{"type":"number","minimum":0},"in":"query","name":"limit"},{"schema":{"type":"number","minimum":0},"in":"query","name":"offset"},{"schema":{"type":"string"},"in":"query","name":"ids"},{"schema":{"type":"string","enum":["DRAFT","OPEN","SENT","VIEWED","OVERDUE","PARTIALLY_PAID","PAID","UNPAID","VOID","VOIDED"]},"in":"query","name":"status"},{"schema":{"type":"string","enum":["charge_automatically","send_invoice"]},"in":"query","name":"collection_method"},{"schema":{"type":"string"},"in":"query","name":"due_date_from"},{"schema":{"type":"string"},"in":"query","name":"due_date_to"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/next-number":{"get":{"summary":"Get next invoice number","tags":["invoices"],"description":"Returns the next sequential invoice number in the canonical `INV-NNN` format for the authenticated company.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}":{"get":{"summary":"Get invoice by ID","tags":["invoices"],"description":"Retrieve a single invoice with all line items.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"patch":{"summary":"Update a draft invoice","tags":["invoices"],"description":"Update an invoice. Only DRAFT invoices can be modified.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_id":{"type":"string"},"currency":{"type":"string","default":"USD"},"collection_method":{"type":"string","enum":["charge_automatically","send_invoice"],"default":"send_invoice"},"from_company_name":{"type":"string"},"from_email":{"type":"string","format":"email"},"from_address":{"type":"object","additionalProperties":{}},"from_tax_id":{"type":"string"},"from_phone":{"type":"string"},"from_logo_url":{"type":"string","format":"uri"},"to_company_name":{"type":"string"},"to_contact_name":{"type":"string"},"to_address":{"type":"object","additionalProperties":{}},"to_tax_id":{"type":"string"},"to_phone":{"type":"string"},"buyer_id":{"type":"string","format":"uuid"},"tax_rate":{"type":"number","minimum":0,"maximum":100},"discount_amount":{"type":"integer","minimum":0},"discount_type":{"type":"string","enum":["FIXED","PERCENTAGE"]},"issue_date":{"type":"string"},"notes":{"type":"string"},"terms":{"type":"string"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"auto_reminders":{"type":"boolean"},"is_recurring":{"type":"boolean"},"recurrence_interval":{"type":"string","enum":["WEEKLY","BIWEEKLY","MONTHLY","QUARTERLY","YEARLY"]},"recurrence_end_date":{"type":"string"},"recurrence_auto_send":{"type":"boolean"},"recurring_parent_id":{"type":"string","format":"uuid"},"template_id":{"type":"string"},"custom_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"value":{"type":"string"}},"required":["name","value"]}},"tax_ids":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string","enum":["merchant","customer"]},"type":{"type":"string","minLength":1},"value":{"type":"string","minLength":1},"label":{"type":"string"}},"required":["type","value"]}},"pdf_page_size":{"type":"string","enum":["LETTER","A4"]},"include_payment_page_link":{"type":"boolean"},"include_pdf_payment_link":{"type":"boolean"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":"string"},"scheduled_finalize_at":{"type":"string"},"scheduled_charge_at":{"type":"string"},"shipping_rate_id":{"type":"string"},"shipping_rate_label":{"type":"string"},"shipping_amount":{"type":"integer","minimum":0},"default_payment_instrument_id":{"type":"string"},"branding_overrides":{"type":["object","null"],"properties":{"header_background":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$"},"logo_url":{"type":["string","null"],"format":"uri"},"company_name":{"type":["string","null"],"maxLength":100},"company_address":{"type":["string","null"],"maxLength":500}}},"to_email":{"type":"string","format":"email"},"due_date":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string","minLength":1},"quantity":{"type":"integer","exclusiveMinimum":0},"unit_price":{"type":"integer","minimum":0},"product_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer","minimum":0},"price_id":{"type":"string"},"coupon_ids":{"type":"array","items":{"type":"string"}},"discountable":{"type":"boolean"},"manual_tax_rate":{"type":"number","minimum":0,"maximum":100},"supply_start_date":{"type":"string"},"supply_end_date":{"type":"string"}},"required":["description","quantity","unit_price"]}}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/send":{"post":{"summary":"Send an invoice","tags":["invoices"],"description":"Send or schedule a request-payment invoice email.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to_email":{"type":"string","format":"email"},"cc_recipients":{"type":"array","items":{"type":"string","format":"email"}},"include_payment_page_link":{"type":"boolean"},"attach_pdf":{"type":"boolean"},"scheduled_send_at":{"type":["string","null"]}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/pay":{"post":{"summary":"Pay an outstanding invoice","tags":["invoices"],"description":"Collect payment for an invoice with a Finix payment instrument.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instrument_id":{"type":"string","minLength":1},"amount":{"type":"integer","exclusiveMinimum":0},"idempotency_key":{"type":"string"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/remind":{"post":{"summary":"Send invoice reminder","tags":["invoices"],"description":"Send a payment reminder for SENT or OVERDUE invoices.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/void":{"post":{"summary":"Void an invoice","tags":["invoices"],"description":"Void an invoice. Cannot void paid invoices.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/pdf":{"get":{"summary":"Get invoice data for PDF","tags":["invoices"],"description":"Returns invoice data as JSON for client-side PDF generation.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/view":{"get":{"summary":"View invoice (public)","tags":["invoices"],"description":"Public endpoint for recipients to view their invoice. Updates last_viewed_at.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/invoices/{id}/pdf/download":{"get":{"summary":"Download invoice PDF (public)","tags":["invoices"],"description":"Public endpoint to download a generated invoice PDF. Returns a redirect to a signed URL.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"302":{"description":"Default Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/login-sessions/":{"get":{"summary":"List active login sessions","tags":["login-sessions"],"description":"Returns all active login sessions for the authenticated user. Automatically registers the current session with device/IP metadata. The current session is flagged with is_current: true.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"delete":{"summary":"Sign out all other sessions","tags":["login-sessions"],"description":"Revokes all login sessions except the current one. The current session remains active. Each revoked session is also signed out via Supabase Admin API (best-effort).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/login-sessions/{id}":{"delete":{"summary":"Revoke a specific login session","tags":["login-sessions"],"description":"Revoke a single session by ID. Cannot revoke the current session (returns 403). The revoked session is also signed out via Supabase Admin API (best-effort).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/me/notification-subscriptions":{"get":{"summary":"List the caller's notification subscriptions","tags":["me"],"description":"Phase 3.3. Returns the events the authenticated user is opted into for their current company (`[{event_name}]`).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]},"put":{"summary":"Replace the caller's notification subscriptions","tags":["me"],"description":"Phase 3.3. Body: `{events: string[]}`. Replaces the entire subscription set for the caller against their current company.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/sandbox/auto-provision":{"post":{"summary":"Auto-provision sandbox environment","tags":["sandbox"],"description":"Auto-provisions a sandbox environment with fake onboarding data, creating a Basis Theory token and enqueuing Brale/Finix account creation. Idempotent — returns success if already provisioned.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","minLength":1,"maxLength":255}},"required":["business_name"]}}},"required":true},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/auth/treasury/transactions/{id}/attachments":{"post":{"summary":"Link uploaded attachments to a treasury transaction","tags":["treasury"],"description":"Persist metadata rows in `transaction_attachments` for files already uploaded via /v1/auth/attachments/upload. Ownership is enforced both per-path (first segment must equal caller's company_id) and per-transaction (transaction must belong to caller's company).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attachments":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"size":{"type":"integer","minimum":0},"type":{"type":"string","minLength":1}},"required":["path","name","size","type"]},"minItems":1}},"required":["attachments"]}}},"required":true},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/webhooks/brale/{token}":{"post":{"summary":"Brale per-business transfer webhook","tags":["brale"],"description":"Per-subscription webhook receiver. The opaque path token resolves to a company's Brale webhook subscription; the request is verified against that subscription's shared secret (transfer.created/completed/canceled/failed, payment.completed, account.verification.*).","parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[]}},"/v1/webhooks/bt/":{"post":{"tags":["basis-theory"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"tenant_id":{"type":"string"},"trace_id":{"type":"string"},"data":{"type":"object","additionalProperties":true}},"required":["id","type","timestamp","tenant_id","trace_id","data"]},"delivered_at":{"type":"string"}},"required":["event","delivered_at"]}}},"required":true},"responses":{"200":{"description":"Default Response"}},"security":[]}},"/v1/webhooks/finix/":{"post":{"summary":"Finix webhook","tags":["finix"],"description":"Webhook for Finix","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"system_generated_idempotency_id":{"type":"string"},"type":{"type":"string","enum":["created","updated","accruing_started","underwritten"]},"entity":{"type":"string"},"occurred_at":{"type":"string"},"_embedded":{"type":"object","properties":{"transfers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","CANCELED","REVERSED","UNKNOWN","RETURNED"]},"type":{"type":"string","enum":["DEBIT","CREDIT","REVERSAL","FEE"]},"source":{"type":["string","null"]},"destination":{"type":["string","null"]},"ready_to_settle_at":{"type":["string","null"]},"statement_descriptor":{"type":["string","null"]},"subtype":{"type":"string","enum":["API","APPLICATION_FEE","DISPUTE","MERCHANT_CREDIT","MERCHANT_CREDIT_ADJUSTMENT","MERCHANT_DEBIT","MERCHANT_DEBIT_ADJUSTMENT","PLATFORM_CREDIT","PLATFORM_CREDIT_ADJUSTMENT","PLATFORM_DEBIT","PLATFORM_DEBIT_ADJUSTMENT","PLATFORM_FEE","SETTLEMENT_MERCHANT","SETTLEMENT_NOOP","SETTLEMENT_PARTNER","SETTLEMENT_PLATFORM","SPLIT_PAYOUT","SPLIT_PAYOUT_ADJUSTMENT","SYSTEM"]},"trace_id":{"type":"string"},"fee":{"type":"number"},"merchant":{"type":"string"},"merchant_identity":{"type":"string"},"fee_profile":{"type":"string"},"operation_key":{"type":["string","null"]},"receipt_last_printed_at":{"type":["string","null"]},"additional_purchase_data":{"type":"null"},"failure_message":{"type":["string","null"]},"additional_buyer_charges":{"type":"null"},"additional_healthcare_data":{"type":"null"},"amount_requested":{"type":"number"},"parent_transfer_trace_id":{"type":["string","null"]},"split_transfers":{"type":["array","null"],"items":{}},"parent_transfer":{"type":["string","null"]},"idempotency_id":{"type":["string","null"]},"failure_code":{"type":["string","null"]},"bank_return_details":{"type":["object","null"],"additionalProperties":{}},"address_verification":{"type":"null"},"security_code_verification":{},"raw":{"type":"null"},"supplemental_fee":{"type":"null"},"externally_funded":{"anyOf":[{"type":"string","enum":["UNKNOWN","FALSE"]},{"type":"string"}]},"messages":{"type":"array","items":{}},"tip_amount":{"type":["number","null"]}},"required":["id","created_at","updated_at","application","amount","currency","state","type","source","destination","ready_to_settle_at","statement_descriptor","trace_id","fee","merchant","merchant_identity","fee_profile","amount_requested","parent_transfer_trace_id","parent_transfer","failure_code","externally_funded","messages"],"additionalProperties":true}},"authorizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"amount":{"type":"number"},"amount_requested":{"type":"number"},"state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","CANCELED","UNKNOWN"]},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"transfer":{"type":["string","null"]},"source":{"type":"string"},"merchant":{"type":"string"},"merchant_identity":{"type":"string"},"void_state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","UNATTEMPTED"]},"capture_state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED","NOT_CAPTURED"]},"receipt_last_printed_at":{"type":["string","null"]},"additional_purchase_data":{"type":"null"},"failure_message":{"type":["string","null"]},"additional_buyer_charges":{"type":"null"},"3ds_redirect_url":{"type":["string","null"]},"additional_healthcare_data":{"type":["object","null"],"properties":{"clinic_account_number":{"type":["number","null"]},"dental_amount":{"type":["number","null"]},"prescription_amount":{"type":["number","null"]},"vision_amount":{"type":["number","null"]}},"required":["clinic_account_number","dental_amount","prescription_amount","vision_amount"]},"expires_at":{"type":"string"},"is_void":{"type":"boolean"},"failure_code":{"type":["string","null"]},"trace_id":{"type":"string"},"address_verification":{"type":"null"},"security_code_verification":{"type":"null"},"raw":{"type":"null"},"idempotency_id":{"type":["string","null"]},"supplemental_fee":{"type":"null"},"messages":{"type":"array","items":{"type":["string","null"]}}},"required":["id","created_at","updated_at","amount","amount_requested","state","currency","transfer","source","merchant","merchant_identity","void_state","receipt_last_printed_at","failure_message","3ds_redirect_url","additional_healthcare_data","expires_at","is_void","failure_code","trace_id","idempotency_id","messages"],"additionalProperties":true}},"disputes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0},"state":{"type":"string","enum":["INQUIRY","PENDING","LOST","WON"]},"reason":{"type":"string","enum":["CLERICAL","FRAUD","INQUIRY","QUALITY","TECHNICAL"]},"message":{"type":["string","null"]},"action":{"type":["string","null"]},"transfer":{"type":"string"},"respond_by":{"type":"string"},"occurred_at":{"type":"string"},"dispute_details":{"type":"null"},"response_state":{"type":"string","enum":["NEEDS_RESPONSE","RESPONDED","ACCEPTED","NO_RESPONSE_ALLOWED","UNKNOWN"]},"identity":{"type":"string"}},"required":["id","created_at","updated_at","amount","state","reason","message","action","transfer","respond_by","occurred_at","identity"],"additionalProperties":true}},"identitys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"type":{"type":"string","enum":["BUSINESS","PERSONAL"]},"identity_roles":{"type":"array","items":{"type":"string","enum":["APPLICATION_OWNER","BENEFICIAL_OWNER","BUYER","PLATFORM_OWNER","RECIPIENT","SELLER","SENDER"]}},"entity":{"type":"object","properties":{"title":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"business_name":{"type":["string","null"]},"business_type":{"type":["string","null"]},"doing_business_as":{"type":["string","null"]},"phone":{"type":["string","null"]},"business_phone":{"type":["string","null"]},"personal_address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["line1","city","region","country","postal_code"],"additionalProperties":true},"business_address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["line1","city","region","country","postal_code"],"additionalProperties":true},"mcc":{"type":["string","null"]},"dob":{"type":["object","null"],"properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":true},"max_transaction_amount":{"type":"number"},"ach_max_transaction_amount":{"type":"number"},"amex_mid":{"type":["string","null"]},"discover_mid":{"type":["string","null"]},"url":{"type":["string","null"]},"annual_card_volume":{"type":"number"},"has_accepted_credit_cards_previously":{"type":"boolean"},"incorporation_date":{"type":["object","null"],"properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":true},"principal_percentage_ownership":{"type":["number","null"]},"short_business_name":{"type":["string","null"]},"ownership_type":{"type":["string","null"]},"tax_authority":{"type":["string","null"]},"tax_id_provided":{"type":"boolean"},"business_tax_id_provided":{"type":"boolean"},"tax_id_fingerprint":{"type":["string","null"]},"business_tax_id_fingerprint":{"type":["string","null"]},"default_statement_descriptor":{"type":["string","null"]}},"required":["title","first_name","last_name","email","business_name","business_type","doing_business_as","phone","business_phone","personal_address","business_address","mcc","dob","max_transaction_amount","ach_max_transaction_amount","amex_mid","discover_mid","url","annual_card_volume","has_accepted_credit_cards_previously","incorporation_date","principal_percentage_ownership","short_business_name","ownership_type","tax_authority","tax_id_provided","business_tax_id_provided","tax_id_fingerprint","business_tax_id_fingerprint","default_statement_descriptor"],"additionalProperties":true}},"required":["id","created_at","updated_at","type","identity_roles","entity"],"additionalProperties":true}},"merchants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"card_expiration_date_required":{"type":"boolean"},"settlement_enabled":{"type":"boolean"},"mid":{"type":["string","null"]},"merchant_name":{"type":"string"},"processing_enabled":{"type":"boolean"},"mcc":{"type":"string"},"processor":{"type":"string"},"creating_transfer_from_report_enabled":{"type":"boolean"},"merchant_profile":{"type":"string"},"card_cvv_required":{"type":"boolean"},"identity":{"type":"string"},"processor_details":{"type":"object","additionalProperties":{}},"onboarding_state":{"type":"string","enum":["PROVISIONING","APPROVED","REJECTED","UPDATE_REQUESTED"]},"verification":{"type":["string","null"]},"gross_settlement_enabled":{"type":"boolean"}},"required":["id","created_at","updated_at","card_expiration_date_required","settlement_enabled","mid","merchant_name","processing_enabled","mcc","processor","creating_transfer_from_report_enabled","merchant_profile","card_cvv_required","identity","processor_details","onboarding_state","verification","gross_settlement_enabled"],"additionalProperties":true}},"instruments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"application":{"type":"string"},"identity":{"type":"string"},"currency":{"type":["string","null"],"enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"country":{"type":["string","null"],"enum":["ABW","AFG","AGO","AIA","ALA","ALB","AND","ARE","ARG","ARM","ASM","ATA","ATF","ATG","AUS","AUT","AZE","BDI","BEL","BEN","BES","BFA","BGD","BGR","BHR","BHS","BIH","BLM","BLR","BLZ","BMU","BOL","BRA","BRB","BRN","BTN","BVT","BWA","CAF","CAN","CCK","CHE","CHL","CHN","CIV","CMR","COD","COG","COK","COL","COM","CPV","CRI","CUB","CUW","CXR","CYM","CYP","CZE","DEU","DJI","DMA","DNK","DOM","DZA","ECU","EGY","ERI","ESH","ESP","EST","ETH","FIN","FJI","FLK","FRA","FRO","FSM","GAB","GBR","GEO","GGY","GHA","GIB","GIN","GLP","GMB","GNB","GNQ","GRC","GRD","GRL","GTM","GUF","GUM","GUY","HKG","HMD","HND","HRV","HTI","HUN","IDN","IMN","IND","IOT","IRL","IRN","IRQ","ISL","ISR","ITA","JAM","JEY","JOR","JPN","KAZ","KEN","KGZ","KHM","KIR","KNA","KOR","KWT","LAO","LBN","LBR","LBY","LCA","LIE","LKA","LSO","LTU","LUX","LVA","MAC","MAF","MAR","MCO","MDA","MDG","MDV","MEX","MHL","MKD","MLI","MLT","MMR","MNE","MNG","MNP","MRT","MSR","MTQ","MUS","MWI","MYS","MYT","NAM","NCL","NER","NFK","NGA","NIC","NIU","NLD","NOR","NPL","NRU","NZL","OMN","PAK","PAN","PCN","PER","PHL","PLW","PNG","POL","PRI","PRK","PRT","PRY","PSE","PYF","QAT","REU","ROU","RUS","RWA","SAU","SDN","SEN","SGP","SGS","SHN","SJM","SLB","SLE","SLV","SMR","SOM","SPM","SRB","SSD","STP","SUR","SVK","SVN","SWE","SWZ","SXM","SYC","SYR","TCA","TCD","TGO","THA","TJK","TKL","TKM","TLS","TON","TTO","TUN","TUR","TUV","TWN","TZA","UGA","UKR","UMI","URY","USA","UZB","VAT","VCT","VEN","VGB","VIR","VNM","VUT","WLF","WSM","XKX","YEM","ZAF","ZMB","ZWE"]},"instrument_type":{"type":"string","enum":["PAYMENT_CARD","BANK_ACCOUNT","TOKEN","APPLE_PAY","GOOGLE_PAY"]},"type":{"type":"string","enum":["PAYMENT_CARD","BANK_ACCOUNT","TOKEN","APPLE_PAY","GOOGLE_PAY"]},"account_type":{"type":["string","null"],"enum":["BUSINESS_CHECKING","BUSINESS_SAVINGS","PERSONAL_CHECKING","PERSONAL_SAVINGS","CHECKING","SAVINGS"]},"bank_code":{"type":["string","null"]},"bank_account_validation_check":{"type":["string","null"],"enum":["INCONCLUSIVE","INVALID","NOT_ATTEMPTED","VALID"]},"masked_account_number":{"type":["string","null"]},"bin":{"type":["string","null"]},"account_updater_enabled":{"type":["boolean","null"]},"third_party_token":{"type":["string","null"]},"enabled":{"type":"boolean"},"issuer_country":{"type":["string","null"]},"last_four":{"type":["string","null"]},"expiration_month":{"type":["number","null"]},"network_token_enabled":{"type":["boolean","null"]},"network_token_state":{"type":["string","null"]},"brand":{"type":["string","null"]},"disabled_code":{"type":["string","null"]},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]}},"required":["line1","line2","city","region","postal_code","country"]},"address_verification":{"type":["string","null"]},"created_via":{"type":["string","null"]},"security_code_verification":{"type":["string","null"]},"disabled_message":{"type":["string","null"]},"card_type":{"type":["string","null"],"enum":["CREDIT","DEBIT","HSA_FSA","NON_RELOADABLE_PREPAID","RELOADABLE_PREPAID","UNKNOWN"]},"expiration_year":{"type":["number","null"]},"name":{"type":["string","null"]},"third_party":{"type":"null"},"fingerprint":{"type":"string"},"institution_number":{"type":["string","null"]},"transit_number":{"type":["string","null"]}},"required":["id","created_at","updated_at","tags","identity","instrument_type","type","enabled","fingerprint"],"additionalProperties":true}},"fees":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"merchant":{"type":"string"},"merchant_identity":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"fee_type":{"type":"string","enum":["ACH_BASIS_POINTS","ACH_CREDIT_RETURN_FIXED_FEE","ACH_DEBIT_RETURN_FIXED_FEE","ACH_FIXED","ACH_MAX_FIXED","ACH_NOTICE_OF_CHANGE_CREDIT_FIXED","ACH_NOTICE_OF_CHANGE_DEBIT_FIXED","AMERICAN_EXPRESS_ASSESSMENT_BASIS_POINTS","AMERICAN_EXPRESS_BASIS_POINTS","AMERICAN_EXPRESS_FIXED","AMERICAN_EXPRESS_INTERCHANGE","ANCILLARY_FIXED_FEE_PRIMARY","ANCILLARY_FIXED_FEE_SECONDARY","APPLICATION_FEE","CARD_BASIS_POINTS","CARD_FIXED","CARD_INTERCHANGE","CUSTOM","DINERS_CLUB_BASIS_POINTS","DINERS_CLUB_FIXED","DINERS_CLUB_INTERCHANGE","DISCOVER_ASSESSMENT_BASIS_POINTS","DISCOVER_BASIS_POINTS","DISCOVER_DATA_USAGE_FIXED","DISCOVER_FIXED","DISCOVER_INTERCHANGE","DISCOVER_NETWORK_AUTHORIZATION_FIXED","DISPUTE_FIXED_FEE","DISPUTE_INQUIRY_FIXED_FEE","EFT_MAX_FIXED","JCB_BASIS_POINTS","JCB_FIXED","JCB_INTERCHANGE","MASTERCARD_ACQUIRER_FEE_BASIS_POINTS","MASTERCARD_ASSESSMENT_OVER_1K_BASIS_POINTS","MASTERCARD_ASSESSMENT_UNDER_1K_BASIS_POINTS","MASTERCARD_BASIS_POINTS","MASTERCARD_FIXED","MASTERCARD_INTERCHANGE","QUALIFIED_TIER_BASIS_POINTS_FEE","QUALIFIED_TIER_FIXED_FEE","SETTLEMENT_FUNDING_TRANSFER_ACH_BASIS_POINTS","SETTLEMENT_FUNDING_TRANSFER_ACH_CREDIT_RETURN_FIXED","SETTLEMENT_FUNDING_TRANSFER_ACH_DEBIT_RETURN_FIXED","SETTLEMENT_FUNDING_TRANSFER_ACH_FIXED","SETTLEMENT_FUNDING_TRANSFER_ACH_MAX_FIXED","SETTLEMENT_FUNDING_TRANSFER_EFT_BASIS_POINTS","SETTLEMENT_FUNDING_TRANSFER_EFT_CREDIT_RETURN_FIXED","SETTLEMENT_FUNDING_TRANSFER_EFT_DEBIT_RETURN_FIXED","SETTLEMENT_FUNDING_TRANSFER_EFT_FIXED","SETTLEMENT_FUNDING_TRANSFER_EFT_MAX_FIXED","SETTLEMENT_FUNDING_TRANSFER_INSTANT_PAYOUT_CARD_BASIS_POINTS","SETTLEMENT_FUNDING_TRANSFER_INSTANT_PAYOUT_CARD_FIXED","SETTLEMENT_FUNDING_TRANSFER_INSTANT_PAYOUT_CARD_MAX_FIXED","SETTLEMENT_FUNDING_TRANSFER_NOC_CREDIT_FIXED","SETTLEMENT_FUNDING_TRANSFER_NOC_DEBIT_FIXED","SETTLEMENT_FUNDING_TRANSFER_SAME_DAY_ACH_BASIS_POINTS","SETTLEMENT_FUNDING_TRANSFER_SAME_DAY_ACH_FIXED","SETTLEMENT_FUNDING_TRANSFER_SAME_DAY_ACH_MAX_FIXED","SETTLEMENT_V2_TRANSFER","SUBSCRIPTION_ACH_BASIS_POINTS","SUBSCRIPTION_ACH_FIXED","SUBSCRIPTION_ACH_MAX_FIXED","SUBSCRIPTION_CARD_BASIS_POINTS","SUBSCRIPTION_CARD_FIXED","SUBSCRIPTION_EFT_BASIS_POINTS","SUBSCRIPTION_EFT_FIXED","SUBSCRIPTION_EFT_MAX_FIXED","SUPPLEMENTAL_FEE_FIXED","VISA_ACQUIRER_PROCESSING_FIXED","VISA_ASSESSMENT_BASIS_POINTS","VISA_BASE_II_CREDIT_VOUCHER_FIXED","VISA_BASE_II_SYSTEM_FILE_TRANSMISSION_FIXED","VISA_BASIS_POINTS","VISA_CREDIT_VOUCHER_FIXED","VISA_FIXED","VISA_INTERCHANGE","VISA_KILOBYTE_ACCESS_FIXED"]},"category":{"type":"string","enum":["PROCESSOR","INTERCHANGE","DUES_AND_ASSESSMENTS","THIRD_PARTY_SERVICE_PROVIDER"]},"fee_subtype":{"type":"string","enum":["CUSTOM","APPLICATION_FEE","PLATFORM_FEE"]},"linked_type":{"type":"string","enum":["TRANSFER","AUTHORIZATION"]},"linked_id":{"type":"string"},"linked_to":{"type":"string"},"display_name":{"type":["string","null"]},"label":{"type":["string","null"]},"type":{"type":"string"},"subtype":{"type":"string"},"state":{"type":"string"}},"required":["id","amount","currency","merchant","fee_type","category","fee_subtype","linked_type","linked_to"],"additionalProperties":true}},"settlements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"total_amount":{"type":["number","null"]},"total_fee":{"type":["number","null"]},"total_fees":{"type":["number","null"]},"net_amount":{"type":["number","null"]},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"merchant_id":{"type":"string"},"merchant":{"type":"string"},"identity":{"type":"string"},"application":{"type":"string"},"processor":{"type":["string","null"]},"processor_type":{"type":["string","null"]},"type":{"type":"string","enum":["MERCHANT_REVENUE","PLATFORM_FEE","PARTNER_FEE","NOOP","MERCHANT","APPLICATION","PLATFORM"]},"destination":{"type":["null","null"]},"payment_type":{"type":["string","null","null"]},"funds_flow":{"type":["string","null","null"]},"status":{"type":"string","enum":["APPROVED","AWAITING_APPROVAL","REJECTED","PENDING"]},"adjustment_credit_amount":{"type":["number","null"]},"adjustment_credit_count":{"type":["number","null"]},"adjustment_debit_amount":{"type":["number","null"]},"adjustment_debit_count":{"type":["number","null"]},"auto_close_time":{"type":["string","null"]},"dispute_credit_amount":{"type":["number","null"]},"dispute_credit_count":{"type":["number","null"]},"dispute_debit_amount":{"type":["number","null"]},"dispute_debit_count":{"type":["number","null"]},"exception":{"type":["boolean","null"]},"externally_funded_amount":{"type":["number","null"]},"externally_funded_count":{"type":["number","null"]},"fee_count":{"type":["number","null"]},"finix_fee_count":{"type":["number","null"]},"payout_plan":{"type":["string","null"]},"reverse_amount":{"type":["number","null"]},"reverse_count":{"type":["number","null"]},"schedule_type":{"type":["string","null"]},"settlement_group":{"type":["string","null"]},"split_count":{"type":["number","null"]},"total_fee_amount":{"type":["number","null"]},"total_finix_fee_amount":{"type":["number","null"]},"total_split_amount":{"type":["number","null"]},"transfer_credit_amount":{"type":["number","null"]},"transfer_credit_count":{"type":["number","null"]},"transfer_debit_amount":{"type":["number","null"]},"transfer_debit_count":{"type":["number","null"]},"window_end":{"type":["string","null"]},"window_start":{"type":["string","null"]},"ready_to_settle_at":{"type":["string","null"]},"tags":{"type":"object","additionalProperties":{},"default":{}}},"required":["id","created_at","updated_at","currency","merchant_id","identity","application","type","status"],"additionalProperties":true}},"verifications":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"trace_id":{"type":"string"},"payment_instrument":{"type":["string","null"]},"merchant":{"type":"string"},"merchant_identity":{"type":"string"},"type":{"type":["string","null"],"enum":["PAYMENT_INSTRUMENT","MERCHANT","IDENTITY"]},"processor":{"type":"string"},"outcome_summary":{"type":["string","null"]},"outcomes":{"type":["array","null"],"items":{"type":"object","properties":{"outcome_code":{"type":"string","enum":["FINANCIAL_HISTORY","HIGH_RISK","INCOMPLETE_APPLICATION","INSUFFICIENT_BUSINESS_HISTORY","MATCH_LIST_DECLINE","OFAC_DECLINE","POTENTIAL_FRAUD","UNSUPPORTED_BUSINESS","OTHER"]},"remediation_details":{"type":["object","null"],"properties":{"type":{"type":"string"},"field_name":{"type":"string"},"file_type":{"type":"string"},"entity_type":{"type":"string"},"entity_id":{"type":"string"}},"required":["type","entity_type","entity_id"]}},"required":["outcome_code","remediation_details"]}},"identity":{"type":["string","null"]},"messages":{"type":"array","items":{"type":"string"}},"payment_instrument_verification_details":{"type":["object","null"],"properties":{"push_to_card_domestic":{"type":["string","null"]},"push_to_card_cross_border":{"type":["string","null"]},"card_type":{"type":["string","null"]},"billing_currency":{"type":["string","null"]},"issuer_country":{"type":"string"}},"required":["push_to_card_domestic","push_to_card_cross_border","card_type","billing_currency","issuer_country"],"additionalProperties":true},"state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"]}},"required":["id","created_at","updated_at","trace_id","payment_instrument","merchant","merchant_identity","type","processor","outcome_summary","outcomes","identity","messages","payment_instrument_verification_details","state"],"additionalProperties":true}},"compliance_forms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"status":{"type":"string","enum":["PENDING","COMPLETED"]},"merchant_id":{"type":"string"},"form_type":{"type":"string"},"completed_at":{"type":"string"}},"required":["id","created_at","updated_at","status","merchant_id","form_type"],"additionalProperties":true}},"merchant_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"fee_profile":{"type":["string","null"]},"risk_profile":{"type":["string","null"]}},"required":["id","created_at","updated_at","fee_profile","risk_profile"],"additionalProperties":true}},"risk_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"merchant":{"type":"string"},"profile_type":{"type":"string"},"risk_rating":{"type":"string"},"status":{"type":"string"},"avs_failure_allowed":{"type":"boolean"},"csc_failure_allowed":{"type":"boolean"}},"required":["id","created_at","updated_at"],"additionalProperties":true}},"fee_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"application":{"type":"string"},"ach_basis_points":{"type":["number","null"]},"ach_basis_points_fee_limit":{"type":["number","null"]},"ach_credit_return_fixed_fee":{"type":["number","null"]},"ach_debit_return_fixed_fee":{"type":["number","null"]},"ach_fixed_fee":{"type":["number","null"]},"ach_notice_of_change_credit_fixed_fee":{"type":["number","null"]},"ach_notice_of_change_debit_fixed_fee":{"type":["number","null"]},"american_express_assessment_basis_points":{"type":["number","null"]},"american_express_basis_points":{"type":["number","null"]},"american_express_charge_dues_assessments":{"type":["number","null"]},"american_express_charge_interchange":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"null"}]},"american_express_externally_funded_basis_points":{"type":["number","null"]},"american_express_externally_funded_fixed_fee":{"type":["number","null"]},"american_express_fixed_fee":{"type":["number","null"]},"ancillary_fixed_fee_primary":{"type":["number","null"]},"ancillary_fixed_fee_secondary":{"type":["number","null"]},"basis_points":{"type":["number","null"]},"card_cross_border_basis_points":{"type":["number","null"]},"card_cross_border_fixed_fee":{"type":["number","null"]},"charge_dues_assessments":{"type":["boolean","null"]},"charge_interchange":{"type":["boolean","null"]},"compliance_forms_overdue_fixed_fee":{"type":["number","null"]},"diners_club_basis_points":{"type":["number","null"]},"diners_club_charge_interchange":{"type":["boolean","null"]},"diners_club_fixed_fee":{"type":["number","null"]},"discover_assessments_basis_points":{"type":["number","null"]},"discover_basis_points":{"type":["number","null"]},"discover_charge_dues_assessments":{"type":["number","null"]},"discover_charge_interchange":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"null"}]},"discover_data_usage_fixed_fee":{"type":["number","null"]},"discover_externally_funded_basis_points":{"type":["number","null"]},"discover_externally_funded_fixed_fee":{"type":["number","null"]},"discover_fixed_fee":{"type":["number","null"]},"discover_network_authorization_fixed_fee":{"type":["number","null"]},"dispute_fixed_fee":{"type":["number","null"]},"dispute_inquiry_fixed_fee":{"type":["number","null"]},"eft_basis_points":{"type":["number","null"]},"eft_basis_points_fee_limit":{"type":["number","null"]},"eft_credit_return_fixed_fee":{"type":["number","null"]},"eft_debit_return_fixed_fee":{"type":["number","null"]},"eft_fixed_fee":{"type":["number","null"]},"externally_funded_basis_points":{"type":["number","null"]},"externally_funded_fixed_fee":{"type":["number","null"]},"fixed_fee":{"type":["number","null"]},"gross_monthly_fees_ach_basis_points":{"type":["number","null"]},"gross_monthly_fees_ach_fixed_fee":{"type":["number","null"]},"gross_monthly_fees_card_basis_points":{"type":["number","null"]},"gross_monthly_fees_card_fixed_fee":{"type":["number","null"]},"gross_monthly_fees_eft_basis_points":{"type":["number","null"]},"gross_monthly_fees_eft_fixed_fee":{"type":["number","null"]},"interac_basis_points":{"type":["number","null"]},"interac_fixed_fee":{"type":["number","null"]},"jcb_basis_points":{"type":["number","null"]},"jcb_charge_interchange":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"null"}]},"jcb_fixed_fee":{"type":["number","null"]},"mastercard_acquirer_fees_basis_points":{"type":["number","null"]},"mastercard_assessments_over1k_basis_points":{"type":["number","null"]},"mastercard_assessments_under1k_basis_points":{"type":["number","null"]},"mastercard_basis_points":{"type":["number","null"]},"mastercard_charge_dues_assessments":{"type":["number","null"]},"mastercard_charge_interchange":{"type":["boolean","null"]},"mastercard_fixed_fee":{"type":["number","null"]},"qualified_tiers":{"type":["object","null"],"additionalProperties":{}},"rounding_mode":{"type":["string","null"]},"settlement_funding_transfer_ach_basis_points":{"type":["number","null"]},"settlement_funding_transfer_ach_basis_points_fee_limit":{"type":["number","null"]},"settlement_funding_transfer_ach_credit_return_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_ach_debit_return_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_ach_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_eft_basis_points":{"type":["number","null"]},"settlement_funding_transfer_eft_basis_points_fee_limit":{"type":["number","null"]},"settlement_funding_transfer_eft_credit_return_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_eft_debit_return_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_eft_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_instant_payout_card_basis_points":{"type":["number","null"]},"settlement_funding_transfer_instant_payout_card_basis_points_fee_limit":{"type":["number","null"]},"settlement_funding_transfer_instant_payout_card_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_noc_credit_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_noc_debit_fixed_fee":{"type":["number","null"]},"settlement_funding_transfer_same_day_ach_basis_points":{"type":["number","null"]},"settlement_funding_transfer_same_day_ach_basis_points_fee_limit":{"type":["number","null"]},"settlement_funding_transfer_same_day_ach_fixed_fee":{"type":["number","null"]},"subscription_ach_basis_points":{"type":["number","null"]},"subscription_ach_basis_points_fee_limit":{"type":["number","null"]},"subscription_ach_fixed_fee":{"type":["number","null"]},"subscription_card_basis_points":{"type":["number","null"]},"subscription_card_fixed_fee":{"type":["number","null"]},"subscription_eft_basis_points":{"type":["number","null"]},"subscription_eft_basis_points_fee_limit":{"type":["number","null"]},"subscription_eft_fixed_fee":{"type":["number","null"]},"tags":{"type":["object","null"],"additionalProperties":{}},"visa_acquirer_processing_fixed_fee":{"type":["number","null"]},"visa_assessments_basis_points":{"type":["number","null"]},"visa_base_II_credit_voucher_fixed_fee":{"type":["number","null"]},"visa_base_II_system_file_transmission_fixed_fee":{"type":["number","null"]},"visa_basis_points":{"type":["number","null"]},"visa_charge_dues_assessments":{"type":["number","null"]},"visa_charge_interchange":{"type":["boolean","null"]},"visa_credit_voucher_fixed_fee":{"type":["number","null"]},"visa_fixed_fee":{"type":["number","null"]},"visa_kilobyte_access_fixed_fee":{"type":["number","null"]}},"required":["id","application"],"additionalProperties":true}},"evidences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":["object","null"],"properties":{"file-extension":{"type":"string"},"content-type":{"type":"string"},"file-name":{"type":"string"}},"required":["file-extension","content-type","file-name"],"additionalProperties":true},"application":{"type":"string"},"dispute":{"type":"string"},"state":{"type":"string","enum":["PENDING","SUCCEEDED"]}},"required":["id","created_at","updated_at","dispute","state"],"additionalProperties":true}},"balance_transfers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"amount":{"type":"number"},"processor_type":{"type":"string"},"reference_id":{"type":"string"},"destination":{"type":"string","enum":["OPERATING_ACCOUNT","FOR_BENEFIT_OF_ACCOUNT"]},"source":{"type":"string","enum":["OPERATING_ACCOUNT","FOR_BENEFIT_OF_ACCOUNT"]},"description":{"type":"string"},"external_reference_id":{"type":"string"},"currency":{"type":"string"},"state":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"]}},"required":["id","created_at","updated_at","amount","processor_type","reference_id","destination","source","description","external_reference_id","currency","state"],"additionalProperties":true}},"onboarding_forms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{},"default":{}},"application":{"type":"string"},"completed_at":{"type":"string"},"application_id":{"type":"string"},"merchant_processors":{"type":"array","items":{"type":"object","properties":{"processor":{"type":"string"}},"required":["processor"],"additionalProperties":true}},"onboarding_data":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"type":{"type":"string","enum":["BUSINESS","PERSONAL"]},"identity_roles":{"type":"array","items":{"type":"string","enum":["APPLICATION_OWNER","BENEFICIAL_OWNER","BUYER","PLATFORM_OWNER","RECIPIENT","SELLER","SENDER"]}},"entity":{"type":"object","properties":{"title":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"business_name":{"type":["string","null"]},"business_type":{"type":["string","null"]},"doing_business_as":{"type":["string","null"]},"phone":{"type":["string","null"]},"business_phone":{"type":["string","null"]},"personal_address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["line1","city","region","country","postal_code"],"additionalProperties":true},"business_address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["line1","city","region","country","postal_code"],"additionalProperties":true},"mcc":{"type":["string","null"]},"dob":{"type":["object","null"],"properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":true},"max_transaction_amount":{"type":"number"},"ach_max_transaction_amount":{"type":"number"},"amex_mid":{"type":["string","null"]},"discover_mid":{"type":["string","null"]},"url":{"type":["string","null"]},"annual_card_volume":{"type":"number"},"has_accepted_credit_cards_previously":{"type":"boolean"},"incorporation_date":{"type":["object","null"],"properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"],"additionalProperties":true},"principal_percentage_ownership":{"type":["number","null"]},"short_business_name":{"type":["string","null"]},"ownership_type":{"type":["string","null"]},"tax_authority":{"type":["string","null"]},"tax_id_provided":{"type":"boolean"},"business_tax_id_provided":{"type":"boolean"},"tax_id_fingerprint":{"type":["string","null"]},"business_tax_id_fingerprint":{"type":["string","null"]},"default_statement_descriptor":{"type":["string","null"]}},"required":["title","first_name","last_name","email","business_name","business_type","doing_business_as","phone","business_phone","personal_address","business_address","mcc","dob","max_transaction_amount","ach_max_transaction_amount","amex_mid","discover_mid","url","annual_card_volume","has_accepted_credit_cards_previously","incorporation_date","principal_percentage_ownership","short_business_name","ownership_type","tax_authority","tax_id_provided","business_tax_id_provided","tax_id_fingerprint","business_tax_id_fingerprint","default_statement_descriptor"],"additionalProperties":true}},"additionalProperties":true},"payment_instruments":{"type":"object","additionalProperties":{}},"additional_underwriting_data":{"type":"object","additionalProperties":{}},"max_transaction_amount":{"type":"number"}},"required":["entity","max_transaction_amount"],"additionalProperties":true},"onboarding_link_details":{"type":"object","properties":{"return_url":{"type":"string"},"expired_session_url":{"type":"string"},"fee_details_url":{"type":"string"},"terms_of_service_url":{"type":"string"},"expiration_in_minutes":{"type":"number"}},"required":["return_url","expired_session_url","fee_details_url","terms_of_service_url","expiration_in_minutes"],"additionalProperties":true},"onboarding_link":{"type":["object","null"],"properties":{"expires_at":{"type":"string"},"link_url":{"type":"string"}},"required":["expires_at","link_url"],"additionalProperties":true},"status":{"type":"string","enum":["IN_PROGRESS","COMPLETED"]},"identity_id":{"type":["string","null"]}},"required":["id","created_at","updated_at","application_id","merchant_processors","onboarding_data","onboarding_link_details","status","identity_id"],"additionalProperties":true}},"payout_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"linked_type":{"type":"string","enum":["MERCHANT"]},"type":{"type":"string","enum":["NET"]},"net":{"type":"object","properties":{"frequency":{"type":"string","enum":["DAILY","MONTHLY"]},"submission_delay_days":{"type":"number"},"payment_instrument_id":{"type":"string"},"rail":{"type":"string","enum":["STANDARD"]}},"required":["frequency","submission_delay_days","payment_instrument_id","rail"],"additionalProperties":true},"linked_id":{"type":"string"}},"required":["id","created_at","updated_at","linked_type","type","net","linked_id"],"additionalProperties":true}},"instrument_histories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"type":{"type":"string"},"application_id":{"type":["string","null"]},"payment_instrument_id":{"type":"string"},"payment_instrument_type":{"type":["string","null"]},"old_instrument_details":{"type":["object","null"],"properties":{"bin":{"type":["string","null"]},"brand":{"type":["string","null"]},"expiration_month":{"type":["string","null"]},"expiration_year":{"type":["string","null"]},"last_four":{"type":["string","null"]},"fingerprint":{"type":["string","null"]}},"additionalProperties":true},"new_instrument_details":{"type":["object","null"],"properties":{"bin":{"type":["string","null"]},"brand":{"type":["string","null"]},"expiration_month":{"type":["string","null"]},"expiration_year":{"type":["string","null"]},"last_four":{"type":["string","null"]},"fingerprint":{"type":["string","null"]}},"additionalProperties":true}},"required":["id","created_at","type","payment_instrument_id"],"additionalProperties":true}},"payment_links":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{}},"application":{"type":"string"},"amount_details":{"type":"object","properties":{"amount_type":{"type":"string","enum":["FIXED","VARIABLE"]},"total_amount":{"type":["number","null"]},"currency":{"type":"string"},"min_amount":{"type":["number","null"]},"max_amount":{"type":["number","null"]},"amount_breakdown":{"type":"null"}},"required":["amount_type","total_amount","currency","min_amount","max_amount"]},"link_expires_at":{"type":"string"},"branding":{"type":"object","properties":{"brand_color":{"type":"string"},"accent_color":{"type":"string"},"logo":{"type":["string","null"],"format":"uri"},"icon":{"anyOf":[{"type":"string","enum":[""]},{"type":"string","format":"uri"},{"type":"null"}]},"logo_alternative_text":{"type":["string","null"]},"button_font_color":{"type":"string"}},"required":["brand_color","accent_color","logo","icon","logo_alternative_text","button_font_color"]},"merchant_id":{"type":"string"},"application_id":{"type":"string"},"allowed_payment_methods":{"type":"array","items":{"type":"string"}},"is_multiple_use":{"type":"boolean"},"additional_details":{"type":"object","properties":{"collect_name":{"type":"boolean"},"collect_email":{"type":"boolean"},"collect_phone":{"type":"boolean"},"collect_billing_address":{"type":"boolean"},"collect_shipping_address":{"type":"boolean"},"success_return_url":{"type":"string"},"unsuccessful_return_url":{"type":"string"},"expired_session_url":{"type":"string"},"terms_of_service_url":{"type":"string"},"expiration_in_minutes":{"type":"number"},"send_receipt":{"type":"boolean"},"receipt_requested_delivery_methods":{"type":"array","items":{}}},"required":["collect_name","collect_email","collect_phone","collect_billing_address","collect_shipping_address","success_return_url","unsuccessful_return_url","expired_session_url","terms_of_service_url","expiration_in_minutes","send_receipt","receipt_requested_delivery_methods"]},"payment_frequency":{"type":"string","enum":["ONE_TIME","RECURRING"]},"nickname":{"type":["string","null"]},"link_url":{"type":"string"},"buyer_details":{"type":"null"},"state":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"image_details":{"type":"object","properties":{"primary_image_url":{"type":["string","null"]},"alternative_image_urls":{"type":"array","items":{"type":"string"}}},"required":["primary_image_url","alternative_image_urls"]},"description":{"type":["string","null"]},"price_details":{"type":"object","properties":{"sale_amount":{"type":["number","null"]},"currency":{"type":"string"},"price_type":{"type":["string","null"]},"regular_amount":{"type":"number"}},"required":["sale_amount","currency","price_type","regular_amount"]},"name":{"type":"string"},"quantity":{"type":"number"}},"required":["image_details","description","price_details","name","quantity"]}},"_links":{"type":"null"}},"required":["id","created_at","updated_at","tags","amount_details","link_expires_at","branding","merchant_id","application_id","allowed_payment_methods","is_multiple_use","additional_details","payment_frequency","nickname","link_url","state","items"],"additionalProperties":true}},"payout_profile":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"linked_type":{"type":"string","enum":["MERCHANT"]},"type":{"type":"string","enum":["NET"]},"net":{"type":"object","properties":{"frequency":{"type":"string","enum":["DAILY","MONTHLY"]},"submission_delay_days":{"type":"number"},"payment_instrument_id":{"type":"string"},"rail":{"type":"string","enum":["STANDARD"]}},"required":["frequency","submission_delay_days","payment_instrument_id","rail"],"additionalProperties":true},"linked_id":{"type":"string"}},"required":["id","created_at","updated_at","linked_type","type","net","linked_id"],"additionalProperties":true}},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"platform_id":{"type":"string"},"application_id":{"type":"string"},"linked_type":{"type":"string"},"linked_to":{"type":"string"},"display_name":{"type":"string"},"type":{"type":"string","enum":["BANK_STATEMENT","BANK_STATEMENT_ONE_MONTH","BANK_STATEMENT_THREE_MONTHS","BUSINESS_ADDRESS_DOCUMENT","BUSINESS_ADDRESS_VERIFICATION","BUSINESS_INCORPORATION_DOCUMENT","BUSINESS_OWNERSHIP_STRUCTURE","BUSINESS_REGISTRATION","BUSINESS_REGISTRATION_DOCUMENT","BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT","BUSINESS_TAX_ID_DOCUMENT","DEVICE_IDLE_IMAGE","DIGITAL_SIGNATURE","DRIVERS_LICENSE_BACK","DRIVERS_LICENSE_FRONT","ENHANCED_DUE_DILIGENCE_DOCUMENT","IDENTIFICATION_CARD_BACK","IDENTIFICATION_CARD_FRONT","OTHER","OWNER_GOVERNMENT_ISSUED_PHOTO_ID","OWNER_TAX_ID_DOCUMENT","PASSPORT","PCI_DOCUMENT","PROCESSING_STATEMENT","TAX_DOCUMENT"]},"status":{"type":"string","enum":["REQUIRES_UPLOAD","UPLOADED","INVALID"]},"tags":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","created_at","updated_at","platform_id","application_id","linked_type","linked_to","display_name","type","status"]}},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"application":{"type":"string"},"amount":{"type":"number"},"billing_interval":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY","QUARTERLY","YEARLY"]},"buyer_details":{"type":"object","properties":{"identity_id":{"type":"string"},"instrument_id":{"type":["string","null"]},"requested_delivery_methods":{"type":"array","items":{}}},"required":["identity_id"]},"canceled_at":{"type":["string","null"]},"canceled_via":{"type":["string","null"]},"currency":{"type":"string","enum":["AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BOV","BRL","BSD","BTN","BWP","BYR","BZD","CAD","CDF","CHE","CHF","CHW","CLF","CLP","CNY","COP","COU","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LTL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MXV","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","USD","USN","UYI","UYU","UZS","VEF","VND","VUV","WST","XAF","XAG","XAU","XBA","XBB","XBC","XBD","XCD","XDR","XOF","XPD","XPF","XPT","XSU","XTS","XUA","XXX","YER","ZAR","ZMW","ZWL"]},"expires_at":{"type":["string","null"]},"first_charge_at":{"type":["string","null"]},"linked_to":{"type":"string"},"linked_type":{"type":"string","enum":["MERCHANT","APPLICATION"]},"next_billing_date":{"type":["object","null"],"properties":{"day":{"type":"number"},"month":{"type":"number"},"year":{"type":"number"}},"required":["day","month","year"]},"nickname":{"type":["string","null"]},"start_subscription_at":{"type":["string","null"]},"state":{"type":"string","enum":["ACTIVE","CANCELED","EXPIRED","NOT_STARTED","PAST_DUE"]},"subscription_details":{"type":"object","properties":{"collection_method":{"type":"string","enum":["BILL_AUTOMATICALLY","SEND_INVOICE"]},"send_invoice":{"type":"boolean"},"send_receipt":{"type":"boolean"},"trial_details":{"type":["object","null"],"properties":{"trial_period_days":{"type":["number","null"]},"trial_end_at":{"type":["string","null"]}}},"discount_phase_details":{"type":["object","null"],"properties":{"discount_amount":{"type":["number","null"]},"discount_percentage":{"type":["number","null"]},"discount_duration_in_billing_intervals":{"type":["number","null"]}}}},"required":["collection_method","send_invoice","send_receipt"]},"subscription_link_id":{"type":["string","null"]},"subscription_phase":{"type":"string","enum":["EVERGREEN","DISCOUNT","FIXED","NONE","TRIAL"]},"subscription_plan_id":{"type":"string"},"total_billing_intervals":{"type":["number","null"]}},"required":["id","created_at","updated_at","amount","billing_interval","buyer_details","currency","linked_to","linked_type","state","subscription_details","subscription_phase","subscription_plan_id"],"additionalProperties":true}}}},"resource":{"type":"string"},"version":{"type":"string"}},"required":["type","entity","occurred_at","_embedded"],"additionalProperties":true},{"type":"object","additionalProperties":true}]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[]}},"/v1/webhooks/helius/":{"post":{"summary":"Helius webhook","tags":["helius"],"description":"Webhook for Helius enhanced transaction notifications","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[]}},"/v1/webhooks/resend/":{"post":{"summary":"Resend delivery webhook","tags":["resend"],"description":"Receives Resend delivery events and records them against `public.email_sends`. Signed with Svix (`svix-id`, `svix-timestamp`, `svix-signature`).","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"timestamp":{"type":"string","format":"date-time"},"data":{},"message":{"type":"string"},"pagination":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"truncated":{"type":"boolean"},"cursors":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"}}}}}},"required":["success","timestamp"]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["success","timestamp","error"]}}}}},"security":[]}}}}