{ "openapi": "3.1.0", "info": { "title": "Kronos Platform Payouts API", "version": "1.3.0", "summary": "Send £ payouts to UK bank accounts from your own funded wallet.", "description": "The Kronos Payouts API lets a business pay its sellers, contractors or customers in pounds, straight to UK bank accounts, from the business's own USDC-funded wallet. Every request is authenticated with your API key and only ever sees your own account.\n\n**Sandbox** keys (`kp_sandbox_`) run on our banking partner HiFi's sandbox: same requests, same responses, no real money. Account numbers ending 0000 always fail so you can test errors. **Live** keys (`kp_live_`) move real money once your business is verified.\n\nGuide, pricing and how to get keys: https://getkronos.io/developers/payouts/", "license": { "name": "Proprietary — free to read and integrate against" }, "contact": { "name": "Kronos Payouts", "email": "support@getkronos.io", "url": "https://getkronos.io/developers/payouts/" } }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://auth.getkronos.io/functions/v1/partner-api", "description": "Production (sandbox and live are chosen by your API key)" } ], "security": [ { "PartnerBearerAuth": [] } ], "tags": [ { "name": "Discovery", "description": "Public API metadata and public partner profile lookup." }, { "name": "Account", "description": "Partner account, balance, compliance, members, recipients, and activity." }, { "name": "Quotes", "description": "Non-binding payout pricing previews." }, { "name": "Payouts", "description": "Idempotent payout creation and status lookup." }, { "name": "Usage", "description": "Partner usage, invoice, and key metadata." } ], "paths": { "/": { "get": { "tags": [ "Discovery" ], "summary": "API discovery", "operationId": "getDiscovery", "security": [], "responses": { "200": { "description": "API metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } } } } }, "/v1": { "get": { "tags": [ "Discovery" ], "summary": "API discovery", "operationId": "getV1Discovery", "security": [], "responses": { "200": { "description": "API metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" } } } } } } }, "/v1/public/partners/{slug}": { "get": { "tags": [ "Discovery" ], "summary": "Get public partner profile", "operationId": "getPublicPartner", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{2,40}$" } } ], "responses": { "200": { "description": "Public partner brand profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPartner" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get partner account", "operationId": "getAccount", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "responses": { "200": { "description": "Partner account, wallet, enabled corridors, and pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/balance": { "get": { "tags": [ "Account" ], "summary": "Get funding balance", "operationId": "getBalance", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "responses": { "200": { "description": "Funding wallet balance and approximate GBP value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "502": { "$ref": "#/components/responses/ProviderUnavailable" } } } }, "/v1/compliance": { "get": { "tags": [ "Account" ], "summary": "Get compliance status", "operationId": "getComplianceStatus", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "responses": { "200": { "description": "Business verification, account, and screening status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/activity": { "get": { "tags": [ "Account" ], "summary": "List recent account activity", "operationId": "listActivity", "description": "Returns the latest 200 requests made on your account (API calls and Partner Portal actions), with who made each one.", "responses": { "200": { "description": "Recent activity list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/recipients": { "get": { "tags": [ "Account" ], "summary": "List payout recipients", "operationId": "listRecipients", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "responses": { "200": { "description": "Recipient summary list grouped from recent payouts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/quotes": { "post": { "tags": [ "Quotes" ], "summary": "Create payout quote", "operationId": "createQuote", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "ukPayoutQuote": { "summary": "Quote a UK payout", "value": { "amount_gbp": "125.00", "country": "GB" } } } } } }, "responses": { "200": { "description": "Quote preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List payouts", "operationId": "listPayouts", "parameters": [ { "$ref": "#/components/parameters/Environment" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Payout list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Payouts" ], "summary": "Create payout", "operationId": "createPayout", "description": "Sends a £ payout to a UK bank account. Requires an Idempotency-Key header (use your own order or escrow id): repeating the same key never pays twice and returns the original payout. Sandbox keys create sandbox payouts; live keys create real ones.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of an existing payout.", "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "const": "true" }, "description": "Present when the same idempotency key returns the stored payout." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "201": { "description": "Payout accepted or sandbox payout recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutCreated" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized", "description": "Missing or invalid API key." }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "$ref": "#/components/responses/ProviderUnavailable" } } } }, "/v1/payouts/{id}": { "get": { "tags": [ "Payouts" ], "summary": "Get payout", "operationId": "getPayout", "parameters": [ { "$ref": "#/components/parameters/Environment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payout status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get current-period usage", "operationId": "getUsage", "parameters": [ { "$ref": "#/components/parameters/Environment" } ], "responses": { "200": { "description": "Usage and unbilled invoice totals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/invoices": { "get": { "tags": [ "Usage" ], "summary": "List invoices", "operationId": "listInvoices", "responses": { "200": { "description": "Recent invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/keys": { "get": { "tags": [ "Usage" ], "summary": "List API key metadata", "operationId": "listApiKeys", "description": "Returns metadata only. Secret key material is not returned.", "responses": { "200": { "description": "API key metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "PartnerBearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key: Authorization: Bearer kp_sandbox_… (testing) or kp_live_… (real money). Create and revoke keys in the Partner Portal under Developers." } }, "parameters": { "Environment": { "name": "environment", "in": "query", "description": "Ignored for API keys: the environment comes from the key itself (kp_sandbox_ or kp_live_).", "schema": { "type": "string", "enum": [ "sandbox", "live" ] } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_\\-:.]{8,100}$" }, "description": "Stable caller-generated key for one logical payout." } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Caller is authenticated but cannot perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientFunds": { "description": "Partner funding balance is insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found or not visible to this partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Request conflicts with an existing resource or limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ProviderUnavailable": { "description": "Provider or balance service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Discovery": { "type": "object", "required": [ "name", "version", "docs" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "docs": { "type": "string", "format": "uri" } } }, "MoneyString": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "12.00" ] }, "Account": { "type": "object", "required": [ "object", "id", "name", "status", "environment", "funding_wallet", "enabled_countries", "prices" ], "properties": { "object": { "type": "string", "const": "account" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "funding_wallet": { "type": "object", "required": [ "currency", "chain", "address" ], "properties": { "currency": { "type": "string", "const": "USDC" }, "chain": { "type": "string" }, "address": { "type": [ "string", "null" ] } } }, "enabled_countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "prices": { "type": "object", "properties": { "payout": { "type": "string" }, "monthly_account": { "type": "string" } } }, "rail": { "type": "string", "enum": [ "hifi_production", "hifi_sandbox", "simulated" ], "description": "Which payout rail this key drives. Sandbox keys use HiFi's sandbox; 'simulated' only until sandbox is connected for your account." } } }, "Environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "Balance": { "type": "object", "required": [ "object", "usdc", "approx_gbp", "gbp_per_usd" ], "properties": { "object": { "type": "string", "const": "balance" }, "usdc": { "$ref": "#/components/schemas/MoneyString" }, "approx_gbp": { "$ref": "#/components/schemas/MoneyString" }, "gbp_per_usd": { "type": "number" } } }, "QuoteRequest": { "type": "object", "required": [ "amount_gbp" ], "properties": { "amount_gbp": { "$ref": "#/components/schemas/MoneyString" }, "country": { "type": "string", "enum": [ "GB" ], "default": "GB" } }, "additionalProperties": false }, "Quote": { "type": "object", "required": [ "object", "country", "seller_receives_gbp", "fee_gbp", "wallet_sends_usdc", "exchange_rate", "fee_breakdown" ], "properties": { "object": { "type": "string", "const": "quote" }, "country": { "type": "string", "const": "GB" }, "seller_receives_gbp": { "$ref": "#/components/schemas/MoneyString" }, "fee_gbp": { "$ref": "#/components/schemas/MoneyString" }, "wallet_sends_usdc": { "$ref": "#/components/schemas/MoneyString" }, "exchange_rate": { "type": "object", "properties": { "gbp_per_usd": { "type": "number" } }, "required": [ "gbp_per_usd" ] }, "fee_breakdown": { "type": "object", "properties": { "taken_in_transfer_gbp": { "$ref": "#/components/schemas/MoneyString" }, "on_monthly_invoice_gbp": { "$ref": "#/components/schemas/MoneyString" } } } } }, "Recipient": { "type": "object", "required": [ "first_name", "last_name", "address", "bank" ], "properties": { "type": { "type": "string", "enum": [ "individual", "business" ], "default": "individual" }, "first_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "last_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "email": { "type": "string", "format": "email" }, "address": { "type": "object", "required": [ "line1", "city", "postal_code" ], "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "region": { "type": "string", "maxLength": 80, "description": "County or region (optional — the town is used if omitted)." } } }, "bank": { "type": "object", "required": [ "bank_name", "sort_code", "account_number" ], "properties": { "bank_name": { "type": "string" }, "sort_code": { "type": "string", "pattern": "^\\d{6}$" }, "account_number": { "type": "string", "pattern": "^\\d{8}$" } } } } }, "CreatePayoutRequest": { "type": "object", "required": [ "amount_gbp", "recipient" ], "properties": { "amount_gbp": { "$ref": "#/components/schemas/MoneyString" }, "country": { "type": "string", "enum": [ "GB" ], "default": "GB" }, "reference": { "type": "string", "maxLength": 120 }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "confirm_code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Not needed with an API key. (Used by the Partner Portal to confirm live payouts sent by hand.)" } }, "additionalProperties": false }, "PayoutStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled", "returned" ] }, "Payout": { "type": "object", "required": [ "id", "object", "environment", "status", "country", "amount_gbp", "fee_gbp", "wallet_sent_usdc", "recipient", "created_at", "updated_at", "created_via" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "type": "string", "const": "payout" }, "environment": { "$ref": "#/components/schemas/Environment" }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "reference": { "type": [ "string", "null" ] }, "country": { "type": "string", "const": "GB" }, "amount_gbp": { "$ref": "#/components/schemas/MoneyString" }, "fee_gbp": { "$ref": "#/components/schemas/MoneyString" }, "wallet_sent_usdc": { "$ref": "#/components/schemas/MoneyString" }, "recipient": { "type": "object", "required": [ "name", "account_last4" ], "properties": { "name": { "type": [ "string", "null" ] }, "account_last4": { "type": [ "string", "null" ] } } }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_via": { "type": "string", "enum": [ "api", "dashboard" ] } } }, "PayoutCreated": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/Quote" } } } ] }, "PayoutList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } } } }, "Usage": { "type": "object", "required": [ "object", "period_start", "payouts", "invoice_so_far" ], "properties": { "object": { "type": "string", "const": "usage" }, "period_start": { "type": "string", "format": "date" }, "payouts": { "type": "object", "properties": { "count": { "type": "integer" }, "completed": { "type": "integer" }, "paid_to_sellers_gbp": { "$ref": "#/components/schemas/MoneyString" }, "fees_gbp": { "$ref": "#/components/schemas/MoneyString" } } }, "invoice_so_far": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "amount_gbp": { "$ref": "#/components/schemas/MoneyString" } } } }, "total_gbp": { "$ref": "#/components/schemas/MoneyString" } } } } }, "InvoiceList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "period": { "type": "string" }, "status": { "type": "string" }, "total_gbp": { "$ref": "#/components/schemas/MoneyString" }, "issued_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object" } } } } } } }, "ApiKeyList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/Environment" }, "key_prefix": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "CreateApiKeyRequest": { "type": "object", "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "label": { "type": "string", "maxLength": 60 } }, "additionalProperties": false }, "ApiKeyCreated": { "type": "object", "required": [ "id", "environment", "key_prefix", "created_at", "secret", "note" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "$ref": "#/components/schemas/Environment" }, "key_prefix": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "pattern": "^kp_(sandbox|live)_[a-f0-9]{48}$", "description": "Returned once at creation time." }, "note": { "type": "string" } } }, "ApiKeyRevoked": { "type": "object", "required": [ "id", "revoked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean", "const": true } } }, "LoginRequested": { "type": "object", "required": [ "ok", "message" ], "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } }, "PublicPartner": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "brand_color": { "type": [ "string", "null" ] } } }, "MemberList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "admin", "viewer" ] }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "RecipientList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "name", "account_last4", "payouts", "paid_gbp", "last_paid_at" ], "properties": { "name": { "type": [ "string", "null" ] }, "account_last4": { "type": [ "string", "null" ] }, "payouts": { "type": "integer", "minimum": 0 }, "paid_gbp": { "$ref": "#/components/schemas/MoneyString" }, "last_paid_at": { "type": "string", "format": "date-time" } } } } } }, "ComplianceStatus": { "type": "object", "required": [ "object", "business_verification", "account", "screening" ], "properties": { "object": { "type": "string", "const": "compliance" }, "business_verification": { "type": "object", "required": [ "status", "provider_status", "continue_url", "terms_url" ], "properties": { "status": { "type": "string" }, "provider_status": { "type": [ "string", "null" ] }, "continue_url": { "type": [ "string", "null" ], "format": "uri" }, "terms_url": { "type": [ "string", "null" ], "format": "uri" } } }, "account": { "type": "object", "required": [ "isolated_wallet", "wallet_chain", "enabled_countries", "payout_limits_gbp", "billing_email", "contact_email" ], "properties": { "isolated_wallet": { "type": "boolean" }, "wallet_chain": { "type": [ "string", "null" ] }, "enabled_countries": { "type": "array", "items": { "type": "string" } }, "payout_limits_gbp": { "type": "object", "properties": { "min": { "$ref": "#/components/schemas/MoneyString" }, "max_per_payout": { "$ref": "#/components/schemas/MoneyString" } } }, "billing_email": { "type": [ "string", "null" ], "format": "email" }, "contact_email": { "type": [ "string", "null" ], "format": "email" } } }, "screening": { "type": "string" } } }, "ActivityList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "required": [ "at", "environment", "action", "status", "by", "detail" ], "properties": { "at": { "type": "string", "format": "date-time" }, "environment": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "status": { "type": [ "integer", "null" ] }, "by": { "type": "string" }, "detail": { "type": [ "string", "null" ] } } } } } } } } }