{"openapi":"3.1.0","info":{"title":"Checkout.com (BYOK) API","version":"0.1.0","description":"Checkout.com (BYOK) lets an AI assistant read your own Checkout.com data through the Checkout.com API with a key you supply (Checkout.com secret API key (sk_...)). Read-only: 10 tools (list_payments, get_payment, list_payment_actions, list_disputes, get_dispute, get_balances, list_financial_actions, list_reports, get_report, list_workflows). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-checkoutcom.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-checkoutcom/docs"},"termsOfService":"https://connectorbay.com/byok-checkoutcom/terms"},"servers":[{"url":"https://byok-checkoutcom.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-checkoutcom/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 that match a reference (such as your order id), newest first, with amount, currency, status, approval, car","description":"List payments that match a reference (such as your order id), newest first, with amount, currency, status, approval, card scheme and balances. Use for \"Find the Checkout.com payment for order ORD-1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"reference":{"description":"Your payment reference, such as an order id.","maxLength":200,"title":"Reference","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of results (1 to 100).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging.","title":"Skip"}},"required":["prefix","reference"],"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 amount, currency, status, approval, reference, card scheme, balances (authorized, captured, r","description":"Get one payment by id with amount, currency, status, approval, reference, card scheme, balances (authorized, captured, refunded, voided) and risk flag. Use for \"What is the status of Checkout.com payment pay_abc\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"id":{"description":"Payment id (starts with pay_) or payment session id.","maxLength":200,"title":"Id","type":"string"}},"required":["prefix","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_payment_actions":{"post":{"operationId":"list_payment_actions","summary":"List the actions on one payment (authorization, capture, refund, void) latest first, with amount, approval and response ","description":"List the actions on one payment (authorization, capture, refund, void) latest first, with amount, approval and response code. Use for \"Was Checkout.com payment pay_abc refunded\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"id":{"description":"Payment id (starts with pay_).","maxLength":200,"title":"Id","type":"string"}},"required":["prefix","id"],"title":"list_payment_actionsArguments","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_disputes":{"post":{"operationId":"list_disputes","summary":"List disputes (chargebacks) newest update first, filtered by status, payment or dates, with category, reason code, amoun","description":"List disputes (chargebacks) newest update first, filtered by status, payment or dates, with category, reason code, amount and evidence deadline. Use for \"Which Checkout.com disputes still need evidence\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Number of results (1 to 250).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of results to skip, for paging.","title":"Skip"},"statuses":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated statuses such as evidence_required,evidence_under_review,won,lost.","title":"Statuses"},"updated_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only disputes updated at or after this ISO 8601 time.","title":"Updated From"},"updated_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only disputes updated before this ISO 8601 time.","title":"Updated To"},"payment_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only disputes of this payment id.","title":"Payment Id"},"payment_reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only disputes of the payment with this reference.","title":"Payment Reference"}},"required":["prefix"],"title":"list_disputesArguments","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_dispute":{"post":{"operationId":"get_dispute","summary":"Get one dispute by id with category, reason code, status, amount, deadline and the disputed payment's id and reference. ","description":"Get one dispute by id with category, reason code, status, amount, deadline and the disputed payment's id and reference. Use for \"Show Checkout.com dispute dsp_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"dispute_id":{"description":"Dispute id (starts with dsp_).","maxLength":200,"title":"Dispute Id","type":"string"}},"required":["prefix","dispute_id"],"title":"get_disputeArguments","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_balances":{"post":{"operationId":"get_balances","summary":"Get the balances of each currency account of an entity (available, pending, payable, collateral), optionally as of a pas","description":"Get the balances of each currency account of an entity (available, pending, payable, collateral), optionally as of a past time. Use for \"What are my Checkout.com balances\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"id":{"description":"Entity id (starts with ent_).","maxLength":200,"title":"Id","type":"string"},"with_currency_account_id":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include the currency account id.","title":"With Currency Account Id"},"balances_at":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"UTC time to read historical balances at, yyyy-MM-ddTHH:mm:ssZ.","title":"Balances At"}},"required":["prefix","id"],"title":"get_balancesArguments","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_financial_actions":{"post":{"operationId":"list_financial_actions","summary":"List the financial actions (captures, refunds, chargebacks) of a payment or action with processing dates, response codes","description":"List the financial actions (captures, refunds, chargebacks) of a payment or action with processing dates, response codes, card type and fee breakdown. Use for \"Show the financial actions of Checkout.com payment pay_abc\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"payment_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Payment id; give this or action_id.","title":"Payment Id"},"action_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Action id; give this or payment_id.","title":"Action Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Number of results (1 to 100).","title":"Limit"},"pagination_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Token from the previous answer's next link for the next page.","title":"Pagination Token"}},"required":["prefix"],"title":"list_financial_actionsArguments","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_reports":{"post":{"operationId":"list_reports","summary":"List the generated reports with type, description, period and file names, optionally between two creation times. Use for","description":"List the generated reports with type, description, period and file names, optionally between two creation times. Use for \"Which Checkout.com reports were generated last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"created_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only reports created after this ISO 8601 time.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only reports created before this ISO 8601 time.","title":"Created Before"},"entity_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only reports of this entity.","title":"Entity Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Number of results (1 to 100).","title":"Limit"},"pagination_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Token for the next page.","title":"Pagination Token"}},"required":["prefix"],"title":"list_reportsArguments","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_report":{"post":{"operationId":"get_report","summary":"Get one report by id with type, description, period, tags and file names. Use for \"Show Checkout.com report rpt_1\".","description":"Get one report by id with type, description, period, tags and file names. Use for \"Show Checkout.com report rpt_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"},"id":{"description":"Report id (starts with rpt_).","maxLength":200,"title":"Id","type":"string"}},"required":["prefix","id"],"title":"get_reportArguments","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_workflows":{"post":{"operationId":"list_workflows","summary":"List the event workflows with id, name and whether each is active (webhook URLs and signatures are not returned). Use fo","description":"List the event workflows with id, name and whether each is active (webhook URLs and signatures are not returned). Use for \"Which Checkout.com workflows are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Your unique Checkout.com API prefix: the first 8 characters of your client ID (vkuhvk4v for cli_vkuhvk4vjn2edkps7dfsq6emqm). Letters, digits and hyphens only.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Prefix","type":"string"}},"required":["prefix"],"title":"list_workflowsArguments","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}}}}