> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Flutterwave

The Flutterwave connector lets your AI agent act in each user's Flutterwave account. Each user connects their own Flutterwave access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

**Authentication:** Bearer Token
**Categories:** Accounting & Finance
**Tools:** 60: 37 read, 20 write, 3 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=FLUTTERWAVE)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Flutterwave connection

   In **AgentKit > Connections**, create a Flutterwave connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'flutterwave'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Flutterwave:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'flutterwave_balances_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "flutterwave"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Flutterwave:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="flutterwave_balances_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Flutterwave credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'flutterwave_balance_get',
  toolInput: {
    currency: '<currency>',
  },
  connector: 'flutterwave',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="flutterwave_balance_get",
    tool_input={
        "currency": "<currency>",
    },
    connection_name="flutterwave",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `flutterwave_balance_get`

Get Wallet Balance · Read-only

Get your available and ledger balance in one currency.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `currency` (`string`, required): ISO 4217 currency code. Example: NGN.

Example input: `{"currency":"<currency>"}`

### `flutterwave_balances_list`

List Wallet Balances · Read-only

Get your available and ledger balance in every currency wallet.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `flutterwave_bank_account_resolve`

Resolve Bank Account Name · Read-only

Look up the account holder name of a bank account number before sending a transfer. Returns account_number and account_name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_bank` (`string`, required): The Customer's Bank code. See full list of bank codes here. Example: 044.
- `account_number` (`string`, required): The Customer's Bank account number. Example: 0690000032.

Example input: `{"account_bank":"<account_bank>","account_number":"<account_number>"}`

### `flutterwave_bank_branches_list`

List Bank Branches · Read-only

List the branches of a bank with their branch codes (needed for transfers in some countries).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): The Bank's unique ID returned in the fetch response. Example: 280.

Example input: `{"id":280}`

### `flutterwave_banks_list`

List Banks · Read-only

List the banks supported in a country with their codes. Use the code as account_bank in transfers and account lookups.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, required): ISO-2 country code e.g. NG. Example: NG.
- `include_provider_type` (`string`, optional): This introduces a field that helps differentiate between a bank and mobile money provider. Example: 1.

Example input: `{"country":"<country>"}`

### `flutterwave_beneficiaries_list`

List Beneficiaries · Read-only

List saved transfer beneficiaries. Returns per beneficiary its id, account number, bank and name. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.

Example input: `{}`

### `flutterwave_beneficiary_get`

Get Beneficiary · Read-only

Get one transfer beneficiary by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique identifier for the beneficiary you intend to fetch. It is returned in the call to create a beneficiary as data.id. Example: 3644.

Example input: `{"id":3644}`

### `flutterwave_bill_categories_list`

List Bill Categories · Read-only

List the bill categories (airtime, data, cable, power and others) you can pay in a country. Returns per category its code and name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): This is the country of the Biller. The expected value is NG. Example: NG.

Example input: `{}`

### `flutterwave_bill_customer_validate`

Validate Bill Customer · Read-only

Validate a customer identifier (meter number, smartcard number, phone and so on) for a bill item before paying. Returns the customer name and status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer` (`string`, required): This is the customer identifier For airtime, the value must be the customer's phone number. For DSTV, it must be the customer's smartcard number. Example: 08038291822.
- `item_code` (`string`, required): This is the item_code returned from bills categories endpoint as data[i].item_code. Example: AT099.

Example input: `{"customer":"<customer>","item_code":"<item_code>"}`

### `flutterwave_bill_items_list`

List Biller Items · Read-only

List the items (products and plans) a biller offers, with item_code, name, amount and fee.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `biller_code` (`string`, required): The unique identifier for the biller. This is returned as data[i].biller_code in the get billers response. Example: BIL119.

Example input: `{"biller_code":"<biller_code>"}`

### `flutterwave_bill_payment_status_get`

Get Bill Payment Status · Read-only

Get the status of a bill payment by reference, including the token for prepaid electricity.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `reference` (`string`, required): This is the tx_ref of the bill transaction. Example: 9300049404444.
- `verbose` (`integer`, optional): This flag allows us to return the status of the bill payment from the provider. Example: 1.

Example input: `{"reference":"<reference>"}`

### `flutterwave_bill_payments_history_list`

List Bill Payment History · Read-only

List past bill payments, filtered by status, dates, reference, batch, category or country, with commission earned. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `batch_reference` (`string`, optional): This unique identifier for a bulk payment. Example: batch-ref-abc123.
- `category` (`string`, optional): The bill category code. Example: CABLEBILLS.
- `country` (`string`, optional): This is the country of the Biller. Allowed values: NG, GH, KE, ZM. Example: NG.
- `from` (`string`, optional): This is the start date it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Example: 2018-08-01.
- `limit` (`string`, optional): The number of entries returned per page. Example: 10.
- `page` (`string`, optional): The page index to start the search from. Example: 1.
- `reference` (`string`, optional): This unique identifier for a single payment. Example: ref-abc123.
- `status` (`string`, optional): The transaction status Allowed values: Successful, Failed, Reversed. Example: Successful.
- `to` (`string`, optional): This is the end date, it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Example: 2018-08-27.

Example input: `{}`

### `flutterwave_bill_payments_summary_get`

Get Bill Payments Summary · Read-only

Get totals of bill payments in a date range, including commission earned.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): This is the start date it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Example: 2018-08-01.
- `to` (`string`, optional): This is the end date, it can be in any of this formats: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD. Example: 2018-08-27.

Example input: `{}`

### `flutterwave_billers_list`

List Billers in Category · Read-only

List the billers in a bill category for a country. Returns per biller its biller_code and name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category` (`string`, required): The bill category code. Example: CABLEBILLS.
- `country` (`string`, required): This is the country of the Biller. The expected value is NG. Example: NG.

Example input: `{"category":"<category>","country":"<country>"}`

### `flutterwave_card_bin_resolve`

Resolve Card BIN · Read-only

Get the issuer, card type and country of a card from its first six digits (BIN).

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `bin` (`integer`, required): The first 6 six digits on the customer's debit/credit card. Example: 123456.

Example input: `{"bin":123456}`

### `flutterwave_chargebacks_list`

List Chargebacks · Read-only

List chargebacks raised against your transactions, optionally by status, dates, currency, flw_ref or id. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `currency` (`string`, optional): ISO 4217 currency code. Example: NGN.
- `flw_ref` (`string`, optional): A unique Flutterwave reference for the transaction returned as flw_ref. Example: YemiDesola/FLW275389391.
- `from` (`string`, optional): The start date of the data query in YYYY-MM-DD. Example: 2020-08-01.
- `id` (`string`, optional): The unique identifier for the transaction. Example: 288192886.
- `page` (`integer`, optional): The page of the data to retrieve e.g. setting 1 retrieves the first page. Example: 1.
- `status` (`string`, optional): The status of the chargeback i.e. lost, won, initiated, accepted, or declined . Example: lost.
- `to` (`string`, optional): The finish date of the data query in YYYY-MM-DD. Example: 2020-08-14.

Example input: `{}`

### `flutterwave_payment_plan_get`

Get Payment Plan · Read-only

Get one payment plan by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique id of the payment plan you want to fetch. It is returned in the call to create a payment plan as data.id. Example: 3807.

Example input: `{"id":3807}`

### `flutterwave_payment_plans_list`

List Payment Plans · Read-only

List recurring payment plans, optionally by date range, amount, currency, interval or status. Returns per plan its id, name, amount, interval, duration, status and plan token. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount` (`integer`, optional): This is the exact amount set when creating the payment plan. Example: 5000.
- `currency` (`string`, optional): This is the currency the payment plan amount is charged in. Example: NGN.
- `from` (`string`, optional): This is the specified date to start the list from. YYYY-MM-DD. Example: 2020-01-01.
- `interval` (`string`, optional): This is how often the payment plan is set to execute. Example: weekly.
- `page` (`integer`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.
- `status` (`string`, optional): This is the status of the payment plan. Example: active.
- `to` (`string`, optional): The is the specified end period for the search. YYYY-MM-DD. Example: 2020-05-05.

Example input: `{}`

### `flutterwave_refund_get`

Get Refund · Read-only

Get one refund by ID with its amount, status and transaction.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id. Example: 469462.

Example input: `{"id":469462}`

### `flutterwave_refunds_list`

List Refunds · Read-only

List refunds, optionally by date range, status, currency or flw_ref. Returns per refund its id, amount, status, flw_ref, transaction and dates.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `currency` (`string`, optional): This is the specified currency to charge in. All currencies supported by Flutterwave can be passed here. You can check our Currency listing for more details. Example: NGN.
- `flw_ref` (`string`, optional): This is the unique reference for the refund transaction. It can be retrieved from the initial refund response as flw_ref. Example: 4687213286.
- `from` (`string`, optional): This is the specified date to start the list from. YYYY-MM-DD. Example: 2020-01-01.
- `id` (`string`, optional): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id. Example: 99025.
- `status` (`string`, optional): This is the status for the queried refunds, Expected values include: successful, failed and completed. Example: completed-mpgs.
- `to` (`string`, optional): The is the specified end period for the search . YYYY-MM-DD. Example: 2020-10-30.

Example input: `{}`

### `flutterwave_settlement_get`

Get Settlement · Read-only

Get one settlement with the transactions it includes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is a unique identifier for the particular settlement you want to fetch. It is returned in the call to list all settlements as data.id. Example: 41497.
- `page` (`string`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.

Example input: `{"id":41497}`

### `flutterwave_settlements_list`

List Settlements · Read-only

List settlements (payouts of collected funds to your bank account), optionally by date range or subaccount. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `disburse_ref` (`string`, optional): The disbursement reference ID to filter settlement logs by. This unique identifier is returned when a disbursement is initiated and can be used to track specific settlement transactions. Example: DISBURSE-123456.
- `from` (`string`, optional): This is the specified date to start the data query from. It should take a YYYY-MM-DD format. Example: 2024-01-01.
- `page` (`integer`, optional): The page of the data to retrieve e.g. setting 1 retrieves the first page. Example: 1.
- `subaccount_id` (`string`, optional): The subaccount ID to query settlement logs for. This is returned as subaccount_id when creating a subaccount. Example: PSA5D901175CB7307974.
- `to` (`string`, optional): This is the specified end date for the data query. It should take a YYYY-MM-DD format. Example: 2024-12-31.

Example input: `{}`

### `flutterwave_subaccount_get`

Get Subaccount · Read-only

Get one collection subaccount by ID with its bank account and split settings.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique id of the sub account you want to fetch. It is returned in the call to create a sub account as data.id. Example: 2181.

Example input: `{"id":2181}`

### `flutterwave_subaccounts_list`

List Subaccounts · Read-only

List collection subaccounts (split payment recipients), optionally by bank or account number. Returns per subaccount its id, subaccount_id, business name, bank account and split settings. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `account_bank` (`string`, optional): This is the sub-accounts bank ISO code. Example: 044.
- `account_number` (`string`, optional): This is the account number associated with the subaccount you want to fetch. Example: 0690000031.
- `bank_name` (`string`, optional): This is the name of the bank associated with the ISO code provided in account_bankfield. Example: Access Bank Nigeria.
- `page` (`integer`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.

Example input: `{}`

### `flutterwave_subscriptions_list`

List Subscriptions · Read-only

List customer subscriptions to payment plans, filtered by email, transaction, plan, dates or status. Returns per subscription its id, customer, plan, amount, status and next due date. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): This is the email of the subscriber. You can use this to query the transactions for a single customer. Example: user@gmail.com.
- `next_due_from` (`string`, optional): This is the parameter to filter from the start date of the next due subscriptions. Example: 2020-01-01.
- `next_due_to` (`string`, optional): This is the parameter to filter to the end date of the next due subscriptions. Example: 2020-05-05.
- `page` (`integer`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.
- `plan` (`integer`, optional): This is the ID of the payment plan. It is returned in the call to create a payment plan as data.id. Example: 3874.
- `status` (`string`, optional): This is the status for the queried transactions. Expected values are active and cancelled. Example: active.
- `subscribed_from` (`string`, optional): This is the start date of the subscriptions(when they are first active). You can use this as a starting point for your query. The expected date format for this parameter is YYYY-MM-DD. Example: 2020-01-01.
- `subscribed_to` (`string`, optional): This is the end date for a subscription. Like subscribed_from, It also has an expected date format of YYYY-MM-DD. Example: 2020-05-05.
- `transaction_id` (`integer`, optional): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge response as data.id. Example: 1190701.

Example input: `{}`

### `flutterwave_transaction_events_list`

View Transaction Timeline · Read-only

Get the timeline of events of a transaction (checkout opened, payment method chosen, OTP sent and so on). Use this to see where a customer dropped off.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id. Example: 957764.

Example input: `{"id":957764}`

### `flutterwave_transaction_fee_get`

Get Transaction Fee · Read-only

Get the fee Flutterwave charges to collect an amount in a currency, optionally for a payment type or card BIN. Returns the fee, merchant fee and charge amount.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount` (`integer`, required): This is the amount of the product or service to be charged from the customer. Example: 1000.
- `currency` (`string`, required): This is the specified currency to charge in. Example: NGN.
- `card_first6digits` (`integer`, optional): This can be used only when the user has entered first 6digits of their card number, it also helps determine international fees on the transaction if the card being used is an international card. Example: 536613.
- `payment_type` (`string`, optional): This is an optional parameter to be used when getting the transaction fees for different payment types. Expected values are card, debit_ng_account, mobilemoney, bank_transfer, and ach_payment.Kindly note that different fees are applied to the different methods, You can check our fee document for more details. Example: card.

Example input: `{"amount":1000,"currency":"<currency>"}`

### `flutterwave_transaction_verify`

Verify Transaction · Read-only

Verify a transaction by its Flutterwave ID and get its final status. Returns status, amount, charged amount, currency, tx_ref, flw_ref, payment type, card or account details and customer. Always verify before giving value.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the transaction unique identifier. It is returned in the initiate transaction call as data.id. Example: 288200108.

Example input: `{"id":288200108}`

### `flutterwave_transaction_verify_by_reference`

Verify Transaction by Reference · Read-only

Verify a transaction by your tx_ref and get its final status, amount, currency and customer. Use this when you only have your own reference.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tx_ref` (`string`, required): The unique reference you set when you created the transaction. Example: DevRef002156.

Example input: `{"tx_ref":"<tx_ref>"}`

### `flutterwave_transactions_list`

List Transactions · Read-only

List collection transactions in a date range, optionally by status, reference, customer or currency. Returns per transaction its id, tx_ref, flw_ref, amount, charged amount, fee, currency, status, payment type, customer and date. Results are paged; pass page for the next page. Use flutterwave_transaction_verify for one transaction.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, required): This is the specified date to start the list from. YYYY-MM-DD. Example: 2020-01-01.
- `to` (`string`, required): The is the specified end period for the search . YYYY-MM-DD. Example: 2020-01-14.
- `currency` (`string`, optional): This is the specified currency to charge in. All currencies supported by Flutterwave can be passed here. You can check our Currency listing for more details. Example: NGN.
- `customer_email` (`string`, optional): This is the email of the customer who carried out a transaction. You can use this to query the transactions for a single customer. Example: user@example.com.
- `customer_fullname` (`string`, optional): The Customer's full name. Example: Yemi Desola.
- `page` (`integer`, optional): This is the page number to retrieve e.g. setting 1 retrieves the first page. Example: 1.
- `status` (`string`, optional): This is the status for the queried transactions. Expected values for status include successful and failed. Example: successful.
- `tx_ref` (`string`, optional): This is the unique merchant reference tied to a transaction. This should be specified when querying a specific transaction. Example: new-transaction-ref.

Example input: `{"from":"<from>","to":"<to>"}`

### `flutterwave_transfer_fee_get`

Get Transfer Fee · Read-only

Get the fee for a transfer of an amount in a currency, optionally by type (account or mobilemoney). Returns the fee and fee type.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount` (`integer`, required): This is the amount to be transferred. Example: 10000.
- `currency` (`string`, required): This is the specified currency for the transfer. Expected values include: NGN, USD, GHS, KES, UGX, RWF. Example: NGN.
- `type` (`string`, optional): This is the type of transfer you want to get the fee for. Expected values are mobilemoney and account. Example: account.

Example input: `{"amount":10000,"currency":"<currency>"}`

### `flutterwave_transfer_get`

Get Transfer · Read-only

Get one transfer by ID with its status, amount, fee, recipient and completion message.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the numeric ID of the transfer you want to fetch. It is returned in the call to create a transfer as data.id. Example: 26251.

Example input: `{"id":26251}`

### `flutterwave_transfer_rates_get`

Get Transfer Rate · Read-only

Get the exchange rate to send an amount in a destination currency from a source currency balance. Returns the rate and the source amount.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `amount` (`integer`, required): This is the amount to transfer to the recipient. Example: 1000.
- `destination_currency` (`string`, required): This is the currency of the wallet you are making a transfer to. Example: USD.
- `source_currency` (`string`, required): This is the currency of the wallet being debited for the transfer. Example: NGN.

Example input: `{"amount":1000,"destination_currency":"<destination_currency>","source_currency":"<source_currency>"}`

### `flutterwave_transfer_retries_get`

Get Transfer Retries · Read-only

List the retry attempts of a transfer with their status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the numeric ID of the transfer you want to fetch. It is returned in the call to create a transfer as data.id. Example: 26251.

Example input: `{"id":26251}`

### `flutterwave_transfers_list`

List Transfers · Read-only

List transfers, optionally by reference, status or date range. Returns per transfer its id, account, bank, amount, fee, currency, status, reference, narration and date. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): This is the start date for the query. Example: 2026-01-01.
- `page` (`string`, optional): This allows you fetch from a specific page e.g. setting 1 retrieves the first page. Example: 1.
- `page_size` (`string`, optional): The number of query results to return per page. If unspecified, this would default to 10 items per page. Example: 20.
- `reference` (`string`, optional): The merchant's unique reference for the transfer. Example: ref-abc123.
- `status` (`string`, optional): This allows you fetch only transfers with a specific status e.g. fetch all successful transactions. Expected values include failed, successful. Example: successful.
- `to` (`string`, optional): This is the end date for the query. Example: 2026-01-31.

Example input: `{}`

### `flutterwave_virtual_account_get`

Get Virtual Account Number · Read-only

Get a virtual account number by its order_ref.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_ref` (`string`, required): The order reference generated for the virtual account. Example: URF_1579513580629_5981535.

Example input: `{"order_ref":"<order_ref>"}`

### `flutterwave_wallet_statement_get`

Get Wallet Statement · Read-only

Get the balance history (credits and debits) of a currency wallet in a date range. Results are paged; pass page for the next page.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `currency` (`string`, required): ISO 4217 currency code. Example: USD.
- `from` (`string`, required): The start date for the filter query in YYYY-MM-DD. Example: 2021-01-01.
- `to` (`string`, required): The end date for the filter query in YYYY-MM-DD. Example: 2021-01-05.
- `page` (`integer`, optional): The page of the data to retrieve. Example: 1.
- `type` (`string`, optional): This indicate the transaction type, i.e. credit(C) or debit(D). Example: C.

Example input: `{"currency":"<currency>","from":"<from>","to":"<to>"}`

### `flutterwave_beneficiary_create`

Create Beneficiary · Write

Save a bank account as a transfer beneficiary. Returns the beneficiary with its id.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_bank` (`string`, required): This is the Bank numeric code. It can be gotten from the get banks endpoint. Example: 044.
- `account_number` (`string`, required): This is the account number of the customer. Example: 0690000032.
- `beneficiary_name` (`string`, required): This is the name of the beneficiary for the transfer. Example: Flutterwave Developers.
- `bank_name` (`string`, optional): This is the name of the beneficiary bank. Example: ACCESS BANK NIGERIA.
- `currency` (`string`, optional): This is the based of the country of the beneficiary bank. If country is KE, supply KES, if NG, supply NGN. Example: NGN.

Example input: `{"account_bank":"<account_bank>","account_number":"<account_number>","beneficiary_name":"<beneficiary_name>"}`

### `flutterwave_bill_payment_create`

Create Bill Payment · Write

Pay a bill (airtime, data, cable, electricity and others) for a customer from your Flutterwave balance. Returns the payment with its reference and status. This spends real money.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`number`, required): This is the amount for the service you would like to buy. Example: 500.
- `biller_code` (`string`, required): The unique identifier for the biller. This is returned as data[i].biller_code in the get billers response. Example: BIL099.
- `country` (`string`, required): This is the country attached to the service being bought e.g. if service is Airtime and country is NG it means you are buying airtime in Nigeria. Example: NG.
- `customer_id` (`string`, required): This is the customer identifier. For airtime, the value must be the customer's phone number. For DSTV, it must be the customer's smartcard number. Example: +23490803840303.
- `item_code` (`string`, required): This is the item_code returned from bills categories endpoint as data[i].item_code. Example: AT099.
- `callback_url` (`string`, optional): Merchant-specific URL for bill payment callbacks. Example: https://webhook.site/5f9a659a-11a2-4925-89cf-8a59ea6a019a.
- `reference` (`string`, optional): This is a unique reference passed by the developer to identify transactions on their end. Example: 9300049404444.

Example input: `{"amount":500,"biller_code":"<biller_code>","country":"<country>","customer_id":"<customer_id>","item_code":"<item_code>"}`

### `flutterwave_bulk_transfer_create`

Create Bulk Transfer · Write

Send many transfers in one batch. Each bulk_data entry takes the same fields as a single transfer. Returns the batch with its id. This moves real money.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `bulk_data` (`array`, required): Transfers to make, each with bank_code, account_number, amount, currency, narration and reference. Example: [{"bank_code": "044", "account_number": "0690000032", "amount": 500, "currency": "NGN", "narration": "Salary", "reference": "sal-0001"}]
- `currency` (`string`, required): The currency of the Transfer. Example: NGN.
- `title` (`string`, optional): This is the title of the bulk transfer attempt. Example: March staff salary payment.

Example input: `{"bulk_data":[{"bank_code":"044","account_number":"0690000032","amount":500,"currency":"NGN","narration":"Salary","reference":"sal-0001"}],"currency":"<currency>"}`

### `flutterwave_charge_capture`

Capture Preauthorized Charge · Write

Capture a preauthorized card charge, for the full or a smaller amount. Returns the captured charge.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): This is the amount to be captured. This allows you to capture an amount less than the original amount authorised on the card. Example: 1000.
- `flw_ref` (`string`, required): This is the data.flw_ref returned in the charge response. Example: FLW001296992.

Example input: `{"amount":"<amount>","flw_ref":"<flw_ref>"}`

### `flutterwave_charge_preauth_refund`

Refund Preauthorized Charge · Write

Refund a captured preauthorized charge. Returns the refund.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): This is the amount to be refunded. Example: 1000.
- `flw_ref` (`string`, required): This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref in the charge response. Example: FLW001296992.

Example input: `{"amount":"<amount>","flw_ref":"<flw_ref>"}`

### `flutterwave_chargeback_respond`

Accept or Decline Chargeback · Write

Accept or decline a chargeback with a comment. Returns the chargeback.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `action` (`string`, required): The action you want to perform on the chargeback i.e. accept or decline. Example: accept.
- `comment` (`string`, required): Give a reason why you're accepting or rejecting the chargeback. Example: I accept the chargeback.
- `id` (`string`, required): Unique identifier for the chargeback. Example: 143.

Example input: `{"action":"<action>","comment":"<comment>","id":"<id>"}`

### `flutterwave_payment_link_create`

Create Payment Link (Checkout) · Write

Create a Flutterwave hosted checkout link for a customer to pay an amount by card, bank transfer, USSD, mobile money and other enabled methods. Returns data.link, the URL to send the customer to. Use flutterwave_transaction_verify after payment to confirm it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`integer`, required): Amount to charge, in the currency's main unit. Example: 1000.
- `customer_email` (`string`, required): Customer email address. Example: customer@example.com.
- `tx_ref` (`string`, required): Your unique reference for this payment. Example: order-1042-a1.
- `currency` (`string`, optional): The currency to charge in. Defaults to "NGN" if not specified. Example: NGN.
- `customer_name` (`string`, optional): Customer full name. Example: Yemi Desola.
- `customer_phone` (`string`, optional): Customer phone number. Example: 08012345678.
- `description` (`string`, optional): Description shown on the checkout page. Example: Payment for order #1042.
- `link_expiration` (`string`, optional): Sets how long the hosted payment link remains valid. Example: 2024-02-14T12:20:00.
- `logo` (`string`, optional): URL of a logo to show on the checkout page. Example: https://example.com/logo.png.
- `meta` (`object`, optional): Extra data to store with the transaction, as an object. Example: {"order_id": "1042"}
- `payment_options` (`string`, optional): Comma-separated list of payment methods to display. Example: card, ussd, mobilemoneyghana.
- `payment_plan` (`integer`, optional): ID of the payment plan (used for recurring payments). Example: 3807.
- `redirect_url` (`string`, optional): URL to redirect the customer to after payment is completed. Example: https://www.flutterwave.com/ng.
- `subaccounts` (`array`, optional): Subaccounts to split the payment with, each with an id. Example: [{"id": "RS_A8EB7D4D9C66C0B1C75014EE67D4D663"}]
- `title` (`string`, optional): Title shown on the checkout page. Example: Acme Store.

Example input: `{"amount":1000,"customer_email":"<customer_email>","tx_ref":"<tx_ref>"}`

### `flutterwave_payment_plan_cancel`

Cancel Payment Plan · Write

Cancel a payment plan so no new subscriptions are charged on it. Returns the plan.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique ìd of the payment plan you want to cancel. Example: 3807.

Example input: `{"id":3807}`

### `flutterwave_payment_plan_create`

Create Payment Plan · Write

Create a recurring payment plan with an amount and interval (daily, weekly, monthly, quarterly, bi-annually or yearly). Returns the plan with its id to pass as payment_plan in a checkout link.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`integer`, required): This is the amount to charge all customers subscribed to this plan. Example: 5000.
- `interval` (`string`, required): This will determine the frequency of the charges for this plan. Could be yearly, quarterly, monthly, weekly, daily, etc. Example: Monthly.
- `name` (`string`, required): This is the name of the payment plan, it will appear on the subscription reminder emails. Example: Monthly Nepa Bill Collection.
- `duration` (`integer`, optional): This is the frequency, it is numeric, e.g. if set to 5 and intervals is set to monthly you would be charged 5 months, and then the subscription stops. Example: 24.

Example input: `{"amount":5000,"interval":"<interval>","name":"<name>"}`

### `flutterwave_payment_plan_update`

Update Payment Plan · Write

Rename a payment plan or change its status. Returns the plan.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique id of the payment plan you want to fetch. It is returned in the call to create a payment plan as data.id. Example: 3807.
- `name` (`string`, required): The new name of the payment plan. Example: January neighbourhood contribution.
- `status` (`string`, required): The new status of the payment plan. Example: active.

Example input: `{"id":3807,"name":"<name>","status":"<status>"}`

### `flutterwave_subaccount_create`

Create Subaccount · Write

Create a collection subaccount that receives a split of payments into its bank account. Returns the subaccount with its subaccount_id to pass in checkout subaccounts.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_bank` (`string`, required): This is the sub-accounts bank ISO code, use the List of Banks for Transfer endpoint to retrieve a list of bank codes. Example: 044.
- `account_number` (`string`, required): This is the customer's account number. When testing on staging, you can find a list of all available test bank accounts here. Example: 0690000037.
- `business_mobile` (`string`, required): Primary business contact number. Example: 090890382.
- `business_name` (`string`, required): This is the sub-account business name. Example: Eternal Blue.
- `country` (`string`, required): This is the ISO country code of the merchant e.g. NG, GH, KE etc. Example: NG.
- `split_value` (`number`, required): This can be a percentage value or flat value depending on what was set on split_type.Note that the % value is in decimal. So 50% is 0.5 and so on. Example: 0.5.
- `business_contact` (`string`, optional): This is the contact person for the sub-account e.g. Richard Hendrix. Example: Richard Hendrix.
- `business_contact_mobile` (`string`, optional): Business contact number number. Example: 090890382.
- `business_email` (`string`, optional): This is the sub-account business email. Example: petya@stux.net.
- `split_type` (`string`, optional): This can be set as percentage or flat. Example: percentage.

Example input: `{"account_bank":"<account_bank>","account_number":"<account_number>","business_mobile":"<business_mobile>","business_name":"<business_name>","country":"<country>","split_value":0.5}`

### `flutterwave_subaccount_update`

Update Subaccount · Write

Update a subaccount's business name, email, split type and value or account number. Returns the subaccount.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique id of the subaccount you want to update. It is returned in the call to create a subaccount as data.id. Example: 3256.
- `split_value` (`number`, required): This can be a percentage value or flat value depending on what was set on split_type. Example: 1000.
- `account_number` (`string`, optional): This is the customer's account number. Example: 0690000040.
- `business_email` (`string`, optional): This is the sub-account business email". Example: richard@piedpiper.com.
- `business_name` (`string`, optional): This is the sub-account business name. Example: Pied Piper.
- `split_type` (`string`, optional): This can be set as percentage or flat. Example: flat.

Example input: `{"id":3256,"split_value":1000}`

### `flutterwave_subscription_activate`

Activate Subscription · Write

Reactivate a cancelled subscription. Returns the subscription.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the ID of the subscription you want to activate. It is returned in the call to query all subscription as data.id. Example: 4147.

Example input: `{"id":4147}`

### `flutterwave_subscription_cancel`

Cancel Subscription · Write

Cancel (deactivate) a customer's subscription so it is no longer charged. Returns the subscription.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the ID of the subscription to be cancelled. It is returned in the call to query all subscription as data.id. Example: 4147.

Example input: `{"id":4147}`

### `flutterwave_transaction_refund`

Refund Transaction · Write

Refund a successful transaction in full or in part. Returns the refund with its id and status. This returns money to the customer.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge and verify transaction responses as data.id. Example: 5708.
- `amount` (`integer`, optional): The amount to refund, Set this to issue a partial refund. Example: 5000.
- `callbackurl` (`string`, optional): The URL for refund response callbacks. Example: https://webhook.site/5f9a659a-11a2-4925-89cf-8a59ea6a019a.
- `comments` (`string`, optional): Custom description for the refund. Example: Refund for order #1042.

Example input: `{"id":5708}`

### `flutterwave_transaction_webhook_resend`

Resend Transaction Webhook · Write

Resend the webhook for a transaction to your webhook URL. Returns a confirmation.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): This is a unique transaction identifier generated by our systems. It is returned in the initiate charge response as data.id. Example: 5708.
- `wait` (`integer`, optional): This parameter would hold for the hook response and return what you respond with as the response. The expected value is 1. Example: 1.

Example input: `{"id":"<id>"}`

### `flutterwave_transfer_create`

Create Transfer · Write

Send money from your Flutterwave balance to a bank account or mobile money wallet. Returns the transfer with its id and status (usually NEW, then SUCCESSFUL or FAILED). This moves real money. Use flutterwave_transfer_fee_get first to see the fee.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `account_bank` (`string`, required): The recipient's bank code. You can query all available banks and their corresponding codes from the get banks endpoint. Example: 044.
- `account_number` (`string`, required): This is the recipient account number. Example: 0690000040.
- `amount` (`integer`, required): This is the amount to transfer to the recipient. Example: 5500.
- `currency` (`string`, required): The currency of the transfer. Example: NGN.
- `beneficiary` (`integer`, optional): The beneficiary's id. This allows you to make a transfer to an existing beneficiary. Example: 3768.
- `beneficiary_name` (`string`, optional): The full name of a transfer beneficiary. Example: Yemi Desola.
- `callback_url` (`string`, optional): The URL for transfer response callbacks. Example: https://webhook.site/5f9a659a-11a2-4925-89cf-8a59ea6a019a.
- `debit_currency` (`string`, optional): Pass this to set a different currency balance as the source of transfer funds. if unspecified, your default balance is debited for the transfer. Example: USD.
- `destination_branch_code` (`string`, optional): A code used to identify different bank branches. This is required for banks that have branches — varies by bank, not country. Check has_branches on the bank object from GET /v3/banks/{country}, or call GET /v3/banks/{id}/branches. Bank has branches -> required (omitting causes disbursement to fail after queueing). Bank has no branches -> omit. Requirements are provider-determined and can change; don't hardcode. Example: 001.
- `narration` (`string`, optional): This is the narration for the transfer e.g. payments for x services provided. Example: Payment for goods purchased.
- `reference` (`string`, optional): This is a merchant's unique reference for the transfer, it can be used to query for the status of the transfer. Example: newFLWXTransfer123.
- `skip_beneficiary_creation` (`string`, optional): if you don't want the automatic beneficiary creation step you can skip that by setting this as 1. Example: 0.

Example input: `{"account_bank":"<account_bank>","account_number":"<account_number>","amount":5500,"currency":"<currency>"}`

### `flutterwave_transfer_retry`

Retry Failed Transfer · Write

Retry a failed transfer. Returns the new transfer attempt. This moves real money.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`integer`, required): This is the unique identifier for the transfer you want to retry. It is returned in the call to create a transfer as data.id. Example: 166948.

Example input: `{"id":166948}`

### `flutterwave_virtual_account_create`

Create Virtual Account Number · Write

Create a virtual bank account number (NGN or GHS) that a customer pays into by bank transfer: dynamic for one amount, or permanent (static, needs BVN or NIN). Returns the account number, bank and expiry.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`integer`, required): The desired amount to be collected. Required when creating a dynamic virtual account. Example: 2000.
- `email` (`string`, required): The email address of the customer. Example: user@example.com.
- `bank_code` (`string`, optional): The bank code for the generated virtual account. Example: 090567.
- `bvn` (`string`, optional): This is the customer's Bank Verification Number. This is only required when creating a static NGN virtual accounts. Example: 12345678901.
- `currency` (`string`, optional): The currency of the Virtual Account. Defaults to NGN if not passed. Allowed values: NGN, GHS. Example: NGN.
- `expires` (`string`, optional): This specifies how long a dynamic virtual account remains active, in seconds. Minimum is 60 seconds (1 minute); Maximum is 5,270,401 seconds (2 months) for NGN and 172,800 seconds (48 hours) for GHS. Example: 60.
- `firstname` (`string`, optional): This is the first name associated with the customer's account. Example: John.
- `is_permanent` (`boolean`, optional): This allows you create a static account number i.e. it doesn't expire. Example: true.
- `lastname` (`string`, optional): This is the last name associated with the customer's account. Example: Doe.
- `narration` (`string`, optional): This allows you specify the name shown when the account is resolved. for GHS Account. this should be 35 characters long. Example: Please make a bank transfer to John.
- `nin` (`string`, optional): This is the customer’s National identification Number. It is required when creating a static virtual account. It can be used in place of the customer's bank verification number. Example: 12345678901.
- `phonenumber` (`string`, optional): This is the customer's phone number. Example: 08012345678.
- `tx_ref` (`string`, optional): This is a transaction reference that would be returned each time a transfer is done to the account. Example: jhn-mdkn-10192029920.

Example input: `{"amount":2000,"email":"<email>"}`

### `flutterwave_virtual_account_status_update`

Deactivate or Reactivate Virtual Account · Write

Deactivate or reactivate a virtual account number. Returns the account.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_ref` (`string`, required): This is a special reference returned when the virtual account is created. It is returned in the create response as data.order_ref. Example: URF_1787125640627_1836135.
- `status` (`string`, required): The status to set for the virtual account. Use inactive to deactivate a static virtual account, and active to reactivate a deactivated static virtual account. Example: inactive.

Example input: `{"order_ref":"<order_ref>","status":"<status>"}`

### `flutterwave_beneficiary_delete`

Delete Beneficiary · Destructive

Delete a saved transfer beneficiary.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique identifier for the beneficiary you intend to fetch. It is returned in the call to create a beneficiary as data.id. Example: 3103.

Example input: `{"id":3103}`

### `flutterwave_charge_void`

Void Preauthorized Charge · Destructive

Void (release) a preauthorized charge that has not been captured. Returns the voided charge.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `flw_ref` (`string`, required): This is a unique reference internally generated by Flutterwave. It is returned as data.flw_ref in the charge response. Example: FLW-TYR67844.

Example input: `{"flw_ref":"<flw_ref>"}`

### `flutterwave_subaccount_delete`

Delete Subaccount · Destructive

Delete a collection subaccount.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): This is the unique id of the sub account you want to fetch. It is returned in the call to create a sub account as data.id. Example: 2165.

Example input: `{"id":2165}`

## Related

Other Accounting & Finance connectors ([all 82](/agentkit/connectors/?category=accounting-finance)):

- [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools
- [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools
- [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
