Tokenization

These endpoints allows the developer/merchant to manage tokenized transactions.

A card must initially be charged before it can be tokenized. Only cards can be tokenized.

Create a Tokenized Charge

This endpoint allows the developer to intiate a tokenized transactions.

post https://api.flutterwave.com/v3/tokenized-charges

Body Params

token string

This is the card token returned from the transaction verification endpoint as data.card.token

email string

This is the email address of the customer

currency string

This is the specified currency to charge in.

country string

This is the ISO country code of the merchant.

amount int32

This is the amount to be charged.

tx_ref string

This is a unique reference peculiar to the transaction being carried out.

first_name string

This is the firstname of the customer making the payment.

last_name string

This is the lastname of the customer making the payment.

narration string

This is a custom description added by the merchant

preauthorize boolean

TPass this value as true to preauthorize a tokenized charge.

ip string

This represents the current IP address of the customer carrying out the transaction.

device_fingerprint string

This is the fingerprint for the device being used. It can be generated using a library on whatever platform is being used.

payment_plan string

This is the id of a previously created payment plan needed to add a card user to the payment plan.

meta object
This is used to include additional payment information.
flightID string

This could be the extra information you want to pass

sideNote string

This could be any message you'd like to associate with this call

subaccounts object
This is an array of objects containing the subaccount IDs to split the payment into.
id string

This is the unique Id returned in the call to create a subaccount as data.subaccount_id

Headers

Authorization string

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

{
    "token": "flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k",
    "currency": "NGN",
    "country": "NG",
    "amount": 2000,
    "email": "developers@flutterwavego.com",
    "first_name": "Flutterwave",
    "last_name": "Developers",
    "ip": 123.876.0997.9,
    "narration": "Sample tokenized charge",
    "tx_ref": "tokenized-c-001"
}

{
   "status":"success",
   "message":"Charge successful",
   "data":{
      "id":277036749,
      "tx_ref":"new-live-test",
      "flw_ref":"FLW253481676",
      "redirect_url":"http://127.0.0",
      "device_fingerprint":"N/A",
      "amount":300,
      "charged_amount":300,
      "app_fee":4.2,
      "merchant_fee":0,
      "processor_response":"APPROVED",
      "auth_model":"noauth",
      "currency":"NGN",
      "ip":"123.456.543",
      "narration":"pstmn charge",
      "status":"successful",
      "payment_type":"card",
      "created_at":"2020-06-01T01:31:59.000Z",
      "account_id":17321,
      "customer":{
         "id":210745229,
         "phone_number":null,
         "name":"Flutterwave Developers",
         "email":"developers@flutterwavego.com",
         "created_at":"2020-06-01T01:27:24.000Z"
      },
      "card":{
         "first_6digits":"123456",
         "last_4digits":"7890",
         "issuer":"MASTERCARD GUARANTY TRUST BANK Mastercard Naira Debit Card",
         "country":"NG",
         "type":"MASTERCARD",
         "expiry":"08/22",
         "token":"flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k"
      }
   }
}

{}
3DS Tokenization

When a merchant tries charge a customer through a card token, the transaction goes through NOAUTH without any need for authentication.

If the merchant chooses to enforce 3DS, you should add do_3ds and redirect_url to the card token payload. By setting do_3ds to true, Flutterwave will charge the tokenized charge via VBVSECURECODE.

We will also redirect the user to the data.meta.authorization.redirect to authorise the token charge.

{
    "token": "flw-t1nf-1dd5c21361bb85c64deb7ff57ec891b2-m03k",
    "currency": "NGN",
    "country": "NG",
    "amount": 12000,
    "email": "developers@flutterwavego.com",
    "full_name": "Flutterwave Developers",
    "ip": "pstmn",
    "narration": "test_token_charge",
    "tx_ref": "testToken111",
    "do_3ds": true,
    "redirect_url": "https://flutterwave.com/ng",
    "meta": {
        "sub_meta_1": "meta_child_1",
        "sub_meta_2": "meta_child_2"
    }
}

{
    "status": "success",
    "message": "Charge initiated",
    "data": {
        "id": 2534420,
        "tx_ref": "testToken111",
        "flw_ref": "FLW-MOCK-0a6b80654370ff4b0987851ce0e611c0",
        "redirect_url": "https://flutterwave.com/ng",
        "device_fingerprint": "N/A",
        "amount": 12000,
        "charged_amount": 12000,
        "app_fee": 168,
        "merchant_fee": 0,
        "processor_response": "Approved",
        "auth_model": "VBVSECURECODE",
        "currency": "NGN",
        "ip": "pstmn",
        "narration": "test_token_charge",
        "status": "pending",
        "payment_type": "card",
        "created_at": "2021-10-07T17:43:46.000Z",
        "account_id": 20937,
        "customer": {
            "id": 1409822,
            "phone_number": null,
            "name": "Flutterwave Developers",
            "email": "developers@flutterwavego.com",
            "created_at": "2021-10-07T17:40:57.000Z"
        },
        "card": {
            "first_6digits": "553188",
            "last_4digits": "2950",
            "issuer": "MASTERCARD  CREDIT",
            "country": "NG",
            "type": "MASTERCARD",
            "expiry": "09/32"
        },
        "meta": {
            "authorization": {
                "mode": "redirect",
                "redirect": "https://ravesandboxapi.flutterwave.com/mockvbvpage?ref=FLW-MOCK-0a6b80654370ff4b0987851ce0e611c0&code=00&message=Approved. Successful&receiptno=RN1633628627056"
            }
        }
    }
}

Create bulk Tokenized Charges

This endpoint allows businesses to make multiple tokenized payments at once.

post https://api.flutterwave.com/v3/bulk-tokenized-charges

Body Params

retry_strategy object
This is an object that defines what should happen when the transaction fails. It contains 3 properties (retry_interval, retry_amount_variable, retry_attempt_variable).
retry_interval int32

This is the number of mins it should take for the retry to happen.

retry_amount_variable int32

This is the amount that would be retried after the specified number of attempts in percentage.

retry_attempt_variable int32

This is the number of times the retry should happen.

last_retry_attempt int32

This is the maximum number of retries. If not set 10 attempts will be made.

bulk_data object
An array of objects containing the tokenized bulk charge data. This array contains the same payload you passed to the single tokenize endpoint with multiple different values.
currency string

This is the specified currency to charge in. Expected values include NGN, GHS, KES, UGX, TZS, USD.

token string

This is the card token returned from the transaction verification endpoint as data.card.token

country string

This is the ISO country code of the merchant.

amount int32

This is the amount to be charged.

email string

This is the email address of the customer

tx_ref string

This is a unique reference peculiar to the transaction being carried out.

first_name string

This is the firstname of the customer making the payment.

last_name string

This is the lastname of the customer making the payment.

ip string

This represents the current IP address of the customer carrying out the transaction.

title string

This is the title of the bulk charge.

Headers

Authorization string

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

{
    "title": "Staff salary for June",
    "retry_strategy": {
        "retry_interval": 120,
        "retry_amount_variable": 60,
        "retry_attempt_variable": 2
    },
    "bulk_data": [
        {
            "currency": "NGN",
            "token": "flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k",
            "country": "NG",
            "amount": 3500,
            "email": "developers@flutterwavego.com",
            "first_name": "Flutterwave",
            "last_name": "Developers",
            "ip": "pstmn",
            "tx_ref": "akhlm-pstmn-blkchrg-xx6"
        },
        {
            "currency": "NGN",
            "token": "flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k",
            "country": "NG",
            "amount": 3000,
            "email": "hi@flutterwavego.com",
            "first_name": "Flutterwave",
            "last_name": "Support",
            "ip": "pstmn",
            "tx_ref": "akhlm-pstmn-blkchrge-xx7"
        }
    ]
}


{
  "status": "success",
  "message": "Bulk charge successful",
  "data": {
    "id": 130,
    "created_at": "2020-01-19T21:43:39.000Z",
    "approver": "N/A"
  }
}

{}

Get bulk Tokenized Charges

This endpoint allows you to get the status of a bulk tokenized charge

get https://api.flutterwave.com/v3/bulk-tokenized-charges/:bulk_id/transactions

Path Params

bulk_id int32

This is the id returned in the bulk charge response

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/bulk-tokenized-charges/156/transactions',
  headers: {
    '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 => 'https://api.flutterwave.com/v3/bulk-tokenized-charges/156/transactions',
  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;


import requests

url = "https://api.flutterwave.com/v3/bulk-tokenized-charges/156/transactions"

payload={}
headers = {
  'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

{
  "status": "success",
  "message": "Bulk charge transactions fetched",
  "data": [
    {
      "tx_ref": "akhlm-pstmn-blkchrg-xx6",
      "id": "1017000",
      "flw_ref": "FLW-M03K-7544dc8d157ca763bbcf864a24906f93",
      "device_fingerprint": "N/A",
      "amount": 3500,
      "currency": "NGN",
      "charged_amount": 3549,
      "app_fee": 49,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-01-19T21:46:29.000Z",
      "account_id": "73362",
      "amount_settled": 3450,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kizito Akhilome",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    },
    {
      "tx_ref": "akhlm-pstmn-blkchrg-xx6",
      "id": "1017004",
      "flw_ref": "FLW-M03K-4aa1f32bbc80a7cf9e42426e9b2d73eb",
      "device_fingerprint": "N/A",
      "amount": 3500,
      "currency": "NGN",
      "charged_amount": 3549,
      "app_fee": 49,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-01-19T21:49:29.000Z",
      "account_id": "73362",
      "amount_settled": 3450,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kizito Akhilome",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    },
    {
      "tx_ref": "akhlm-pstmn-blkchrg-xx6",
      "id": "1163067",
      "flw_ref": "FLW-M03K-9d02da3020c67ac05ade7b596881d59f",
      "device_fingerprint": "N/A",
      "amount": 3500,
      "currency": "NGN",
      "charged_amount": 3500,
      "app_fee": 1050,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-03-11T19:22:06.000Z",
      "account_id": "73362",
      "amount_settled": 2450,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kendrick Graham",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    },
    {
      "tx_ref": "akhlm-pstmn-blkchrge-xx6",
      "id": "1017001",
      "flw_ref": "FLW-M03K-bbd148a9569b709882da8437e123ba61",
      "device_fingerprint": "N/A",
      "amount": 3000,
      "currency": "NGN",
      "charged_amount": 3042,
      "app_fee": 42,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-01-19T21:46:30.000Z",
      "account_id": "73362",
      "amount_settled": 2950,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kizito Akhilome",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    },
    {
      "tx_ref": "akhlm-pstmn-blkchrge-xx6",
      "id": "1017005",
      "flw_ref": "FLW-M03K-3a046716482046ea974c73d73eaa4463",
      "device_fingerprint": "N/A",
      "amount": 3000,
      "currency": "NGN",
      "charged_amount": 3042,
      "app_fee": 42,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-01-19T21:49:30.000Z",
      "account_id": "73362",
      "amount_settled": 2950,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kizito Akhilome",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    },
    {
      "tx_ref": "akhlm-pstmn-blkchrge-xx6",
      "id": "1163068",
      "flw_ref": "FLW-M03K-02c21a8095c7e064b8b9714db834080b",
      "device_fingerprint": "N/A",
      "amount": 3000,
      "currency": "NGN",
      "charged_amount": 3000,
      "app_fee": 1000,
      "merchant_fee": 0,
      "processor_response": "Approved",
      "auth_model": "noauth",
      "ip": "pstmn",
      "narration": "Kizito Akhilome",
      "status": "successful",
      "payment_type": "card",
      "created_at": "2020-03-11T19:22:07.000Z",
      "account_id": "73362",
      "amount_settled": 2000,
      "card": {
        "expiry": "09/22",
        "type": "MASTERCARD",
        "country": "NIGERIA NG",
        "issuer": "MASTERCARD  CREDIT",
        "first_6digits": "553188",
        "last_4digits": "2950"
      },
      "customer": {
        "id": "252759",
        "email": "user@example.com",
        "phone_number": "0813XXXXXXX",
        "name": "Kendrick Graham",
        "created_at": "2020-01-15T13:26:24.000Z"
      }
    }
  ]
}

{}

Get status of bulk Tokenized Charges

This endpoint allows you to query the status of a bulk tokenized charge.

get https://api.flutterwave.com/v3/bulk-tokenized-charges/:bulk_id

Path Params

bulk_id int32

This is the id returned in the bulk charge response

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/bulk-tokenized-charges/156',
  headers: {
    '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 => 'https://api.flutterwave.com/v3/bulk-tokenized-charges/156',
  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;


import requests

url = "https://api.flutterwave.com/v3/bulk-tokenized-charges/156"

payload={}
headers = {
  'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

{
    "status": "success",
    "message": "Bulk charge fetched",
    "data": {
        "id": 156,
        "title": "akhlm blk tknzd chrg pstmn tst 1",
        "approver": "N/A",
        "processed_charges": 2,
        "pending_charges": 0,
        "total_charges": 2
    }
}

{}

Update Card token

This endpoints allow developers update the details tied to a customer's card token.

put https://api.flutterwave.com/v3/tokens/:token

Path Params

token string

This is the card token returned from the transaction verification endpoint as data.card.token

Body Params

email string

This is the email address of the customer

full_name string

This is the fullname of the customer making the payment.

phone_number string

This is the lastname of the customer making the payment.

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({
  "email": "user@example.com",
  "full_name": "Kendrick Graham",
  "phone_number": "0813XXXXXXX"
});

var config = {
  method: 'put',
  url: 'https://api.flutterwave.com/v3/tokens/flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k',
  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 => 'https://api.flutterwave.com/v3/tokens/flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k',
  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 =>'{
    "email": "user@example.com",
    "full_name": "Kendrick Graham",
    "phone_number": "0813XXXXXXX"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;



import requests
import json

url = "https://api.flutterwave.com/v3/tokens/flw-t1nf-f9b3bf384cd30d6fca42b6df9d27bd2f-m03k"

payload = json.dumps({
  "email": "user@example.com",
  "full_name": "Kendrick Graham",
  "phone_number": "0813XXXXXXX"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)


{
    "status": "success",
    "message": "Token details updated",
    "data": {
        "customer_email": "user@example.com",
        "customer_full_name": "Kendrick Graham",
        "customer_phone_number": "0813XXXXXXX",
        "created_at": "2020-01-15T13:26:24.000Z"
    }
}

{
    "status": "error",
    "message": "Token not found",
    "data": null
}
Loading...