Have you ever integrated our payment API into your product? Help us improve the developer experience for you and everyone by taking this short survey, get started here

Payout Subaccounts

Build and manage wallets with Flutterwave payout subaacount APIs. We recommend you read the overview to understand the flow before proceeding.

Create a Payout Subaccount

Create wallets for your customers.

post https://api.flutterwave.com/v3/payout-subaccounts

Body Params

account_name string

The name of the wallet. It should be the name of the customer.
email string

The email address of the customer.
mobilenumber string

The customer's mobile number to be linked with the wallet.
country string

This is the country of the wallet.

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

{
  "account_name": "John Doe",
  "email": "developers@flutterwavego.com",
  "mobilenumber": "010101010",
  "country": "US"
}

{
  "status": "success",
  "message": "Payout subaccount created",
  "data": {
    "id": 699,
    "account_reference": "PSAFF2118D1A33844332",
    "account_name": "Flutterwave Developers",
    "barter_id": "234000001708294",
    "email": "developers@flutterwavego.com",
    "mobilenumber": "09012903324",
    "country": "NG",
    "nuban": "6222126177",
    "bank_name": "Sterling Bank",
    "bank_code": "232",
    "status": "ACTIVE",
    "created_at": "2022-03-04T19:57:24.000Z"
  }
}

{}

List all Payout Subaccounts

Query details for multiple wallets.

get https://api.flutterwave.com/v3/payout-subaccounts

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

{
  "status": "success",
  "message": "Payout subaccounts fetched",
  "data": [
    {
      "id": 700,
      "account_reference": "PSA15FAF664D63870782",
      "account_name": "Cornelius Ashley-Osuzoka ",
      "barter_id": "234000001708295",
      "email": "cornelius@flutterwavego.com",
      "mobilenumber": "09012903324",
      "country": "NG",
      "nuban": "6222126187",
      "bank_name": "Sterling Bank",
      "bank_code": "232",
      "status": "ACTIVE",
      "created_at": "2022-03-04T19:57:50.000Z"
    },
    {
      "id": 701,
      "account_reference": "PSAC33BFC23033921446",
      "account_name": "Ayomide Jimi-Oni ",
      "barter_id": "234000001708296",
      "email": "ayomide@flutterwavego.com",
      "mobilenumber": "09012903324",
      "country": "NG",
      "nuban": "6222126197",
      "bank_name": "Sterling Bank",
      "bank_code": "232",
      "status": "ACTIVE",
      "created_at": "2022-03-04T19:58:41.000Z"
    },
    {
      "id": 699,
      "account_reference": "PSAFF2118D1A33844332",
      "account_name": "Flutterwave Developers",
      "barter_id": "234000001708294",
      "email": "developers@flutterwavego.com",
      "mobilenumber": "09012903324",
      "country": "NG",
      "nuban": "6222126177",
      "bank_name": "Sterling Bank",
      "bank_code": "232",
      "status": "ACTIVE",
      "created_at": "2022-03-04T19:57:24.000Z"
    }
  ]
}


{}

Get a Payout Subaccount

Fetch details for a wallet.

get https://api.flutterwave.com/v3/payout-subaccounts/:account_reference

Path Params

account_reference string

The unique reference for the wallet

Query Params

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

{
  "status": "success",
  "message": "Payout subaccount fetched",
  "data": {
    "id": 699,
    "account_reference": "PSAFF2118D1A33844332",
    "account_name": "Flutterwave Developers",
    "barter_id": "234000001708294",
    "email": "developers@flutterwavego.com",
    "mobilenumber": "09012903324",
    "country": "NG",
    "nuban": "6222126177",
    "bank_name": "Sterling Bank",
    "bank_code": "232",
    "status": "ACTIVE",
    "transfer_limits": {
        "single_limit": 30000000,
        "total_daily_limit": 120000000
    },
    "created_at": "2022-03-04T19:57:24.000Z"
  }
}

{}

Update a Payout Subaccount

Update a customer's wallet details.

put https://api.flutterwave.com/v3/payout-subaccounts/:account_reference

Path Params

account_reference string

The unique reference for the payout

Body Params

account_name string

The customer's name to be updated.
mobilenumber string

This is the mobile number of the payout subaccount.
email string

This is the email address of the payout subaccount.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

curl --request PUT \
     --url https://api.flutterwave.com/v3/payout-subaccounts/PSAFF2118D1A33844332 \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
     --header 'Content-Type: application/json' \
     --data '
{
     "account_name": "Flutterwave Developers",
     "email": "developers@flutterwavego.com",
     "mobilenumber": "010101010",
     "country": "NG"
}
'

{
  "status": "success",
  "message": "Payout subaccount updated",
  "data": {
    "id": 699,
    "account_reference": "PSAFF2118D1A33844332",
    "account_name": "Flutterwave Developers",
    "barter_id": "234000001708294",
    "email": "developers@flutterwavego.com",
    "mobilenumber": "010101010",
    "country": "NG",
    "nuban": "6222126177",
    "bank_name": "Sterling Bank",
    "bank_code": "232",
    "status": "ACTIVE",
    "created_at": "2022-03-04T19:57:24.000Z"
  }
}

{}

Fetch Transactions

Query a wallet's transaction logs.

get https://api.flutterwave.com/v3/payout-subaccounts/:account_reference/transactions

Path Params

account_reference string

The unique reference for the payout

Query Params

from string

start date for transaction query.
to string

end date for transaction query.
currency string

currency of the subaccount. The possible values are USD, EUR, GBP and NGN

Show optional parameters

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

curl --request GET \
     --url 'https://api.flutterwave.com/v3/payout-subaccounts/PSAFF2118D1A33844332/transactions?from=2021-01-01&to=2021-02-10&currency=USD' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
     --header 'Content-Type: application/json'


{
  "status": "success",
  "message": "Wallet statement retrieved",
  "data": {
    "page_info": {
      "total": 8,
      "current_page": 1,
      "total_pages": 1
    },
    "transactions": [
      {
        "type": "D",
        "amount": 8206,
        "currency": "NGN",
        "balance_before": 8209.6,
        "balance_after": 3.6,
        "reference": "FLWRVCNFxxxxxxxxx",
        "date": "2023-08-10T04:47:21+00:00",
        "remarks": "From xxxxxxxx",
        "sent_currency": "NGN",
        "rate_used": 1,
        "sent_amount": 8206,
        "statement_type": "available"
      },
      {
        "type": "D",
        "amount": 350016,
        "currency": "NGN",
        "balance_before": 358225.6,
        "balance_after": 8209.6,
        "reference": "FLWRVCNFxxxxxxxxxxx",
        "date": "2023-07-26T03:48:25+00:00",
        "remarks": "xxxxxx|xxxxxx",
        "sent_currency": "NGN",
        "rate_used": 0,
        "sent_amount": 350016,
        "statement_type": "available"
      },
      {
        "type": "D",
        "amount": 2000,
        "currency": "NGN",
        "balance_before": 360225.6,
        "balance_after": 358225.6,
        "reference": "00001523xxxxxx",
        "date": "2023-07-26T03:42:51+00:00",
        "remarks": "FEE|Received Money from ZENITH BANK|xxxxxxxxx",
        "sent_currency": "",
        "rate_used": 0,
        "sent_amount": 0,
        "statement_type": "available"
      },
      {
        "type": "C",
        "amount": 360016,
        "currency": "NGN",
        "balance_before": 209.6,
        "balance_after": 360225.6,
        "reference": "0000152307xxxxx",
        "date": "2023-07-26T03:42:51+00:00",
        "remarks": "Received Money from ZENITH BANK|xxxxxxxxxxxxxx",
        "sent_currency": "",
        "rate_used": 0,
        "sent_amount": 0,
        "statement_type": "available"
      },
      {
        "type": "D",
        "amount": 1.4,
        "currency": "NGN",
        "balance_before": 211,
        "balance_after": 209.6,
        "reference": "000016230xxxxxxx",
        "date": "2023-07-26T03:37:52+00:00",
        "remarks": "xxxxxxxxxxx",
        "sent_currency": "",
        "rate_used": 0,
        "sent_amount": 0,
        "statement_type": "available"
      },
      {
        "type": "C",
        "amount": 100,
        "currency": "NGN",
        "balance_before": 111,
        "balance_after": 211,
        "reference": "0000162xxxxxx",
        "date": "2023-07-26T03:37:52+00:00",
        "remarks": "Received Money from xxxxxxxx",
        "sent_currency": "",
        "rate_used": 0,
        "sent_amount": 0,
        "statement_type": "available"
      },
      {
        "type": "C",
        "amount": 110,
        "currency": "NGN",
        "balance_before": 1,
        "balance_after": 111,
        "reference": "FLWRVCNFxxxxxx",
        "date": "2023-06-23T07:48:07+00:00",
        "remarks": "xxxxxxxxx",
        "sent_currency": "NGN",
        "rate_used": 1,
        "sent_amount": 110,
        "statement_type": "available"
      },
      {
        "type": "C",
        "amount": 1,
        "currency": "NGN",
        "balance_before": 0,
        "balance_after": 1,
        "reference": "FLWRVCNFxxxxxx",
        "date": "2023-06-23T07:46:54+00:00",
        "remarks": "xxxxxx",
        "sent_currency": "NGN",
        "rate_used": 1,
        "sent_amount": 1,
        "statement_type": "available"
      }
    ]
  }
}

{}

Fetch Available Balance

This section describes how to fetch the available balance on a payout/transfer subaccount on Flutterwave.

get https://api.flutterwave.com/v3/payout-subaccounts/:account_reference/balances

Path Params

account_reference string

The unique reference for the wallet.

Query Params

currency string

currency of the subaccount. The possible values are USD, EUR, GBP and NGN

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

curl --request GET \
     --url 'https://api.flutterwave.com/v3/payout-subaccounts/PSAFF2118D1A33844332/balances?currency=USD' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
     --header 'Content-Type: application/json'


{
    "status": "success",
    "message": "Subaccount balance fetched",
    "data": {
        "currency": "NGN",
        "available_balance": 13200,
        "ledger_balance": 0
    }
}

{}

Fetch Static Virtual Accounts

Generate static account details (virtual accounts) for wallet funding.

get https://api.flutterwave.com/v3/payout-subaccounts/:account_reference/static-account

Path Params

account_reference string

The unique reference for the wallet.

Query Params

currency string

currency of the subaccount. The possible values are USD, EUR, GBP and NGN

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call

curl --request GET \
     --url 'https://api.flutterwave.com/v3/payout-subaccounts/PSAFF2118D1A33844332/static-account?currency=USD' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
     --header 'Content-Type: application/json'

{
  "status": "success",
  "message": "SERVICE-RESPONSE",
  "data": {
    "static_account": "8336657404",
    "bank_name": "Community Federal Savings Bank",
    "bank_code": "026073150",
    "currency": "USD",
    "is_default": null,
    "type": "ach_routing_number"
  }
}

{}
Loading...