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.

first_name string

The customer's first name.

last_name string

The customer's last name.

date_of_birth string

This is the date of birth of the cardholder. Expected date format is YYYY/MM/DD.

email string

This is the cardholder's email address.

phone string

This is mobile number of the user.

title string

This is title of the cardholder. Expected values are Mr, Mrs and Miss

gender string

This is the cardholder's gender. Expected values are M and F.

Show optional parameters

Headers

Authorization string

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

{
    "currency": "USD",
    "amount":5,
    "debit_currency": "NGN",
    "billing_name": "Example User.",
    "billing_address": "333, Fremont Street",
    "billing_city": "San Francisco",
    "billing_state": "CA",
    "billing_postal_code": "94105",
    "billing_country": "US",
    "first_name": "Example",
    "last_name": "User",
    "date_of_birth": "1996/12/30",
    "email": "userg@example.com",
    "phone": "07030000000",
    "title": "MR",
    "gender": "M",
    "callback_url": "https://webhook.site/b67965fa-e57c-4dda-84ce-0f8d6739b8a5"
}

{
    "status": "success",
    "message": "Card created successfully",
    "data": {
        "id": "199a344f-1dbe-4b00-ba4d-beb014345fae",
        "account_id": 2061620,
        "amount": "5.00",
        "currency": "USD",
        "card_pan": "5319938155020288",
        "masked_pan": "531993*******0288",
        "city": "San Francisco",
        "state": "CA",
        "address_1": "333 Fremont Street",
        "address_2": null,
        "zip_code": "94105",
        "cvv": "905",
        "expiration": "2025-09",
        "send_to": null,
        "bin_check_name": null,
        "card_type": "mastercard",
        "name_on_card": "Example user.",
        "created_at": "2022-09-21T16:54:53.3851427+00:00",
        "is_active": true,
        "callback_url": "https://webhook.site/b67965fa-e57c-4dda-84ce-0f8d6739b8a5"
    }
}

{
    "status": "error",
    "message": "Service is temporarily unvailable for user",
    "data": 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": [
    {
      "id": 5032304,
      "amount": 250,
      "fee": 0,
      "product": "Card Issuance Fee",
      "gateway_reference_details": "Card Issuance fee",
      "reference": "CF-BARTER-20230307042356745846",
      "response_code": 5,
      "gateway_reference": "New Local Card 16",
      "amount_confirmed": 0,
      "narration": "Card Issuance Fee",
      "indicator": "D",
      "created_at": "2023-03-07T16:23:56.193Z",
      "status": "Successful",
      "response_message": "Transaction was Successful",
      "currency": "NGN"
    },
    {
      "id": 5032303,
      "amount": 102,
      "fee": 0,
      "product": "Card Funding Debit",
      "gateway_reference_details": "Card Funding Transfers",
      "reference": "CF-BARTER-20230307042353348107",
      "response_code": 5,
      "gateway_reference": "New Local Card 16",
      "amount_confirmed": 0,
      "narration": null,
      "indicator": "D",
      "created_at": "2023-03-07T16:23:53.663Z",
      "status": "Successful",
      "response_message": "Transaction was Successful",
      "currency": "NGN"
    }
  ]
}

{
  "status": "error",
  "message": "Card details could not be found",
  "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