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

Beneficiaries

These endpoints allows the developer/merchant to manage Transfer Beneficiaries.

Create a Transfer Beneficiary

This section describes how to create beneficiaries for Transfers.

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

Body Params

account_bank string

This is the Bank numeric code. It can be gotten from the /get banks endpoint.
account_number string

This is the account number of the customer.
beneficiary_name string

This is the name of the beneficiary for the Transfer.

Show optional parameters

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': '{{BASE_API_URL}}/beneficiaries',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  body: JSON.stringify({
      "account_number":"0690000034",
      "account_bank":"044",
      "beneficiary_name": "Ade Bond"
      })

};
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}}/beneficiaries",
  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\t\"account_number\": \"0690000034\",\n\t\"account_bank\": \"044\"\n,\n\t\"beneficiary_name\": \"Ade Bond\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/beneficiaries")

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\t\"account_number\": \"0690000034\",\n\t\"account_bank\": \"044\"\n,\n\t\"beneficiary_name\": \"Ade Bond\"\n}"

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

{
  "status": "success",
  "message": "Beneficiary created",
  "data": {
    "id": 3644,
    "account_number": "0690000034",
    "bank_code": "044",
    "full_name": "Ade Bond",
    "created_at": "2020-01-16T18:01:28.000Z",
    "bank_name": "ACCESS BANK NIGERIA"
  }
}

{}

List all Transfer Beneficiaries

This section describes how to get all beneficiaries saves for Transfers.

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

Query Params

Show optional parameters

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': '{{BASE_API_URL}}/beneficiaries',
  '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 => "{{BASE_API_URL}}/beneficiaries",
  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("{{BASE_API_URL}}/beneficiaries")

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": "Payout beneficiaries fetched",
  "meta": {
    "page_info": {
      "total": 9,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "data": [
    {
      "id": 3768,
      "account_number": "0690000040",
      "bank_code": "044",
      "full_name": "Alexis Sanchez",
      "meta": null,
      "created_at": "2020-01-20T16:09:24.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 3690,
      "account_number": "0690000039",
      "bank_code": "044",
      "full_name": "Dotun Ajib",
      "meta": null,
      "created_at": "2020-01-19T22:36:06.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 3644,
      "account_number": "0690000034",
      "bank_code": "044",
      "full_name": "Ade Bond",
      "meta": null,
      "created_at": "2020-01-16T18:01:28.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 3608,
      "account_number": "0690000044",
      "bank_code": "044",
      "full_name": "Mercedes Daniel",
      "meta": null,
      "created_at": "2020-01-15T11:58:02.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 3565,
      "account_number": "0690000038",
      "bank_code": "044",
      "full_name": "John Sunday",
      "meta": null,
      "created_at": "2020-01-14T05:53:34.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 3104,
      "account_number": "2540782773934",
      "bank_code": "000",
      "full_name": "Kwame Adew",
      "meta": null,
      "created_at": "2019-12-05T23:49:31.000Z",
      "bank_name": "FA-BANK"
    },
    {
      "id": 3093,
      "account_number": "0690000041",
      "bank_code": "044",
      "full_name": "Alexis Rogers",
      "meta": null,
      "created_at": "2019-12-05T21:29:57.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 2923,
      "account_number": "0690000032",
      "bank_code": "044",
      "full_name": "Pastor Bright",
      "meta": null,
      "created_at": "2019-11-28T08:15:29.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    },
    {
      "id": 2857,
      "account_number": "0690000031",
      "bank_code": "044",
      "full_name": "Forrest Green",
      "meta": null,
      "created_at": "2019-11-20T10:33:20.000Z",
      "bank_name": "ACCESS BANK NIGERIA"
    }
  ]
}


{}

Fetch a Transfer Beneficiary

This section describes how to get all details for a particular beneficiary.

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

Path Params

id int32

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

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': '{{BASE_API_URL}}/beneficiaries/2923',
  '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 => "{{BASE_API_URL}}/beneficiaries/2923",
  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("{{BASE_API_URL}}/beneficiaries/2923")

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": "Payout beneficiary fetched",
  "data": {
    "id": 2923,
    "account_number": "0690000032",
    "bank_code": "044",
    "full_name": "Pastor Bright",
    "meta": null,
    "created_at": "2019-11-28T08:15:29.000Z",
    "bank_name": "ACCESS BANK NIGERIA"
  }
}


{}

Delete a Transfer Beneficiary

This section describes how to remove a beneficiary from your beneficiary list.

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

Path Params

id int32

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

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': '{{BASE_API_URL}}/beneficiaries/3103',
  '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 => "{{BASE_API_URL}}/beneficiaries/3103",
  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("{{BASE_API_URL}}/beneficiaries/3103")

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": "Beneficiary deleted",
  "data": "Deleted"
}


{}
Loading...