{"openapi":"3.1.0","info":{"title":"Payments API — LiveOne","version":"0.1.0","description":"Multi-processor, multi-tenant payments service"},"components":{"schemas":{"AccountListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"total":{"type":"number"}},"required":["items","total"]},"Account":{"type":"object","properties":{"id":{"type":"string"},"organization_id":{"type":["string","null"]},"scope":{"type":"string"},"scope_id":{"type":["string","null"]},"product_id":{"type":["string","null"]},"processor":{"type":"string"},"processor_mode":{"type":"string"},"vault_credential_id":{"type":"string"},"display_name":{"type":"string"},"is_default":{"type":"number"},"status":{"type":"string"},"processor_account_id":{"type":["string","null"]},"currency":{"type":"string"},"capabilities":{"type":["string","null"]},"platform_fee_bps":{"type":["number","null"]},"platform_fee_fixed_cents":{"type":["number","null"]},"metadata":{"type":["string","null"]},"created_at":{"type":"number"},"updated_at":{"type":"number"},"deleted_at":{"type":["number","null"]}},"required":["id","organization_id","scope","scope_id","product_id","processor","processor_mode","vault_credential_id","display_name","is_default","status","processor_account_id","currency","capabilities","platform_fee_bps","platform_fee_fixed_cents","metadata","created_at","updated_at","deleted_at"]},"ApiError":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"Authentication required"},"docsUrl":{"type":"string","example":"/api/reference#tag/errors/unauthorized"},"details":{"type":"object","additionalProperties":{},"example":{"field":"email"}},"retryAfter":{"type":"number","example":60},"field":{"type":"string","example":"email"}},"required":["code","message"]},"requestId":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["success","error","requestId"]},"UpdateAccountInput":{"type":"object","properties":{"display_name":{"type":"string","minLength":1,"maxLength":200},"is_default":{"type":"boolean"},"processor_account_id":{"type":["string","null"]},"currency":{"type":"string","minLength":3,"maxLength":3},"platform_fee_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"platform_fee_fixed_cents":{"type":["integer","null"],"minimum":0},"metadata":{"type":["object","null"],"additionalProperties":{}}}},"AccountTestResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"processor":{"type":"string"},"processor_account_id":{"type":["string","null"]},"message":{"type":"string"}},"required":["ok","processor","processor_account_id","message"]},"CustomerListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"]},"Customer":{"type":"object","properties":{"id":{"type":"string"},"organization_id":{"type":"string"},"external_ref":{"type":["string","null"]},"external_ref_type":{"type":["string","null"]},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"metadata":{"type":["string","null"]},"created_at":{"type":"number"},"updated_at":{"type":"number"},"deleted_at":{"type":["number","null"]}},"required":["id","organization_id","external_ref","external_ref_type","email","name","metadata","created_at","updated_at","deleted_at"]},"SessionResponse":{"type":"object","properties":{"session_id":{"type":"string","example":"ses_xxx"},"session_url":{"type":["string","null"],"example":"https://checkout.stripe.com/..."},"account_id":{"type":"string","description":"Resolved/used account"},"processor":{"type":"string"},"processor_session_id":{"type":"string"},"status":{"type":"string"},"expires_at":{"type":["number","null"]}},"required":["session_id","session_url","account_id","processor","processor_session_id","status","expires_at"]},"TransactionListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"]},"Transaction":{"type":"object","properties":{"id":{"type":"string"},"organization_id":{"type":"string"},"customer_id":{"type":["string","null"]},"account_id":{"type":"string"},"processor_transaction_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"platform_fee_in_cents":{"type":"number"},"net_to_account_in_cents":{"type":["number","null"]},"source_type":{"type":["string","null"]},"source_id":{"type":["string","null"]},"idempotency_key":{"type":"string"},"failure_code":{"type":["string","null"]},"failure_message":{"type":["string","null"]},"metadata":{"type":["string","null"]},"created_at":{"type":"number"},"updated_at":{"type":"number"}},"required":["id","organization_id","customer_id","account_id","processor_transaction_id","type","status","amount_in_cents","currency","platform_fee_in_cents","net_to_account_in_cents","source_type","source_id","idempotency_key","failure_code","failure_message","metadata","created_at","updated_at"]},"Refund":{"type":"object","properties":{"id":{"type":"string"},"organization_id":{"type":"string"},"transaction_id":{"type":"string"},"account_id":{"type":"string"},"processor_refund_id":{"type":"string"},"amount_in_cents":{"type":"number"},"reason":{"type":["string","null"]},"status":{"type":"string"},"initiated_by":{"type":["string","null"]},"notes":{"type":["string","null"]},"metadata":{"type":["string","null"]},"created_at":{"type":"number"},"updated_at":{"type":"number"}},"required":["id","organization_id","transaction_id","account_id","processor_refund_id","amount_in_cents","reason","status","initiated_by","notes","metadata","created_at","updated_at"]},"RefundListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"]}},"parameters":{}},"paths":{"/v1/accounts":{"get":{"tags":["Accounts"],"summary":"List processor accounts","parameters":[{"schema":{"type":"string","enum":["platform","product","org","sub_org"],"description":"Filter by scope"},"required":false,"description":"Filter by scope","name":"scope","in":"query"},{"schema":{"type":"string","example":"stripe"},"required":false,"name":"processor","in":"query"},{"schema":{"type":"string","enum":["pending","active","suspended","archived"],"default":"active"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Account list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountListResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Accounts"],"summary":"Create a processor account","requestBody":{"description":"Account data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["platform","product","org","sub_org"]},"scope_id":{"type":["string","null"]},"product_id":{"type":["string","null"],"example":"liveone"},"processor":{"type":"string","enum":["stripe","nmi","paypal","adyen"]},"processor_mode":{"type":"string","enum":["direct","connect_destination","connect_separate","split_funding"],"default":"direct"},"vault_credential_id":{"type":"string","description":"Must already exist in Vault"},"display_name":{"type":"string","minLength":1,"maxLength":200},"is_default":{"type":"boolean","default":false},"processor_account_id":{"type":["string","null"],"example":"acct_xxx"},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"usd"},"platform_fee_bps":{"type":["integer","null"],"minimum":0,"maximum":10000},"platform_fee_fixed_cents":{"type":["integer","null"],"minimum":0},"metadata":{"type":["object","null"],"additionalProperties":{}}},"required":["scope","processor","vault_credential_id","display_name"]}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Resource already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/accounts/{id}":{"get":{"tags":["Accounts"],"summary":"Get a processor account","parameters":[{"schema":{"type":"string","example":"ppa_xxx","description":"Account ID"},"required":true,"description":"Account ID","name":"id","in":"path"}],"responses":{"200":{"description":"Account found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Accounts"],"summary":"Update a processor account","parameters":[{"schema":{"type":"string","example":"ppa_xxx","description":"Account ID"},"required":true,"description":"Account ID","name":"id","in":"path"}],"requestBody":{"description":"Update data","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountInput"}}}},"responses":{"200":{"description":"Account updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/accounts/{id}/suspend":{"post":{"tags":["Accounts"],"summary":"Suspend a processor account (resolver will skip it)","parameters":[{"schema":{"type":"string","example":"ppa_xxx","description":"Account ID"},"required":true,"description":"Account ID","name":"id","in":"path"}],"responses":{"200":{"description":"Account suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/accounts/{id}/test":{"post":{"tags":["Accounts"],"summary":"Smoke-test credentials for a processor account","parameters":[{"schema":{"type":"string","example":"ppa_xxx","description":"Account ID"},"required":true,"description":"Account ID","name":"id","in":"path"}],"responses":{"200":{"description":"Test result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountTestResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/customers":{"get":{"tags":["Customers"],"summary":"List customers","parameters":[{"schema":{"type":"string"},"required":false,"name":"external_ref","in":"query"},{"schema":{"type":"string"},"required":false,"name":"external_ref_type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"email","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Customer list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Customers"],"summary":"Create or upsert a customer by external_ref","requestBody":{"description":"Customer data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Defaults to caller org"},"external_ref":{"type":"string"},"external_ref_type":{"type":"string","default":"user"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"metadata":{"type":"object","additionalProperties":{}}},"required":["email"]}}}},"responses":{"200":{"description":"Customer upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/customers/{id}":{"get":{"tags":["Customers"],"summary":"Get a customer by ID","parameters":[{"schema":{"type":"string","example":"cust_xxx"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Customer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/sessions":{"post":{"tags":["Sessions"],"summary":"Create a hosted Checkout Session","requestBody":{"description":"Session data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization_id":{"type":"string","description":"Defaults to caller's org"},"product_id":{"type":"string","example":"liveone"},"purpose":{"type":"string","enum":["one_time","subscription","add_payment_method"]},"preferred_processor":{"type":"string","enum":["stripe","nmi","paypal","adyen"]},"amount_in_cents":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"usd"},"description":{"type":"string"},"plan_id":{"type":"string"},"customer":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"external_ref":{"type":"string"},"external_ref_type":{"type":"string","default":"user"}},"required":["email"]},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"source_type":{"type":"string","example":"proposal"},"source_id":{"type":"string","example":"prop_xxx"},"account_id":{"type":"string"},"enable_link":{"type":"boolean","default":true},"enable_wallets":{"type":"boolean","default":true},"idempotency_key":{"type":"string"}},"required":["purpose","customer","success_url","cancel_url"]}}}},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/sessions/{id}":{"get":{"tags":["Sessions"],"summary":"Get a session by processor session ID","parameters":[{"schema":{"type":"string","example":"ses_xxx"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/transactions":{"get":{"tags":["Transactions"],"summary":"List transactions","parameters":[{"schema":{"type":"string"},"required":false,"name":"customer_id","in":"query"},{"schema":{"type":"string","enum":["pending","succeeded","failed","canceled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"source_type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"source_id","in":"query"},{"schema":{"type":["number","null"],"description":"Unix timestamp (seconds)"},"required":false,"description":"Unix timestamp (seconds)","name":"from","in":"query"},{"schema":{"type":["number","null"]},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Transaction list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionListResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/transactions/{id}":{"get":{"tags":["Transactions"],"summary":"Get a transaction by ID","parameters":[{"schema":{"type":"string","example":"ptx_xxx"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Transaction found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/refunds":{"post":{"tags":["Refunds"],"summary":"Issue a refund","requestBody":{"description":"Refund data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string","description":"Internal transaction ID (ptx_xxx)"},"amount_in_cents":{"type":"integer","exclusiveMinimum":0,"description":"Defaults to full amount"},"reason":{"type":"string","enum":["requested_by_customer","duplicate","fraudulent","other"],"default":"requested_by_customer"},"notes":{"type":"string"}},"required":["transaction_id"]}}}},"responses":{"201":{"description":"Refund initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Refunds"],"summary":"List refunds","parameters":[{"schema":{"type":"string"},"required":false,"name":"transaction_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Refund list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundListResponse"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/refunds/{id}":{"get":{"tags":["Refunds"],"summary":"Get a refund by ID","parameters":[{"schema":{"type":"string","example":"ref_xxx"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Refund found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"webhooks":{}}