Payment Plans

This section describes how merchants and developers can create and manage their respective payment plans.

Create Payment Plan

This section describes how to create a payment plan with Flutterwave.

post https://api.flutterwave.com/v3/payment-plans

Body Params

amount int32

This is the amount to charge all customers subscribed to this plan.

name string

This will determine the frequency of the charges for this plan. Could be yearly, quarterly, monthly, weekly, daily, etc.

interval string

This will determine the frequency of the charges for this plan. Could be yearly, quarterly, monthly, weekly, daily, etc.

duration int32

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.

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}}/payment-plans',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {SEC_KEY}'
  },
  body: JSON.stringify({"amount":5000,"name":"the akhlm postman plan 2","interval":"monthly","duration":48})

};
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}}/payment-plans",
  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    \"amount\": 5000,\n    \"name\": \"the akhlm postman plan 2\",\n    \"interval\": \"monthly\",\n    \"duration\": 48\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("{{BASE_API_URL}}/payment-plans")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"
request.body = "{\n    \"amount\": 5000,\n    \"name\": \"the akhlm postman plan 2\",\n    \"interval\": \"monthly\",\n    \"duration\": 48\n}"

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

{
  "status": "success",
  "message": "Payment plan created",
  "data": {
    "id": 3807,
    "name": "the akhlm postman plan 2",
    "amount": 5000,
    "interval": "monthly",
    "duration": 48,
    "status": "active",
    "currency": "NGN",
    "plan_token": "rpp_12d2ef3d5ac1c13b9d30",
    "created_at": "2020-01-16T18:08:19.000Z"
  }
}

{}

Get payment plans

This section describes how to fetch all payment plans on your account.

get https://api.flutterwave.com/v3/payment-plans

Query Params

from string

This is the specified date to start the list from. YYYY-MM-DD.

to string

The is the specified end period for the search. YYYY-MM-DD.

page int32

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

amount int32

This is the exact amount set when creating the payment plan.

currency string

This is the currency the payment plan amount is charged in.

interval string

This is how often the payment plan is set to execute.

status string

This is the status of the payment plan.

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}}/payment-plans',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {SEC_KEY}'
  }
};
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}}/payment-plans",
  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(
    "Content-Type: application/json",
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/payment-plans")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"

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

{
  "status": "success",
  "message": "Payment plans fetched",
  "meta": {
    "page_info": {
      "total": 11,
      "current_page": 1,
      "total_pages": 2
    }
  },
  "data": [
    {
      "id": 3809,
      "name": "akhlm postman updated",
      "amount": 0,
      "interval": "daily",
      "duration": 0,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_59072efa415936a5cfbf",
      "created_at": "2020-01-16T18:10:32.000Z"
    },
    {
      "id": 3808,
      "name": "N/A",
      "amount": 5000,
      "interval": "daily",
      "duration": 0,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_e8b0c18d665d849f033b",
      "created_at": "2020-01-16T18:10:22.000Z"
    },
    {
      "id": 3807,
      "name": "akhlm postman update",
      "amount": 5000,
      "interval": "monthly",
      "duration": 48,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_12d2ef3d5ac1c13b9d30",
      "created_at": "2020-01-16T18:08:19.000Z"
    },
    {
      "id": 3806,
      "name": "the akhlm postman plan",
      "amount": 5000,
      "interval": "weekly",
      "duration": 52,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_25f3bbeae9333211dd35",
      "created_at": "2020-01-16T18:05:01.000Z"
    },
    {
      "id": 3772,
      "name": "The selma Postman Plan 2",
      "amount": 5000,
      "interval": "weekly",
      "duration": 52,
      "status": "cancelled",
      "currency": "NGN",
      "plan_token": "rpp_d2f295acd1970438f822",
      "created_at": "2020-01-14T05:43:48.000Z"
    },
    {
      "id": 3771,
      "name": "The selma Postman Plan",
      "amount": 5000,
      "interval": "monthly",
      "duration": 12,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_3e0968c64209b7a0f25c",
      "created_at": "2020-01-14T05:42:57.000Z"
    },
    {
      "id": 3700,
      "name": "The selma Plan",
      "amount": 2000,
      "interval": "monthly",
      "duration": 12,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_93fef9f31f7b6abb5882",
      "created_at": "2020-01-10T13:29:46.000Z"
    },
    {
      "id": 3699,
      "name": "N/A",
      "amount": 0,
      "interval": "daily",
      "duration": 0,
      "status": "cancelled",
      "currency": "NGN",
      "plan_token": "rpp_93d443ad355b5efb4fe3",
      "created_at": "2020-01-10T13:28:47.000Z"
    },
    {
      "id": 3698,
      "name": "The selma Editted",
      "amount": 0,
      "interval": "daily",
      "duration": 0,
      "status": "cancelled",
      "currency": "NGN",
      "plan_token": "rpp_f1ef76170b1a7bc1110b",
      "created_at": "2020-01-10T13:28:13.000Z"
    },
    {
      "id": 3657,
      "name": "akhlm-stag",
      "amount": 2000,
      "interval": "hourly",
      "duration": 4,
      "status": "active",
      "currency": "NGN",
      "plan_token": "rpp_fed796f8be1f5469a41f",
      "created_at": "2019-12-31T16:51:28.000Z"
    }
  ]
}

{}

Get a Payment Plan

This section describes how to get a single payment plan

get https://api.flutterwave.com/v3/payment-plans/:id

Path Params

id int32

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

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}}/payment-plans/3806',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {SEC_KEY}'
  }
};
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}}/payment-plans/3806",
  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(
    "Content-Type: application/json",
    "Authorization: Bearer {SEC_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/payment-plans/3806")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"

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

{
  "status": "success",
  "message": "Payment plan fetched",
  "data": {
    "id": 3806,
    "name": "the akhlm postman plan",
    "amount": 5000,
    "interval": "weekly",
    "duration": 52,
    "status": "active",
    "currency": "NGN",
    "plan_token": "rpp_25f3bbeae9333211dd35",
    "created_at": "2020-01-16T18:05:01.000Z"
  }
}

{}

Update a Payment Plan

This endpoint help the merchant/developer update an existing payment plan.

put https://api.flutterwave.com/v3/payment-plans/:id

Path Params

id int32

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

Body Params

amount int32

The new name of the payment plan.

status string

The new status of the payment plan.

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': 'PUT',
  'url': '{{BASE_API_URL}}/payment-plans/3807',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {SEC_KEY}'
  },
  body: JSON.stringify({"name":"January neighbourhood contribution ","status":"active"})

};
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}}/payment-plans/3807",
  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    \"name\": \"January neighbourhood contribution \",\n    \"status\": \"active\"\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("{{BASE_API_URL}}/payment-plans/3807")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"
request.body = "{\n    \"name\": \"January neighbourhood contribution \",\n    \"status\": \"active\"\n}"

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

{
  "status": "success",
  "message": "Payment plan updated",
  "data": {
    "id": 3807,
    "name": "akhlm postman update",
    "plan_token": "rpp_12d2ef3d5ac1c13b9d30",
    "status": "active",
    "currency": "NGN",
    "amount": 5000,
    "duration": 48,
    "interval": "monthly",
    "created_at": "2020-01-16T18:08:19.000Z"
  }
}

{}

Cancel a Payment Plan

This endpoint help the merchant/developer cancel an existing payment plan.

put https://api.flutterwave.com/v3/payment-plans/:id/cancel

Path Params

id int32

This is the unique id of the payment plan you want to cancel

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': 'PUT',
  'url': '{{BASE_API_URL}}/payment-plans/3807/cancel',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {SEC_KEY}'
  }
};
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}}/payment-plans/3807/cancel",
  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_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("{{BASE_API_URL}}/payment-plans/3807/cancel")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Put.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {SEC_KEY}"

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

{
  "status": "success",
  "message": "Payment plan cancelled",
  "data": {
    "id": 3807,
    "name": "the akhlm postman plan 2",
    "plan_token": "rpp_12d2ef3d5ac1c13b9d30",
    "status": "cancelled",
    "currency": "NGN",
    "amount": 5000,
    "duration": 48,
    "interval": "monthly",
    "created_at": "2020-01-16T18:08:19.000Z"
  }
}

{}

Payment Plans

API Reference

Endpoints

Payment Plans

Create Payment Plan

Body Params

Headers

Get payment plans

Query Params

Headers

Get a Payment Plan

Path Params

Headers

Update a Payment Plan

Path Params

Body Params

Headers

Cancel a Payment Plan

Path Params

Headers