{"openapi":"3.1.0","info":{"title":"Yoco (BYOK) API","version":"0.1.0","description":"Yoco (BYOK) lets an AI assistant read your own Yoco data through the Yoco API with a key you supply (personal application API key with read scopes (business/orders:read, business/payouts:read, business/locations:read, business/devices:read)). Read-only: 11 tools (list_payments, get_payment, list_orders, get_order, list_refunds, list_payouts, get_payout, list_payout_entries, list_payment_links,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-yoco.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-yoco/docs"},"termsOfService":"https://connectorbay.com/byok-yoco/terms"},"servers":[{"url":"https://byok-yoco.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-yoco/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/list_payments":{"post":{"operationId":"list_payments","summary":"List payments (card, instant EFT, cash) with status, method, source, receipt number and total, tip and refunded amounts ","description":"List payments (card, instant EFT, cash) with status, method, source, receipt number and total, tip and refunded amounts in cents. Needs the business/orders:read scope. Use for \"What payments did my Yoco business take this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"status":{"anyOf":[{"enum":["approved","cancelled","failed","pending"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payments in this status.","title":"Status"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"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 id with status, method, source, receipt number and amounts in cents. Use for \"Show Yoco payment 17321","description":"Get one payment by id with status, method, source, receipt number and amounts in cents. Use for \"Show Yoco payment 1732194482873-c777dc85\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"description":"Payment id.","maxLength":200,"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_orders":{"post":{"operationId":"list_orders","summary":"List orders with status, order number, location, channel and gross, discount, tax, tip and net amounts in cents. Needs t","description":"List orders with status, order number, location, channel and gross, discount, tax, tip and net amounts in cents. Needs the business/orders:read scope. Use for \"Which Yoco orders were completed today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"status":{"anyOf":[{"enum":["cancelled","completed","open"],"type":"string"},{"type":"null"}],"default":null,"description":"Only orders in this status.","title":"Status"},"location_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders at this location id.","title":"Location Id"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"title":"list_ordersArguments","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_order":{"post":{"operationId":"get_order","summary":"Get one order by id with status, timestamps and gross, discount, tax, tip and net amounts in cents. Use for \"Show Yoco o","description":"Get one order by id with status, timestamps and gross, discount, tax, tip and net amounts in cents. Use for \"Show Yoco order 1585232943682-9f7e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order id.","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"get_orderArguments","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 with status, type, linked payment, method and amount in cents. Use for \"Which refunds did Yoco process rece","description":"List refunds with status, type, linked payment, method and amount in cents. Use for \"Which refunds did Yoco process recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"status":{"anyOf":[{"enum":["approved","failed","pending","rejected"],"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds in this status.","title":"Status"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"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/list_payouts":{"post":{"operationId":"list_payouts","summary":"List payouts to your bank with type, status and gross, fee, net and capital repayment amounts in cents. Needs the busine","description":"List payouts to your bank with type, status and gross, fee, net and capital repayment amounts in cents. Needs the business/payouts:read scope. Use for \"When were my last Yoco payouts and how much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"status":{"anyOf":[{"enum":["failed","paid","sent","unpaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts in this status.","title":"Status"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"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/get_payout":{"post":{"operationId":"get_payout","summary":"Get one payout by id with type, status and gross, fee, net amounts in cents. Use for \"Show Yoco payout po1\".","description":"Get one payout by id with type, status and gross, fee, net amounts in cents. Use for \"Show Yoco payout po1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payout_id":{"description":"Payout id.","maxLength":200,"title":"Payout Id","type":"string"}},"required":["payout_id"],"title":"get_payoutArguments","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_payout_entries":{"post":{"operationId":"list_payout_entries","summary":"List the entries that make up one payout (payments, refunds, fees, adjustments) with gross, fee and net amounts, for rec","description":"List the entries that make up one payout (payments, refunds, fees, adjustments) with gross, fee and net amounts, for reconciliation. Use for \"What transactions make up Yoco payout po1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payout_id":{"description":"Payout id.","maxLength":200,"title":"Payout Id","type":"string"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"required":["payout_id"],"title":"list_payout_entriesArguments","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_payment_links":{"post":{"operationId":"list_payment_links","summary":"List payment links with reference, status, URL and linked order. Use for \"Which Yoco payment links are still pending\".","description":"List payment links with reference, status, URL and linked order. Use for \"Which Yoco payment links are still pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"status":{"anyOf":[{"enum":["cancelled","paid","pending"],"type":"string"},{"type":"null"}],"default":null,"description":"Only links in this status.","title":"Status"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"title":"list_payment_linksArguments","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_locations":{"post":{"operationId":"list_locations","summary":"List the business locations with id and name. Needs the business/locations:read scope. Use for \"What Yoco locations does","description":"List the business locations with id and name. Needs the business/locations:read scope. Use for \"What Yoco locations does my business have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"title":"list_locationsArguments","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_card_machines":{"post":{"operationId":"list_card_machines","summary":"List card machines with nickname, serial number and dates. Needs the business/devices:read scope. Use for \"Which Yoco ca","description":"List card machines with nickname, serial number and dates. Needs the business/devices:read scope. Use for \"Which Yoco card machines do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time (ISO 8601). If only one bound is given the window is 31 days; a range may not exceed 31 days.","title":"Created At Gte"},"created_at_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time (ISO 8601).","title":"Created At Lte"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass next_cursor from the previous answer to get the next page.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"}},"title":"list_card_machinesArguments","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}}}}