{"openapi":"3.1.0","info":{"title":"HitPay (BYOK) API","version":"0.1.0","description":"HitPay (BYOK) lets an AI assistant read your own HitPay data through the HitPay API with a key you supply (business API key (live)). Read-only: 9 tools (list_charges, get_charge, list_payouts, get_payout, list_balances, list_payment_requests, list_subscription_plans, get_account_status, list_locations). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hitpay.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hitpay/docs"},"termsOfService":"https://connectorbay.com/byok-hitpay/terms"},"servers":[{"url":"https://byok-hitpay.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hitpay/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_charges":{"post":{"operationId":"list_charges","summary":"List charges newest first with amount, fees, status, payment method, channel and dates; filter by status, date range, am","description":"List charges newest first with amount, fees, status, payment method, channel and dates; filter by status, date range, amount, customer, payment request or payout. Use for \"Which HitPay charges succeeded this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 100).","title":"Per Page"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the next_cursor value from the previous answer's meta.","title":"Cursor"},"status":{"anyOf":[{"enum":["succeeded","failed","refunded"],"type":"string"},{"type":"null"}],"default":null,"description":"Charge status: succeeded, failed or refunded.","title":"Status"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges created on or after this date, YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges created on or before this date, YYYY-MM-DD.","title":"Date To"},"amount_from":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Only charges of at least this amount.","title":"Amount From"},"amount_to":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Only charges of at most this amount.","title":"Amount To"},"keywords":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search by amount, charge id, customer email or remark.","title":"Keywords"},"payment_request_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges of this payment request id.","title":"Payment Request Id"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges of this customer id.","title":"Customer Id"},"payout_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges settled in this payout id.","title":"Payout Id"}},"title":"list_chargesArguments","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_charge":{"post":{"operationId":"get_charge","summary":"Get one charge by id: amount, amount without fees, refunded amount, fees, status, payment method, channel and reference;","description":"Get one charge by id: amount, amount without fees, refunded amount, fees, status, payment method, channel and reference; customer details are left out. Use for \"Show HitPay charge 9c1b2f4e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"charge_id":{"description":"Charge id.","maxLength":200,"title":"Charge Id","type":"string"}},"required":["charge_id"],"title":"get_chargeArguments","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 (settlements of your balance to your own bank account) newest first with status, amount, currency, bank nam","description":"List payouts (settlements of your balance to your own bank account) newest first with status, amount, currency, bank name, reference and arrival date; the bank account number is left out. Use for \"When is my next HitPay payout arriving\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page (1 to 100).","title":"Per Page"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the next_cursor value from the previous answer's meta.","title":"Cursor"},"status":{"anyOf":[{"enum":["scheduled","processing","paid","failed","canceled","pending"],"type":"string"},{"type":"null"}],"default":null,"description":"Payout status: scheduled, processing, paid, failed, canceled or pending.","title":"Status"},"created_at_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts created on or after this date, YYYY-MM-DD.","title":"Created At From"},"created_at_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payouts created on or before this date, YYYY-MM-DD.","title":"Created At To"}},"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 status, amount, bank name, reference, failure reason and arrival date; the bank account number","description":"Get one payout by id with status, amount, bank name, reference, failure reason and arrival date; the bank account number is left out. Use for \"Show HitPay payout 9d2a\".","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_balances":{"post":{"operationId":"list_balances","summary":"List the account's balance per currency: available, pending, deposit and reserve wallets. Use for \"How much available ba","description":"List the account's balance per currency: available, pending, deposit and reserve wallets. Use for \"How much available balance do I have on HitPay\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_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_payment_requests":{"post":{"operationId":"list_payment_requests","summary":"List payment requests (payment links and checkouts); filter by free text on email, id or reference number. Use for \"Whic","description":"List payment requests (payment links and checkouts); filter by free text on email, id or reference number. Use for \"Which HitPay payment requests are open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 100).","title":"Per Page"},"current_page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial match on email, id or reference number.","title":"Search"},"is_default":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only default payment links.","title":"Is Default"}},"title":"list_payment_requestsArguments","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_subscription_plans":{"post":{"operationId":"list_subscription_plans","summary":"List recurring-billing subscription plans with price, currency, cycle and frequency. Use for \"Which HitPay subscription ","description":"List recurring-billing subscription plans with price, currency, cycle and frequency. Use for \"Which HitPay subscription plans do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many plans per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_subscription_plansArguments","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_account_status":{"post":{"operationId":"get_account_status","summary":"Show the account's bank-account status and verification status (overall, owner, business). Use for \"Is my HitPay account","description":"Show the account's bank-account status and verification status (overall, owner, business). Use for \"Is my HitPay account fully verified\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_account_statusArguments","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 business locations (stores) with name, city, country and active flag. Use for \"Which HitPay locations do I have\".","description":"List business locations (stores) with name, city, country and active flag. Use for \"Which HitPay locations do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many locations per page.","title":"Per Page"},"keywords":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by location name keywords or exact id.","title":"Keywords"}},"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}}}}