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' bank account with Flutterwave for faster payments.

Generate a token

This endpoint helps you tokenize a customer's bank account via E-mandate. We recommed that you read our overview before you proceed with your integration.

post https://api.flutterwave.com/v3/accounts/tokenize

Body Params

account_bank string

The customer's bank. Query the get bank endpoint to retrieve the correct bank code.
account_number string

The customer's bank account number.
address string

The customer's residential address.
amount int32

The transaction amount.
email string

The customer's email address
phone_number string

The customer's phone number.

Show optional parameters

Headers

Authorization string

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

{
    "email": "user@example.com",
    "amount": "100",
    "address": "XYZ Example Street, Example City.",
    "phone_number": "08081806271",
    "account_bank": "058",
    "account_number": "0002093669",
    "start_date": "2024-06-22T01:28:00.000Z", 
    "end_date": "2025-04-04T01:28:00.000Z",
    "narration": "e-Mandate token for tester", 
}

{
    "status": "success",
    "message": "Account tokenization successful.",
    "data": {
        "status": "PENDING",
        "amount": 100,
        "address": "8992 Yundt Islands",
        "narration": "e-Mandate GTB",
        "account_id": 188360,
        "currency": "NGN",
        "end_date": "2025-09-30T01:28:00.000Z",
        "customer_id": 295028849,
        "start_date": "2024-10-01T10:47:18.095Z",
        "reference": "URF_EMANDATE_1727779638485_38482",
        "created_at": "2024-10-01T10:47:18.000Z",
        "response_code": "02",
        "response_message": "Welcome to NIBSS e-mandate authentication service, a seamless and convenient authentication experience. Kindly proceed with a token payment of N100:00 into account number 9020025928 with Fidelity Bank {Account name : NIBSS MANDATE ACTIVATION}. This payment will trigger the authentication of your mandate. Note: You have 10 minutes to complete this payment. Thank You"
        "mandate_consent" {
            "account_number":"9020025928",
            "bank": "070",
            "bank_name":"Fidelity Bank"
        }
    }
}

{
   "status": "error",
   "message": "Account details could not be resolved.",
   "data": null
}

Get a Token

This endpoint allows you to get the status of a generated token

get https://api.flutterwave.com/v3/accounts/token/:reference

Path Params

reference string

This is the reference of a generated token. This is returned as reference in the response when generating a token.

Headers

Authorization string

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

curl --request GET \
--url 'https://api.flutterwave.com/v3/accounts/token/:reference' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \

{
    "status": "success",
    "message": "Account token fetched successfully.",
    "data": {
        "token": "flw-1bt-5e1ba73fff7f1aa9642606d4d82a45d3-k3n",
        "reference": "URF_EMANDATE_1728385553726_55174",
        "status": "APPROVED",
        "start_date": "2024-10-08T11:05:52.000Z",
        "end_date": "2024-10-10T01:28:56.000Z",
        "amount": 100,
        "currency": "NGN",
        "address": "06548 Clay Path",
        "narration": "eMandate test on F4B flow for an nigerian merchant",
        "processor_code": "00",
        "processor_response": "Approved Or Completed Successfully",
        "active_on": "2024-10-08T11:36:26.724Z",
        "created_at": "2024-10-08T11:05:53.000Z",
        "updated_at": "2024-10-08T11:06:26.000Z",
        "account_id": 1091430,
        "customer_id": 585229978
    }
}

{
    "status": "error",
    "message": "No mandate token found for reference.",
    "data": null
}

Update token

This endpoint allow developers update the status of a customer's account token.

put https://api.flutterwave.com/v3/accounts/token/:reference

Path Params

reference string

This is the reference of a generated token. This is returned as reference in the response when generating a token.

Body Params

status string

Specifies the new status to which you want to update the current token. Supported values are 'ACTIVE', 'SUSPENDED', and 'DELETED'.

Headers

Authorization string

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

curl --request PUT \
--url 'https://api.flutterwave.com/v3/accounts/token/:reference' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
"status": "SUSPENDED" // supported statuses also include ACTIVE and DELETED 
}
'

{
    "status": "success",
    "message": "Account token updated successfully.",
    "data": {
        "token": "flw-1bt-XXXXXXXX-k3n",
        "reference": "URF_EMANDATE_1726257451101_39351",
        "status": "SUSPENDED",
        "start_date": "2024-09-13T19:57:30.000Z",
        "end_date": "2025-09-13T01:28:56.000Z",
        "amount": 100,
        "currency": "NGN",
        "address": "8463 Elouise Valley",
        "narration": "eMandate test on F4B flow for an nigerian merchant",
        "response_code": "00",
        "response_message": "Approved Or Completed Successfully",
        "active_on": "2024-09-13T23:02:55.000Z",
        "created_at": "2024-09-13T19:57:31.000Z",
        "updated_at": "2024-10-01T14:24:02.000Z",
        "account_id": 188360,
        "customer_id": 295028780
    }
}

{
    "status": "error",
    "message": "No account token found for reference.",
    "data": null
}

{
    "status": "error",
    "message": "status must be one of [ACTIVE, SUSPENDED, DELETED]",
    "data": null
}
Loading...