Virtual cards

Create A Virtual Card

post https://api.flutterwave.com/v3/virtual-cards

Body Params

currency string

This is the currency the card would be denominated in. Expected values include NGN and USD.

amount int32

This is the amount to prefund the card with on card creation.

debit_currency string

Please use this if you want to debit a different balance on Flutterwave to fund your card e.g. you are funding a USD card but you want to debit your NGN balance to fund the card.

billing_name string

This is the name that will appear on the card.

billing_address string

This is the registered address for the card. e.g. Your house address where you would receive your card statements.

billing_city string

This is the city registered with the card, it makes up part of the address the customer used for their card.

billing_state string

This is the State/County/Province/Region registered with the card. It is a two letter word representing the state in the billing country e.g CA, NY

billing_country string

This is the country registered with the card.

billing_postal_code int32

This is the zip code or postal card registered with the card.

callback_url string

This is a callback endpoint you provide where we send details about any transaction that occurs on the card.

Headers

Authorization string

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

var axios = require('axios');
var data = JSON.stringify({
  "currency": "USD",
  "amount": 5,
  "debit_currency": "NGN",
  "billing_name": "Flutterwave Developers",
  "billing_address": "3563 Huntertown Rd, Allison park, PA",
  "billing_city": "San Francisco",
  "billing_state": "CA",
  "billing_postal_code": "94105",
  "billing_country": "US"
});

var config = {
  method: 'post',
  url: 'https://api.flutterwave.com/v3/virtual-cards',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/transfers/166948/retries",
  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",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

require "uri"
require "net/http"

url = URI("{{BASE_API_URL}}/transfers/166948/retries")

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

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

{
    "status": "success",
    "message": "Card created successfully",
    "data": {
        "id": "43ec6e92-9eb7-48ad-91c8-7bee425a33cf",
        "account_id": 65637,
        "amount": "20,000.00",
        "currency": "NGN",
        "card_hash": "43ec6e92-9eb7-48ad-91c8-7bee425a33cf",
        "card_pan": "5366130699778900",
        "masked_pan": "536613*******8900",
        "city": "Lekki",
        "state": "Lagos",
        "address_1": "19, Olubunmi Rotimi",
        "address_2": null,
        "zip_code": "23401",
        "cvv": "134",
        "expiration": "2023-01",
        "send_to": null,
        "bin_check_name": null,
        "card_type": "mastercard",
        "name_on_card": "Jermaine Graham",
        "created_at": "2020-01-17T18:33:29.0130255+00:00",
        "is_active": true,
        "callback_url": null
    }
}

{}

Get All Virtual Cards

This call fetches all virtual cards created by the User

get https://api.flutterwave.com/v3/virtual-cards

Headers

Authorization string

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

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.flutterwave.com/v3/virtual-cards',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "/virtual-cards",
  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("/virtual-cards")

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":"Cards fetched successfully",
   "data":[
       {
         "id":"df3f2ba4-f137-4ce0-a6e3-3264c5831f17",
         "account_id":118661,
         "amount":"8999.00",
         "currency":"NGN",
         "card_hash":"df3f2ba4-f137-4ce0-a6e3-3264c5831f17",
         "card_pan":"5366136122489510",
         "masked_pan":"536613*******9510",
         "city":"Lekki",
         "state":"Lagos",
         "address_1":"19, Olubunmi Rotimi",
         "address_2":null,
         "zip_code":"23401",
         "cvv":"032",
         "expiration":"2024-11",
         "send_to":null,
         "bin_check_name":null,
         "card_type":"mastercard",
         "name_on_card":"1GM Main",
         "created_at":"2021-11-17T00:22:43.813Z",
         "is_active":true,
         "callback_url":null
      },
      {
         "id":"3f32e4bc-89b4-4bd2-bc55-22fbb04b882f",
         "account_id":118661,
         "amount":"4000.00",
         "currency":"USD",
         "card_hash":"3f32e4bc-89b4-4bd2-bc55-22fbb04b882f",
         "card_pan":"5366131828291260",
         "masked_pan":"536613*******1260",
         "city":"Lekki",
         "state":"Lagos",
         "address_1":"19, Olubunmi Rotimi",
         "address_2":null,
         "zip_code":"23401",
         "cvv":"725",
         "expiration":"2024-11",
         "send_to":null,
         "bin_check_name":null,
         "card_type":"mastercard",
         "name_on_card":"micheal spark",
         "created_at":"2021-11-16T18:46:09.567Z",
         "is_active":true,
         "callback_url":"https://boomchart.net/boompay_multi/use-virtual/"
      }
   ]
}

{}

Get A Virtual Card

This call gets a specific virtual card by ID created by the User with

get https://api.flutterwave.com/v3/virtual-cards/:id

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

Headers

Authorization string

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

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.flutterwave.com/v3/virtual-cards/{id}',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/df3f2ba4-f137-4ce0-a6e3-3264c5831f17",
  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}}/virtual-cards/df3f2ba4-f137-4ce0-a6e3-3264c5831f17")

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": "Card fetched successfully",
  "data": {
    "id": "df3f2ba4-f137-4ce0-a6e3-3264c5831f17",
    "account_id": 118661,
    "amount": "8999.00",
    "currency": "NGN",
    "card_hash": "df3f2ba4-f137-4ce0-a6e3-3264c5831f17",
    "card_pan": "5366136122489510",
    "masked_pan": "536613*******9510",
    "city": "Lekki",
    "state": "Lagos",
    "address_1": "19, Olubunmi Rotimi",
    "address_2": null,
    "zip_code": "23401",
    "cvv": "032",
    "expiration": "2024-11",
    "send_to": null,
    "bin_check_name": null,
    "card_type": "mastercard",
    "name_on_card": "1GM Main",
    "created_at": "2021-11-17T00:22:43.813Z",
    "is_active": true,
    "callback_url": null
  }
}

{}

Fund A Virtual Card

This funds a specific virtual card.

post https://api.flutterwave.com/v3/virtual-cards/:id/fund

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

Body Params

debit_currency string

Use this if you want to debit a different balance on Flutterwave to fund your card e.g. you are funding a USD card but you want to debit your NGN balance to fund the card

amount int

This is the amount you want to fund the card. The amount would be in the card currency

Headers

Authorization string

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

var axios = require('axios');

var data = JSON.stringify({
  "debit_currency": "USD",
  "amount": 5000
});

var config = {
  method: 'post',
  url: 'https://api.flutterwave.com/v3/virtual-cards/{id}/fund',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  },
  data: data
};


axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/fund",
  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    \"debit_currency\": \"NGN\",\n    \"amount\": 400000\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}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/fund")

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    \"debit_currency\": \"NGN\",\n    \"amount\": 400000\n}"

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

{
  "status": "success",
  "message": "Card funded successfully",
  "data": null
}

{}

Withdraw From A Virtual Card

This withdraws existing funds from a virtual card

post https://api.flutterwave.com/v3/virtual-cards/:id/withdraw

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

Body Params

amount string

This is the amount to be withdrawn

Headers

Authorization string

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

var axios = require('axios');

var data = JSON.stringify({"amount":"500000"})

var config = {
  method: 'put',
  url: '{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/withdraw',
  data: data,
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};


axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/withdraw",
  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\": 500000\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}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/withdraw")

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\": 500000\n}"

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

{
  "status": "success",
  "message": "Card transactions fetched successfully",
  "data": null
}

{}

Block/Unblock Virtual Card

This call terminates a virtual card created by the User.

put https://api.flutterwave.com/v3/virtual-cards/:id/status/:status_action

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

status_action string

This is the action you want to perform on the virtual card. Can be block or unblock

Headers

Authorization string

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

var axios = require('axios');

var config = {
  method: 'put',
  url: '{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/status/block',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};


axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/status/block",
  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}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/status/block")

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": "Card blocked successfully",
  "data": null
}

{}

Terminate A Virtual Card

This call terminates a virtual card created by the User.

put https://api.flutterwave.com/v3/virtual-cards/:id/terminate

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

Headers

Authorization string

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

var axios = require('axios');

var config = {
  method: 'put',
  url: 'https://api.flutterwave.com/v3/virtual-cards/{id}/terminate',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};


axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/1cb36826-8e05-40d6-8b9e-7f7439a141cb/terminate",
  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}}/virtual-cards/1cb36826-8e05-40d6-8b9e-7f7439a141cb/terminate")

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": "Card terminated successfully",
  "data": null
}

{}

Get A Virtuals Card's Transactions

This call fetches transactions by date range on a single card

get https://api.flutterwave.com/v3/virtual-cards/:id/transactions

Path Params

id string

This is the id of the virtual card to be fetched. You can get this id from the call to create a virtual card or list virtual cards as data.id

Query Params

from string

This is the start date of the transaction request period

to string

This is the end date of the transaction request period

index int

Pass 0 if you want to start from the beginning

size int

Specify how many transactions you want to retrieve in a single call

Headers

Authorization string

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

var axios = require('axios');

var config = {
  method: 'put',
  url: 'https://api.flutterwave.com/v3/virtual-cards/{id}/transactions',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  }
};


axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "{{BASE_API_URL}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/transactions?from=2019-01-01&to=2020-01-13&index=1&size=5",
  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}}/virtual-cards/38c9201a-fcb2-48fd-875e-6494ed79a6bb/transactions?from=2019-01-01&to=2020-01-13&index=1&size=5")

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": "Card transactions fetched successfully",
  "data": null
}

{}

Virtual cards

API Reference

Endpoints

Create A Virtual Card

Body Params

Headers

Get All Virtual Cards

Headers

Get A Virtual Card

Path Params

Headers

Fund A Virtual Card

Path Params

Body Params

Headers

Withdraw From A Virtual Card

Path Params

Body Params

Headers

Block/Unblock Virtual Card

Path Params

Headers

Terminate A Virtual Card

Path Params

Headers

Get A Virtuals Card's Transactions

Path Params

Query Params

Headers