{"openapi":"3.1.0","info":{"title":"Culqi (BYOK) API","version":"0.1.0","description":"Culqi (BYOK) lets an AI assistant read your own Culqi data through the Culqi API with a key you supply (Culqi secret key (sk_live_... or sk_test_...)). Read-only: 10 tools (list_charges, get_charge, list_refunds, list_orders, get_order, list_plans, list_subscriptions, list_events, list_deposits, list_balance_operations). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-culqi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-culqi/docs"},"termsOfService":"https://connectorbay.com/byok-culqi/terms"},"servers":[{"url":"https://byok-culqi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-culqi/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 in cents, currency, refunded amount, fraud score, outcome and paid flag. Custome","description":"List charges, newest first, with amount in cents, currency, refunded amount, fraud score, outcome and paid flag. Customer, card and fraud-detail data are left out. Use for \"What did my Culqi business charge this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"min_amount":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Minimum charge amount in cents.","title":"Min Amount"},"max_amount":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Maximum charge amount in cents.","title":"Max Amount"},"currency_code":{"anyOf":[{"enum":["PEN","USD"],"type":"string"},{"type":"null"}],"default":null,"description":"Only charges in this currency.","title":"Currency Code"},"captured":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Only captured (true) or uncaptured (false) charges.","title":"Captured"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"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 with amounts in cents, refunded amount, fraud score and outcome message. Use for \"Show Culqi charge","description":"Get one charge by id with amounts in cents, refunded amount, fraud score and outcome message. Use for \"Show Culqi charge chr_test_HuVDSH10IoLKtYMa\".","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_refunds":{"post":{"operationId":"list_refunds","summary":"List refunds with linked charge, amount in cents, reason and status. Use for \"Which Culqi refunds were issued lately\".","description":"List refunds with linked charge, amount in cents, reason and status. Use for \"Which Culqi refunds were issued lately\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"reason":{"anyOf":[{"enum":["duplicado","fraudulento","solicitud_comprador"],"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds with this reason.","title":"Reason"},"status":{"anyOf":[{"enum":["pendiente","rechazado","completado"],"type":"string"},{"type":"null"}],"default":null,"description":"Only refunds in this status.","title":"Status"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"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_orders":{"post":{"operationId":"list_orders","summary":"List payment orders (cash, QR and wallet payments) with state, amount in cents, fees, payment code and expiry. Use for \"","description":"List payment orders (cash, QR and wallet payments) with state, amount in cents, fees, payment code and expiry. Use for \"Which Culqi orders are still pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders in this state (for example pending, paid, expired).","title":"State"},"min_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum order amount in cents.","title":"Min Amount"},"max_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum order amount in cents.","title":"Max Amount"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"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 state, amounts in cents, fees and timestamps. Use for \"Show Culqi order ord_test_xjmEW4dIyJM9G4","description":"Get one order by id with state, amounts in cents, fees and timestamps. Use for \"Show Culqi order ord_test_xjmEW4dIyJM9G4cc\".","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_plans":{"post":{"operationId":"list_plans","summary":"List recurring-billing plans with price in cents, interval, trial days and subscriber count. Use for \"What subscription ","description":"List recurring-billing plans with price in cents, interval, trial days and subscriber count. Use for \"What subscription plans do I have on Culqi\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":[1,2],"type":"integer"},{"type":"null"}],"default":null,"description":"Plan status: 1 active, 2 inactive.","title":"Status"},"min_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum plan amount in cents.","title":"Min Amount"},"max_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum plan amount in cents.","title":"Max Amount"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"title":"list_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/list_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List subscriptions with status, plan, billing period progress and next billing date. Use for \"Which Culqi subscriptions ","description":"List subscriptions with status, plan, billing period progress and next billing date. Use for \"Which Culqi subscriptions bill next\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"plan_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions on this plan id.","title":"Plan Id"},"status":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Subscription status: 1 created, 2 trial, 3 active, 4 cancelled and more.","title":"Status"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"title":"list_subscriptionsArguments","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_events":{"post":{"operationId":"list_events","summary":"List account events (charge created, failed, refunded and so on) with type, time and webhook delivery status code. Use f","description":"List account events (charge created, failed, refunded and so on) with type, time and webhook delivery status code. Use for \"Which Culqi events failed to deliver recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this type, for example charge.creation.failed.","title":"Type"},"creation_date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest creation time as a UNIX timestamp.","title":"Creation Date From"},"creation_date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest creation time as a UNIX timestamp.","title":"Creation Date To"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum results to return (default 50).","title":"Limit"},"before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page before this id (use cursors.before from the previous answer). Not inclusive.","title":"Before"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Return the page after this id (use cursors.after from the previous answer). Not inclusive.","title":"After"}},"title":"list_eventsArguments","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_deposits":{"post":{"operationId":"list_deposits","summary":"List settlement deposits Culqi paid to your bank in a date range, with status, bank, voucher id and amount. Account hold","description":"List settlement deposits Culqi paid to your bank in a date range, with status, bank, voucher id and amount. Account holder and number are left out. Use for \"How much did Culqi deposit to my bank this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency_code":{"description":"Currency of the operations.","enum":["PEN","USD"],"title":"Currency Code","type":"string"},"date_from":{"description":"Start of the range as a UNIX timestamp.","maxLength":200,"title":"Date From","type":"string"},"date_to":{"description":"End of the range as a UNIX timestamp.","maxLength":200,"title":"Date To","type":"string"},"sort":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order by date.","title":"Sort"}},"required":["currency_code","date_from","date_to"],"title":"list_depositsArguments","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_balance_operations":{"post":{"operationId":"list_balance_operations","summary":"List balance operations (sales, cancellations, refunds) with gross amount, commission, IGV tax and net payable amount. C","description":"List balance operations (sales, cancellations, refunds) with gross amount, commission, IGV tax and net payable amount. Card and customer data are left out. Use for \"What commissions did Culqi take on my sales this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency_code":{"description":"Currency of the operations.","enum":["PEN","USD"],"title":"Currency Code","type":"string"},"operation_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this operation type (for example Authorized, Canceled, Refund).","title":"Operation Type"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the range as a UNIX timestamp.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the range as a UNIX timestamp.","title":"Date To"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":200,"description":"Operations per page (default 200).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order by date.","title":"Sort"}},"required":["currency_code"],"title":"list_balance_operationsArguments","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}}}}