{"openapi":"3.1.0","info":{"title":"SureSettles White-Label Platform API","version":"1.0.0","description":"Implemented backend-only platform contract. Player financial engines and approvals remain authoritative. Canonical-owner domain/credential administration is deliberately outside the native API."},"servers":[{"url":"https://suresettles.com/api/platform/v1"}],"security":[{"PlatformBearer":[]}],"components":{"securitySchemes":{"PlatformBearer":{"type":"http","scheme":"bearer","description":"High-entropy platform credential. Never a player token, widget ID, management token or SureSettles user JWT."}},"schemas":{"PaymentLinkCreate":{"type":"object","additionalProperties":false,"properties":{"merchantId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"externalReference":{"type":"string","minLength":1,"maxLength":256,"description":"Your order/reference ID, without control characters. Returned by the status endpoint."},"amountCents":{"type":"integer","minimum":1,"maximum":100000000},"currency":{"type":"string","enum":["USD","ILS"]},"locked":{"const":true},"idempotencyKey":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"required":["merchantId","title","amountCents","currency","locked","idempotencyKey"]},"OperatorCreate":{"type":"object","additionalProperties":false,"properties":{"externalOperatorId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"name":{"type":"string","minLength":2,"maxLength":100},"website":{"type":"string","format":"uri"},"payoutAddress":{"type":"string","default":"","description":"Public TRON destination, or empty for owner setup; never a private key."}},"required":["externalOperatorId","name","website"]},"OperatorUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":100},"website":{"type":"string","format":"uri"},"enabled":{"type":"boolean"},"minDepositCents":{"type":"integer","minimum":100,"maximum":100000000},"maxDepositCents":{"type":"integer","minimum":100,"maximum":100000000},"minWithdrawalCents":{"type":"integer","minimum":100,"maximum":100000000},"withdrawalLimitCents":{"type":["string","null"],"pattern":"^[0-9]{1,10}$"},"paymentMethods":{"type":"object","additionalProperties":false,"properties":{"crypto":{"type":"boolean"},"card":{"type":"boolean"},"google_pay":{"type":"boolean"},"apple_pay":{"type":"boolean"},"cash_app":{"type":"boolean"},"ideal":{"type":"boolean"},"sepa":{"type":"boolean"},"promptpay":{"type":"boolean"}},"required":[]}},"required":[]},"Delegation":{"type":"object","additionalProperties":false,"properties":{"merchantId":{"type":"string","format":"uuid"},"externalOperatorId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"role":{"type":"string","enum":["admin","operator","viewer"]}},"required":["merchantId","externalOperatorId","role"]},"PlayerSession":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"purpose":{"type":"string","enum":["deposit","withdrawal","both"]},"origin":{"type":"string","format":"uri","description":"An exact approved HTTPS origin, with no path/query. Loopback HTTP only in development."},"expiresInSeconds":{"type":"integer","minimum":60,"maximum":900,"default":300}},"required":["externalPlayerId","purpose","origin"]},"PlayerRevoke":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","minLength":20,"maxLength":4096}},"required":["token"]},"DepositQuote":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"currency":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,30}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,8})(\\.[0-9]{1,8})?$","description":"Positive decimal string; USD has at most two decimal places."},"mode":{"type":"string","enum":["usd","crypto"],"default":"usd"},"network":{"type":"string","maxLength":32}},"required":["externalPlayerId","currency","amount"]},"Deposit":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"nativeQuoteId":{"type":"string","format":"uuid"},"playerToken":{"type":"string","minLength":20,"maxLength":4096},"playerIp":{"type":"string","description":"Optional real end-user IP, never the backend proxy IP."}},"required":["externalPlayerId","nativeQuoteId","playerToken"]},"WithdrawalQuote":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"amountCents":{"type":"integer","minimum":1,"maximum":100000000},"playerAddress":{"type":"string","minLength":10,"maxLength":256},"playerPreferredCoin":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,30}$"}},"required":["externalPlayerId","amountCents","playerAddress","playerPreferredCoin"]},"Withdrawal":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"nativeQuoteId":{"type":"string","format":"uuid"},"playerToken":{"type":"string","minLength":20,"maxLength":4096}},"required":["externalPlayerId","nativeQuoteId","playerToken"]},"FiatQuote":{"type":"object","additionalProperties":false,"properties":{"externalPlayerId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"providerCode":{"type":"string","pattern":"^[a-z0-9_-]{1,32}$"},"paymentMethod":{"type":"string","enum":["card","google_pay","apple_pay","cash_app","ideal","sepa","paypal","promptpay"]},"currencyFrom":{"type":"string","pattern":"^[A-Z]{3}$"},"amountFrom":{"type":"string","pattern":"^(0|[1-9][0-9]{0,8})(\\.[0-9]{1,2})?$"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"state":{"type":"string","maxLength":64},"returnSuccessUrl":{"type":"string","format":"uri","maxLength":1024},"returnFailedUrl":{"type":"string","format":"uri","maxLength":1024},"email":{"type":"string","format":"email","maxLength":254},"playerIp":{"type":"string","description":"Real end-user IP from your authenticated backend."}},"required":["externalPlayerId","providerCode","paymentMethod","currencyFrom","amountFrom","returnSuccessUrl","returnFailedUrl"]},"Launch":{"type":"object","additionalProperties":false,"properties":{"externalSubject":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"},"merchantId":{"type":["string","null"],"format":"uuid","default":null},"role":{"type":"string","enum":["admin","operator","viewer"]},"mode":{"type":"string","enum":["hosted","embedded"]},"sourceOrigin":{"type":"string","format":"uri","description":"An exact approved HTTPS origin, with no path/query. Loopback HTTP only in development."},"targetOrigin":{"type":"string","format":"uri","description":"An exact approved HTTPS origin, with no path/query. Loopback HTTP only in development."}},"required":["externalSubject","role","mode","sourceOrigin","targetOrigin"]},"SubjectRevoke":{"type":"object","additionalProperties":false,"properties":{"externalSubject":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"}},"required":["externalSubject"]},"Brand":{"type":"object","additionalProperties":false,"properties":{"appName":{"type":"string","minLength":2,"maxLength":60},"primary":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"primaryText":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"text":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"template":{"type":"string","enum":["full-page","compact"]},"logoAssetId":{"type":["string","null"],"format":"uuid","default":null},"faviconAssetId":{"type":["string","null"],"format":"uuid","default":null}},"required":["appName","primary","primaryText","background","text","template"]},"BrandPublish":{"type":"object","additionalProperties":false,"properties":{"draftRevision":{"type":"integer","minimum":1}},"required":["draftRevision"]},"Asset":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["logo","favicon"]},"content":{"type":"string","maxLength":350100,"description":"Base64 PNG/JPEG bytes, at most 256 KiB decoded."}},"required":["kind","content"]},"Callbacks":{"type":"object","additionalProperties":false,"properties":{"webhookUrl":{"type":"string","format":"uri","maxLength":512},"creditCheckUrl":{"type":"string","format":"uri","maxLength":512}},"required":["webhookUrl","creditCheckUrl"]},"Pricing":{"type":"object","additionalProperties":false,"properties":{"rateBps":{"type":"integer","minimum":0,"maximum":500},"expectedRevision":{"type":"integer","minimum":0}},"required":["rateBps","expectedRevision"]},"FeeEnrollment":{"type":"object","additionalProperties":false,"properties":{"consent":{"type":"boolean"}},"required":["consent"]},"Envelope":{"type":"object","properties":{"success":{"const":true},"data":{}},"required":["success","data"]},"Error":{"type":"object","properties":{"success":{"const":false},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["success","error"]}}},"paths":{"/session":{"get":{"operationId":"get__session","summary":"Read this credential’s platform identity, environment and effective permissions. Never a SureSettles user login.","x-required-scope":"authenticated","parameters":[],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links":{"post":{"operationId":"post__payment_links","summary":"Create an amount-locked, company-branded link for an authorized operator. Production backend only; no pricing or wallet-administration permission needed. Retry the identical body and idempotencyKey after an uncertain response.","x-required-scope":"payments:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLinkCreate"}}}},"responses":{"200":{"description":"Identical idempotent replay: the same link, not another payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-links/{id}":{"get":{"operationId":"get__payment_links_id_","summary":"Read the authoritative status of one company-created link within this credential’s current operator access. A browser redirect is not proof of payment.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators":{"get":{"operationId":"get__operators","summary":"List only this credential’s platform/operator portfolio.","x-required-scope":"operators:read","parameters":[],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"post__operators","summary":"Idempotently provision a new platform-owned operator using externalOperatorId. No email account linking.","x-required-scope":"operators:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperatorCreate"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}":{"get":{"operationId":"get__operators_merchantId_","summary":"Read one canonical merchant’s permitted configuration.","x-required-scope":"operators:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patch__operators_merchantId_","summary":"Edit name, website, payment-method allowlist, enablement and per-transaction limits. No signer or approval-policy controls.","x-required-scope":"operators:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperatorUpdate"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delegations":{"post":{"operationId":"post__delegations","summary":"Request independent-owner consent. Production only; approval happens on the canonical site.","x-required-scope":"operators:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delegation"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/delegation":{"delete":{"operationId":"delete__operators_merchantId_delegation","summary":"Revoke a delegated relationship without transferring merchant ownership.","x-required-scope":"operators:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/payment-methods":{"get":{"operationId":"get__operators_merchantId_payment_methods","summary":"Discover effective methods. Fiat retains admitted provider checkout and mandatory disclosures.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/assets":{"get":{"operationId":"get__operators_merchantId_assets","summary":"Discover assets admitted by the established payment engine.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/player-sessions":{"post":{"operationId":"post__operators_merchantId_player_sessions","summary":"Issue a separate, purpose-bound opaque player token; production returns a genuine widget handshake proof.","x-required-scope":"players:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerSession"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/player-sessions/revoke":{"post":{"operationId":"post__operators_merchantId_player_sessions_revoke","summary":"Revoke an opaque player token for this operator only.","x-required-scope":"players:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerRevoke"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/quotes":{"post":{"operationId":"post__operators_merchantId_quotes","summary":"Persist a short-lived, player/operator/environment-bound crypto deposit quote.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositQuote"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/deposits":{"post":{"operationId":"post__operators_merchantId_deposits","summary":"Consume a native quote using a player token and Idempotency-Key. Executes existing deposit admission.","x-required-scope":"payments:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"get__operators_merchantId_deposits","summary":"Keyset-paginated deposit history; optional externalPlayerId filter.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":512}},{"in":"query","name":"externalPlayerId","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/fiat-quotes":{"post":{"operationId":"post__operators_merchantId_fiat_quotes","summary":"Persist admitted fiat checkout input and estimated credit. No raw card data.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiatQuote"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/fiat-orders":{"post":{"operationId":"post__operators_merchantId_fiat_orders","summary":"Consume a fiat quote through existing player-purpose, provider, limits, fees and payout admission.","x-required-scope":"payments:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/fiat-orders/{fiatOrderId}":{"get":{"operationId":"get__operators_merchantId_fiat_orders_fiatOrderId_","summary":"Read webhook-reconciled fiat status by canonical local UUID and merchant ownership.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"fiatOrderId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/deposits/{transactionId}":{"get":{"operationId":"get__operators_merchantId_deposits_transactionId_","summary":"Read a transaction owned by this operator, not a provider-wide reference.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/withdrawal-quotes":{"post":{"operationId":"post__operators_merchantId_withdrawal_quotes","summary":"Quote an integer-cent player withdrawal to a supported address/asset.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalQuote"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/withdrawals":{"post":{"operationId":"post__operators_merchantId_withdrawals","summary":"Submit through the existing authorization, manual-approval, reserve and rollback engine. Not a merchant-treasury withdrawal.","x-required-scope":"payments:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_.:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"get__operators_merchantId_withdrawals","summary":"Read paginated player withdrawal history.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":512}},{"in":"query","name":"externalPlayerId","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/withdrawals/{transactionId}":{"get":{"operationId":"get__operators_merchantId_withdrawals_transactionId_","summary":"Read canonical operator-scoped withdrawal status.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/requests/{key}":{"get":{"operationId":"get__operators_merchantId_requests_key_","summary":"Reconcile a durable idempotency claim. Never re-key an uncertain financial request.","x-required-scope":"payments:read","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports":{"get":{"operationId":"get__reports","summary":"Portfolio or merchantId-filtered totals and 50-row transaction pages. Monetary totals are decimal strings.","x-required-scope":"reports:read","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":768}},{"in":"query","name":"from","schema":{"type":"string","maxLength":32}},{"in":"query","name":"to","schema":{"type":"string","maxLength":32}},{"in":"query","name":"status","schema":{"type":"string","maxLength":40}},{"in":"query","name":"currency","schema":{"type":"string","maxLength":32}},{"in":"query","name":"network","schema":{"type":"string","maxLength":32}},{"in":"query","name":"rail","schema":{"type":"string","enum":["crypto","fiat"]}},{"in":"query","name":"type","schema":{"type":"string","enum":["deposit","withdrawal"]}},{"in":"query","name":"bucket","schema":{"type":"string","enum":["day","week","month"],"default":"day"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operator-portfolio":{"get":{"operationId":"get__operator_portfolio","summary":"Search the complete authorized portfolio using search and a scope-bound keyset cursor. 50 rows per page; total includes operators beyond the compatibility-list cap.","x-required-scope":"operators:read","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","maxLength":512}},{"in":"query","name":"search","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallets":{"get":{"operationId":"get__wallets","summary":"Read-only configured settlement addresses and cached observations, with merchantId/cursor filters. Null/unavailable is not zero; no signer or withdrawal authority.","x-required-scope":"wallets:read","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pricing":{"get":{"operationId":"get__pricing","summary":"Merchant markup, revision, history and paged financial enrollments. Unrestricted production company access also returns read-only revenueShareBps and all-time USD fee-share, markup and combined earnings, with recorded collections separate. The fee share defaults to 30% of posted processing fees, never payment volume; only central administration can change it. Restricted and sandbox principals never receive company-wide revenue. Machine credentials cannot change pricing or enroll merchants.","x-required-scope":"pricing:read","parameters":[{"in":"query","name":"enrollmentCursor","schema":{"type":"string","maxLength":768}},{"in":"query","name":"enrollmentSearch","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/earnings":{"get":{"operationId":"get__earnings","summary":"Immutable accrued, funded collected, reserved, outstanding and reversed fees with deposit/collection references. Not a withdrawable balance. Same canonical-deposit date and payment filters as reports.","x-required-scope":"reports:read","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"cursor","schema":{"type":"string","maxLength":768}},{"in":"query","name":"from","schema":{"type":"string","maxLength":32}},{"in":"query","name":"to","schema":{"type":"string","maxLength":32}},{"in":"query","name":"status","schema":{"type":"string","maxLength":40}},{"in":"query","name":"currency","schema":{"type":"string","maxLength":32}},{"in":"query","name":"network","schema":{"type":"string","maxLength":32}},{"in":"query","name":"rail","schema":{"type":"string","enum":["crypto","fiat"]}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/management-launches":{"post":{"operationId":"post__management_launches","summary":"Issue a 60-second, single-use hosted/embedded management handoff. Resulting permissions are intersected with the credential scopes.","x-required-scope":"launches:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Launch"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subjects/revoke":{"post":{"operationId":"post__subjects_revoke","summary":"Durably revoke a tenant-namespaced external management subject and its outstanding access.","x-required-scope":"launches:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectRevoke"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/branding":{"get":{"operationId":"get__branding","summary":"Read platform defaults or an operator draft/published configuration via merchantId.","x-required-scope":"operators:read","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"put__branding","summary":"Save a contrast-validated draft, without publishing it.","x-required-scope":"branding:write","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete__branding","summary":"Remove an operator override using merchantId; platform defaults remain.","x-required-scope":"branding:write","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/branding/publish":{"post":{"operationId":"post__branding_publish","summary":"Compare-and-publish the exact draftRevision previewed by your team.","x-required-scope":"branding:write","parameters":[{"in":"query","name":"merchantId","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPublish"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets":{"post":{"operationId":"post__assets","summary":"Decode/re-encode bounded PNG/JPEG logo or favicon bytes. No SVG, remote fetch, HTML, CSS or scripts.","x-required-scope":"branding:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"responses":{"201":{"description":"Created or idempotently replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/callbacks":{"get":{"operationId":"get__callbacks","summary":"Read the single platform webhook and credit-check destinations.","x-required-scope":"callbacks:write","parameters":[],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"put__callbacks","summary":"Configure public HTTPS destinations. Changes invalidate financial certification; delegated callbacks require owner consent.","x-required-scope":"callbacks:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Callbacks"}}}},"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/callback-credential":{"get":{"operationId":"get__operators_merchantId_callback_credential","summary":"Backend-only verification secret derived for this platform/operator, never the underlying legacy merchant API secret.","x-required-scope":"callbacks:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/sandbox/{transactionId}/confirm":{"post":{"operationId":"post__operators_merchantId_sandbox_transactionId_confirm","summary":"Sandbox-only duplicate-safe credit proof; no provider traffic or real funds.","x-required-scope":"payments:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/operators/{merchantId}/sandbox/{transactionId}/rollback":{"post":{"operationId":"post__operators_merchantId_sandbox_transactionId_rollback","summary":"Sandbox-only duplicate-safe rollback of a reserved player debit.","x-required-scope":"payments:write","parameters":[{"in":"path","name":"merchantId","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"path","name":"transactionId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful scoped response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"default":{"description":"Safe error. Honor Retry-After for 429; reconcile uncertain financial work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}