{"openapi":"3.1.0","info":{"title":"YooKassa (BYOK) API","version":"0.1.0","description":"YooKassa (BYOK) lets an AI assistant read your own YooKassa data through the YooKassa API with a key you supply (shop ID (the first part of the Basic credential)). Read-only: 9 tools (get_shop_settings, list_payments, get_payment, list_refunds, get_refund, list_receipts, list_payouts, list_deals, list_sbp_banks). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-yookassa.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-yookassa/docs"},"termsOfService":"https://connectorbay.com/byok-yookassa/terms"},"servers":[{"url":"https://byok-yookassa.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-yookassa/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_shop_settings":{"post":{"operationId":"get_shop_settings","summary":"Show the shop or gateway the key belongs to: account id, name, test flag, enabled payment methods, fiscalization setting","description":"Show the shop or gateway the key belongs to: account id, name, test flag, enabled payment methods, fiscalization setting and payout balance. Use for \"Which YooKassa shop is this key for and is it a test shop\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"on_behalf_of":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Id of a connected shop when acting for a partner shop (optional).","title":"On Behalf Of"}},"title":"get_shop_settingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payments":{"post":{"operationId":"list_payments","summary":"List payments newest first with status, amount, income after fees, payment method type and dates. Filter by status, meth","description":"List payments newest first with status, amount, income after fees, payment method type and dates. Filter by status, method and creation or capture time; page with cursor. Use for \"Which YooKassa payments succeeded since 2026-01-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","waiting_for_capture","succeeded","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status.","title":"Status"},"payment_method":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Payment method type, for example bank_card, sbp, yoo_money, sberbank or tinkoff_bank.","title":"Payment Method"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at before this time (ISO 8601).","title":"Created At Lt"},"captured_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with captured_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Captured At Gte"},"captured_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with captured_at before this time (ISO 8601).","title":"Captured At Lt"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many objects to return (1 to 100, default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, to fetch the following page.","title":"Cursor"}},"title":"list_paymentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_payment":{"post":{"operationId":"get_payment","summary":"Get one payment by its id: status, amount, fees, payment method type, description, cancellation reason and timestamps. U","description":"Get one payment by its id: status, amount, fees, payment method type, description, cancellation reason and timestamps. Use for \"What is the state of YooKassa payment 2ff7d6c0-000f-5000-9000-1f4d1a2b3c4d\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"description":"Id of the payment as returned when it was created (UUID).","maxLength":64,"title":"Payment Id","type":"string"}},"required":["payment_id"],"title":"get_paymentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_refunds":{"post":{"operationId":"list_refunds","summary":"List refunds newest first with the refunded payment id, status, amount and date; filter by payment, status and creation ","description":"List refunds newest first with the refunded payment id, status, amount and date; filter by payment, status and creation time. Use for \"Which refunds were made for YooKassa payment 2ff7d6c0-000f-5000-9000-1f4d1a2b3c4d\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds of this payment id.","title":"Payment Id"},"status":{"anyOf":[{"enum":["pending","succeeded","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Refund status.","title":"Status"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at before this time (ISO 8601).","title":"Created At Lt"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many objects to return (1 to 100, default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, to fetch the following page.","title":"Cursor"}},"title":"list_refundsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_refund":{"post":{"operationId":"get_refund","summary":"Get one refund by id with its payment id, status, amount, description and cancellation details. Use for \"What is the sta","description":"Get one refund by id with its payment id, status, amount, description and cancellation details. Use for \"What is the status of YooKassa refund 216749f7-0016-50be-b000-078d43a63ae4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"refund_id":{"description":"Id of the refund (UUID).","maxLength":64,"title":"Refund Id","type":"string"}},"required":["refund_id"],"title":"get_refundArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_receipts":{"post":{"operationId":"list_receipts","summary":"List fiscal receipts (payment or refund receipts) with fiscal document number, registration time and status; filter by p","description":"List fiscal receipts (payment or refund receipts) with fiscal document number, registration time and status; filter by payment, refund, status and time. Use for \"Which receipts were registered for YooKassa payment 2ff7d6c0-000f-5000-9000-1f4d1a2b3c4d\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts of this payment id.","title":"Payment Id"},"refund_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only receipts of this refund id.","title":"Refund Id"},"status":{"anyOf":[{"enum":["pending","succeeded","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Receipt status.","title":"Status"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at before this time (ISO 8601).","title":"Created At Lt"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many objects to return (1 to 100, default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, to fetch the following page.","title":"Cursor"}},"title":"list_receiptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payouts":{"post":{"operationId":"list_payouts","summary":"List payouts made to cards, YooMoney wallets or via the Faster Payments System, with status, amount and dates; filter by","description":"List payouts made to cards, YooMoney wallets or via the Faster Payments System, with status, amount and dates; filter by status, destination type and creation time. Use for \"Which YooKassa payouts succeeded in January 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","succeeded","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Payout status.","title":"Status"},"payout_destination_type":{"anyOf":[{"enum":["yoo_money","bank_card","sbp"],"type":"string"},{"type":"null"}],"default":null,"description":"Destination type.","title":"Payout Destination Type"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at before this time (ISO 8601).","title":"Created At Lt"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many objects to return (1 to 100, default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, to fetch the following page.","title":"Cursor"}},"title":"list_payoutsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_deals":{"post":{"operationId":"list_deals","summary":"List safe deals (marketplace payment holds) with status, balance and expiry; filter by status, text search and creation ","description":"List safe deals (marketplace payment holds) with status, balance and expiry; filter by status, text search and creation time. Use for \"Which YooKassa safe deals are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["opened","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Deal status.","title":"Status"},"full_text_search":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Free text matched against deal description and metadata.","title":"Full Text Search"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at at or after this time (ISO 8601, for example 2026-01-01T00:00:00.000Z).","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only objects with created_at before this time (ISO 8601).","title":"Created At Lt"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many objects to return (1 to 100, default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, to fetch the following page.","title":"Cursor"}},"title":"list_dealsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sbp_banks":{"post":{"operationId":"list_sbp_banks","summary":"List banks that take part in the Faster Payments System (SBP) and can receive payouts, with bank id, name and BIC. Use f","description":"List banks that take part in the Faster Payments System (SBP) and can receive payouts, with bank id, name and BIC. Use for \"Which banks can receive SBP payouts through YooKassa\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_sbp_banksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}