{"openapi":"3.1.0","info":{"title":"Flutterwave (BYOK) API","version":"0.1.0","description":"Flutterwave (BYOK) lets an AI assistant read your own Flutterwave data through the Flutterwave API with a key you supply (secret key (FLWSECK-...) of API version 3). Read-only: 10 tools (list_transactions, verify_transaction_by_reference, list_transfers, get_transfer, list_refunds, list_settlements, get_wallet_balances, list_payment_plans, list_subscriptions, list_subaccounts). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-flutterwave.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-flutterwave/docs"},"termsOfService":"https://connectorbay.com/byok-flutterwave/terms"},"servers":[{"url":"https://byok-flutterwave.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-flutterwave/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_transactions":{"post":{"operationId":"list_transactions","summary":"List payment transactions with amount, currency, fees, status, payment type, customer and time; filter by date range, st","description":"List payment transactions with amount, currency, fees, status, payment type, customer and time; filter by date range, status, currency, reference or customer. Use for \"Which Flutterwave payments were successful last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items from this date, as YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items up to this date, as YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this status, for example successful or failed.","title":"Status"},"currency":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this currency code, for example NGN.","title":"Currency"},"tx_ref":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the transaction with this merchant reference.","title":"Tx Ref"},"customer_email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions of this customer e-mail.","title":"Customer Email"},"customer_fullname":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only transactions of this customer name.","title":"Customer Fullname"}},"title":"list_transactionsArguments","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/verify_transaction_by_reference":{"post":{"operationId":"verify_transaction_by_reference","summary":"Look up one transaction by your own reference (tx_ref): final status, amount, fees, settled amount, payment type, card t","description":"Look up one transaction by your own reference (tx_ref): final status, amount, fees, settled amount, payment type, card type and last four digits, customer. Use for \"Did Flutterwave transaction with reference DevRef002156 succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tx_ref":{"description":"The merchant reference you set for the transaction.","maxLength":200,"title":"Tx Ref","type":"string"}},"required":["tx_ref"],"title":"verify_transaction_by_referenceArguments","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_transfers":{"post":{"operationId":"list_transfers","summary":"List payouts (transfers) with amount, fee, currency, status, reference, recipient name and bank name; recipient account ","description":"List payouts (transfers) with amount, fee, currency, status, reference, recipient name and bank name; recipient account numbers are left out. Use for \"Which Flutterwave transfers failed this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items from this date, as YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items up to this date, as YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page (the provider default is 10 when omitted).","title":"Page Size"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this status, for example successful, failed or pending.","title":"Status"},"reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the transfer with this merchant reference.","title":"Reference"}},"title":"list_transfersArguments","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_transfer":{"post":{"operationId":"get_transfer","summary":"Get one transfer by numeric id: amount, fee, currency, status, reference, recipient name, bank and message. Use for \"Sho","description":"Get one transfer by numeric id: amount, fee, currency, status, reference, recipient name, bank and message. Use for \"Show Flutterwave transfer 1933222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Numeric transfer id returned when the transfer was created.","title":"Id","type":"integer"}},"required":["id"],"title":"get_transferArguments","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 refunded amount, status, transaction id and time; filter by date range, status or currency. Use for \"W","description":"List refunds with refunded amount, status, transaction id and time; filter by date range, status or currency. Use for \"Which Flutterwave refunds were made this quarter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items from this date, as YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items up to this date, as YYYY-MM-DD.","title":"Date To"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this refund status, for example completed or failed.","title":"Status"},"currency":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this currency code.","title":"Currency"},"flw_ref":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the refund with this Flutterwave reference.","title":"Flw Ref"}},"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_settlements":{"post":{"operationId":"list_settlements","summary":"List settlements with gross, fee, refund, chargeback and net amounts, currency, status, due and processed dates. Use for","description":"List settlements with gross, fee, refund, chargeback and net amounts, currency, status, due and processed dates. Use for \"When is my next Flutterwave settlement due and how much is it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items from this date, as YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items up to this date, as YYYY-MM-DD.","title":"Date To"},"subaccount_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only settlements of this subaccount id.","title":"Subaccount Id"},"disburse_ref":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only settlements of this disbursement reference.","title":"Disburse Ref"}},"title":"list_settlementsArguments","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_wallet_balances":{"post":{"operationId":"get_wallet_balances","summary":"Show your wallet balances in every currency: available balance and ledger balance. Use for \"What is my Flutterwave walle","description":"Show your wallet balances in every currency: available balance and ledger balance. Use for \"What is my Flutterwave wallet balance in each currency\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_wallet_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_plans":{"post":{"operationId":"list_payment_plans","summary":"List recurring payment plans with name, amount, interval, duration, status, currency and plan token. Use for \"What payme","description":"List recurring payment plans with name, amount, interval, duration, status, currency and plan token. Use for \"What payment plans have I set up on Flutterwave\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items from this date, as YYYY-MM-DD.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items up to this date, as YYYY-MM-DD.","title":"Date To"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only plans with this status, for example active.","title":"Status"},"currency":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only plans in this currency.","title":"Currency"},"interval":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only plans with this interval, for example weekly.","title":"Interval"},"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only plans with exactly this amount.","title":"Amount"}},"title":"list_payment_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 plan subscriptions with amount, customer, plan id, status and creation time; filter by e-mail, plan or status. Use ","description":"List plan subscriptions with amount, customer, plan id, status and creation time; filter by e-mail, plan or status. Use for \"Which Flutterwave subscriptions are active on plan 3657\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this subscriber e-mail.","title":"Email"},"plan":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only subscriptions of this plan id.","title":"Plan"},"status":{"anyOf":[{"enum":["active","cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this status.","title":"Status"},"transaction_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only the subscription created by this transaction id.","title":"Transaction Id"},"subscribed_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions started on or after this date, YYYY-MM-DD.","title":"Subscribed From"},"subscribed_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions started on or before this date, YYYY-MM-DD.","title":"Subscribed To"}},"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_subaccounts":{"post":{"operationId":"list_subaccounts","summary":"List collection subaccounts with business name, bank, split type and value, country and subaccount id; account numbers a","description":"List collection subaccounts with business name, bank, split type and value, country and subaccount id; account numbers are left out. Use for \"Which Flutterwave subaccounts and split ratios do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"account_bank":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subaccounts of this bank code.","title":"Account Bank"},"bank_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subaccounts of this bank name.","title":"Bank Name"}},"title":"list_subaccountsArguments","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}}}}