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

Tokenization

Tokenize your customers' cards with Flutterwave for faster payments.

Create a Tokenized Charge

This endpoint helps you tokenize a customer's card. We recommed that you read our overview before you proceed with your integration.

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

The customer's email address.
currency string

This is the specified currency to charge in.
amount int32

This is the amount to be charged.
tx_ref string

This is a unique reference for the transaction.

Show optional parameters

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": "user@example.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":"user@example.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"
      }
   }
}

{}

Create bulk Tokenized Charges

Tokenize multiple cards at once. Please read our overview on bulk tokenizations before you continue.

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

Body Params

retry_strategy object
This object defines retries for failed tokenization attempts.
retry_interval int32

The number in minutes for the next retry attempt.
retry_amount_variable int32

The amount to be retried after the specified number of attempts in percentage.
retry_attempt_variable int32

The number of retries to make after the initial tokenization attempt.
last_retry_attempt int32

The maximum number of retries to attempt. If unspecified, It is set to 10 by default.
bulk_data object
The array of objects containing your charge data. Each object in the array hold the request data for each card.
currency string

This is the specified currency to charge in.
token string

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

country string

This is the 2-letter country code.
amount int32

This is the amount to be charged in the transaction.
email string

The customer's email address.
tx_ref string

This is a unique reference for the transaction.
first_name string

The customer's first name.
last_name string

The customer's last name
ip string

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

Show optional parameters

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": "user@example.com",
            "first_name": "Flutterwave",
            "last_name": "Developers",
            "ip": "123.876.0997.9",
            "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": "123.876.0997.9",
            "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

The customer's email address.
full_name string

This is the fullname of the customer making the payment.
phone_number string

This is the mobile number 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...