Collection Subaccounts

These endpoints allows the developer/merchant to manage Collection Subaccounts.

Create a Collection Subaccount

This document shows you how to create a subaccount on Flutterwave.

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

Body Params

account_bank string

This is the sub-accounts bank ISO code, use the List of Banks for Transfer endpoint to retrieve a list of bank codes.

account_number string

This is the customer's account number. When testing on staging, you can find a list of all available test bank accounts

business_name string

This is the sub-account business name.

split_value double

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.

business_mobile string

Primary business contact number

business_email string

This is the sub-account business email.

business_contact sting

This is the contact person for the sub-account e.g. Richard Hendrix.

business_contact_mobile string

Business contact number number.

split_type string

This can be set as percentage or flat.

meta array of objects

This is an array that allows you pass more information about the sub-account.

Headers

Authorization string

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

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.flutterwave.com/v3/subaccounts',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  body: JSON.stringify({
    "account_bank":"044",
    "account_number":"0690000037",
    "business_name":"Eternal Blue",
    "business_email":"petya@stux.net",
    "business_contact":"Anonymous",
    "business_contact_mobile":"090890382",
    "business_mobile":"09087930450",
    "country":"NG",
    "meta":[{"meta_name":"mem_adr",
             "meta_value":"0x16241F327213"
            }],
    "split_type":"percentage",
    "split_value":0.5
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.flutterwave.com/v3/subaccounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n    \"account_bank\": \"044\",\n    \"account_number\": \"0690000037\",\n    \"business_name\": \"Eternal Blue\",\n    \"business_email\": \"petya@stux.net\",\n    \"business_contact\": \"Anonymous\",\n    \"business_contact_mobile\": \"090890382\",\n    \"business_mobile\": \"09087930450\",\n    \"country\": \"NG\",\n    \"meta\": [\n        {\n            \"meta_name\": \"mem_adr\",\n            \"meta_value\": \"0x16241F327213\"\n        }\n    ],\n    \"split_type\": \"percentage\",\n    \"split_value\": 0.5\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/payout-subaccounts")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"
request.body = "{\n    \"account_bank\": \"044\",\n    \"account_number\": \"0690000037\",\n    \"business_name\": \"Eternal Blue\",\n    \"business_email\": \"petya@stux.net\",\n    \"business_contact\": \"Anonymous\",\n    \"business_contact_mobile\": \"090890382\",\n    \"business_mobile\": \"09087930450\",\n    \"country\": \"NG\",\n    \"meta\": [\n        {\n            \"meta_name\": \"mem_adr\",\n            \"meta_value\": \"0x16241F327213\"\n        }\n    ],\n    \"split_type\": \"percentage\",\n    \"split_value\": 0.5\n}"


response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Subaccount created",
  "data": {
    "id": 2181,
    "account_number": "0690000037",
    "account_bank": "044",
    "full_name": "Eternal Blue",
    "created_at": "2020-05-31T00:40:15.000Z",
    "split_type": "percentage",
    "split_value": 0.5,
    "subaccount_id": "RS_235E8F4E92A4048B57EA29B0E1B8F78B",
    "bank_name": "ACCESS BANK NIGERIA"
  }
}

{}

Fetch all subaccounts

This section describes how to list all collection subaccounts on Flutterwave.

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

Query Params

account_bank string

This is the sub-accounts bank ISO code

account_number string

This is the account number associated with the subaccount you want to fetch

bank_name string

This is the name of the bank associated with the ISO code provided in account_bankfield

page int32

This is the page number to retrieve e.g. setting 1 retrieves the first page

Headers

Authorization string

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

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.flutterwave.com/v3/subaccounts',
  'headers': {
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.flutterwave.com/v3/subaccounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/subaccounts")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Subaccounts fetched",
  "meta": {
    "page_info": {
      "total": 8,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "data": [
    {
      "id": 2181,
      "account_number": "0690000037",
      "account_bank": "044",
      "business_name": "Eternal Blue",
      "full_name": "Ibra Mili",
      "created_at": "2020-01-20T06:47:56.000Z",
      "meta": [
        {
          "meta_name": "mem_adr",
          "meta_value": "0x16241F327213"
        }
      ],
      "account_id": 88747,
      "split_ratio": 1,
      "split_type": "percentage",
      "split_value": 0.5,
      "subaccount_id": "RS_9BD2ACE480785E759A16FDE1874A6657",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 2180,
      "account_number": "0690000035",
      "account_bank": "044",
      "business_name": "Eternal Blue",
      "full_name": "Peter Crouch",
      "created_at": "2020-01-20T06:44:58.000Z",
      "meta": [
        {
          "meta_name": "mem_adr",
          "meta_value": "0x16241F327213"
        }
      ],
      "account_id": 88746,
      "split_ratio": 1,
      "split_type": "flat",
      "split_value": 0,
      "subaccount_id": "RS_5096825149E9FDDC65864F79B815AB45",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 2164,
      "account_number": "0690000043",
      "account_bank": "044",
      "business_name": "JK Services",
      "full_name": "Roberta Weber",
      "created_at": "2020-01-17T16:25:36.000Z",
      "meta": [
        {}
      ],
      "account_id": 88496,
      "split_ratio": 1,
      "split_type": "flat",
      "split_value": 0,
      "subaccount_id": "RS_A560B61FF493A3720913B0487030D2A5",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 2063,
      "account_number": "0690000039",
      "account_bank": "044",
      "business_name": "Sharp Guy",
      "full_name": "Dotun Ajib",
      "created_at": "2020-01-02T21:54:35.000Z",
      "meta": [
        {
          "swift_code": ""
        }
      ],
      "account_id": 86548,
      "split_ratio": 1,
      "split_type": "percentage",
      "split_value": 0.6,
      "subaccount_id": "RS_2A9D2F79274AD40924983F5BA6975336",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 1962,
      "account_number": "0690000042",
      "account_bank": "044",
      "business_name": "Sam Son",
      "full_name": "Forrest Terry",
      "created_at": "2019-12-09T13:27:04.000Z",
      "meta": [
        {
          "swift_code": ""
        }
      ],
      "account_id": 84353,
      "split_ratio": 1,
      "split_type": "percentage",
      "split_value": 0.02,
      "subaccount_id": "RS_008F29575D91B6E80BB31F5B374CBF4E",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 1961,
      "account_number": "0690000033",
      "account_bank": "044",
      "business_name": "Zen Daya",
      "full_name": "Bale Gary",
      "created_at": "2019-12-09T13:19:41.000Z",
      "meta": [
        {
          "swift_code": ""
        }
      ],
      "account_id": 84351,
      "split_ratio": 1,
      "split_type": "percentage",
      "split_value": 0.05,
      "subaccount_id": "RS_DE6A6DDCB8C0708D7D39B7DFEC0AC8B7",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 1960,
      "account_number": "0690000031",
      "account_bank": "044",
      "business_name": "Zen Daya",
      "full_name": "Forrest Green",
      "created_at": "2019-12-09T13:18:14.000Z",
      "meta": [
        {
          "swift_code": ""
        }
      ],
      "account_id": 84349,
      "split_ratio": 1,
      "split_type": "percentage",
      "split_value": 0.05,
      "subaccount_id": "RS_7F017022CF4E8A7F0BD5BBD86BD442B0",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    },
    {
      "id": 1663,
      "account_number": "0690000032",
      "account_bank": "044",
      "business_name": "Monkey Tail",
      "full_name": "Pastor Bright",
      "created_at": "2019-09-25T13:44:23.000Z",
      "meta": [
        {
          "swift_code": ""
        }
      ],
      "account_id": 75465,
      "split_ratio": 1,
      "split_type": "flat",
      "split_value": 100,
      "subaccount_id": "RS_19D8078A8CB10757BA7ACA8FB695D17C",
      "bank_name": "ACCESS BANK NIGERIA",
      "country": "NG"
    }
  ]
}

{}

Fetch a subaccount

This section describes how to fetch a collection subaccount on Flutterwave.

get https://api.flutterwave.com/v3/subaccounts/id

Path Params

id int32

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

Headers

Authorization string

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

var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://api.flutterwave.com/v3/subaccounts/21816',
  'headers': {
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.flutterwave.com/v3/subaccounts/21816",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/subaccounts/21816")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Authorization"] = "Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Subaccount fetched",
  "data": {
    "id": 2181,
    "account_number": "0690000037",
    "account_bank": "044",
    "business_name": "Eternal Blue",
    "full_name": "RITA BLUE",
    "created_at": "2020-05-31T00:40:15.000Z",
    "meta": null,
    "account_id": 133581,
    "split_ratio": 1,
    "split_type": "percentage",
    "split_value": 0.5,
    "subaccount_id": "RS_235E8F4E92A4048B57EA29B0E1B8F78B",
    "bank_name": "ACCESS BANK NIGERIA",
    "country": "NG"
  }
}

{}

Update a subaccount

This section describes how to update a collection subaccount on Flutterwave.

put https://api.flutterwave.com/v3/subaccounts/id

Path Params

id int32

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

Body Params

business_name string

This is the sub-account business name.

split_value float

This can be a percentage value or flat value depending on what was set on split_type

business_email string

This is the sub-account business email.

split_type string

This can be set as percentage or flat.

account_number string

This is the customer's account number.

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/subaccounts/2165 \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
     --header 'Content-Type: application/json' \
    --data-raw '{
    "business_name": "Luxe collectibles",
    "business_email": "mad@o.enterprises",
    "account_bank": "044",
    "account_number": "0690000040",
    "split_type": "flat",
    "split_value": "200"
}'

var request = require('request');
var options = {
  'method': 'PUT',
  'url': 'https://api.flutterwave.com/v/subaccounts/2165',
  'headers': {
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
  body: JSON.stringify({
    "business_name":"Luxe collectibles",
    "business_email":"mad@o.enterprises",
    "account_bank":"044",
    "account_number":"0690000040",
    "split_type":"flat",
    "split_value":"200"
    )};
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

  <?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/subaccounts/2165",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS =>"{\n    \"business_name\": \"Luxe collectibles\",\n    \"business_email\": \"mad@o.enterprises\",\n    \"account_bank\": \"044\",\n    \"account_number\": \"0690000040\",\n    \"split_type\": \"flat\",\n    \"split_value\": \"200\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer {SEC_KEY}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/subaccounts/2165")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Authorization"] = "Bearer {SEC_KEY}"
request["Content-Type"] = "application/json"
request.body = "{\n    \"business_name\": \"Luxe collectibles\",\n    \"business_email\": \"mad@o.enterprises\",\n    \"account_bank\": \"044\",\n    \"account_number\": \"0690000040\",\n    \"split_type\": \"flat\",\n    \"split_value\": \"200\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Subaccount edited",
  "data": {
    "id": 2181,
    "account_number": "0690000040",
    "account_bank": "044",
    "business_name": "Luxe collectibles",
    "full_name": "RITA BLUE",
    "created_at": "2020-01-17T16:28:26.000Z",
    "meta": [
      {
        "meta_name": "MarketplaceID",
        "meta_value": "ggs-920900"
      }
    ],
    "account_id": 133581,
    "split_ratio": 1,
    "split_type": "flat",
    "split_value": "1000",
    "subaccount_id": "RS_884E7E4BD793ADA77F491CF4AD3DE19E",
    "bank_name": "ACCESS BANK NIGERIA",
    "country": "NG"
  }
}

{}

Delete a subaccount

This section describes how to delete a collection subaccount on Flutterwave.

delete https://api.flutterwave.com/v3/subaccounts/id

Path Params

id int32

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

Headers

Authorization string

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

var request = require('request');
var options = {
  'method': 'DELETE',
  'url': 'https://api.flutterwave.com/v3/subaccounts/21816',
  'headers': {
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.flutterwave.com/v3/subaccounts/21816",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("https://api.flutterwave.com/v3/subaccounts/21816")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::DELETE.new(url)
request["Authorization"] = "Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Subaccount deleted",
  "data": null
}

{}

Collection Subaccounts

API Reference

Endpoints

Collection Subaccounts

Create a Collection Subaccount

Body Params

Headers

Fetch all subaccounts

Query Params

Headers

Fetch a subaccount

Path Params

Headers

Update a subaccount

Path Params

Body Params

Headers

Delete a subaccount

Path Params

Headers