Direct Card Charge

Learn how to collect payments with Cards.

We recommend checking out the introductory section to understand the basics of direct charge first. This guide assumes you’ve read that.

Direct card charge allows you to charge both local cards (issued in your country of operation) and international cards. This is useful if your customers are predominantly credit/debit card users and you’d prefer they manage payments via your app.

The country of operation for your Flutterwave account is the country you selected during account creation. Payments will be considered international if you accept cards issued outside this country or charge in currencies other than your local currency.

Prerequisite

Compliance

Using direct card charges involves handling some very sensitive customer data, so a PCI DSS compliance certificate is required. When you’ve got one, contact your Relationship Manager or reach out to [e-mail] to enable this feature on your account.

Payment Flow

Using a card charge involves four main steps:

1. Initiating the payment: You send the transaction details and the customer’s payment details to the charge card endpoint.
2. Authorize the charge: We tell you the details needed to authorize the charge, you get those from the customer, and you send them to the same charge card endpoint.
3. Validate the charge: Think of this as a second layer of authentication. The customer provides some info to validate the charge (such as an OTP), and you send that to us (via the validate charge endpoint). This completes the payment.
4. Verify the payment: As a failsafe, you’ll call our API to verify that the payment was successful before giving value (via the verify transaction endpoint).

In some scenarios, steps 2 and/or 3 might be skipped. For example, cards that use 3DS authentication won’t have a validation stage. We’ll explain the different scenarios in this guide.

Recurring Payments

You can also collect recurring payments from customers with direct card charges. See our guide to card tokenization.

Card Authorization Models

When you make a card charge request, Flutterwave will evaluate the card to determine its authorization model—a card personal identification number (PIN), an address verification system (AVS), a 3DS redirect, or no authorization at all.

If no authorization is required, the charge is completed, and you can skip to verifying the payment.

For cards that require authorization, we’ll send you a prompt telling you what parameters are needed for that authorization model so the cardholder can authenticate their transaction.

Collect the Customer’s Payment Details

First, you’ll need the customer’s card details. You can collect these with a simple HTML form like the one below:

After collecting the card details, you’ll need to add some other details to make up the full payload, including:

• tx_ref: A unique reference code that you’ll generate for each transaction.
• amount: The amount to be charged for the transaction.
• currency: The currency to be used for the charge.
• email: The customer’s email address.
• redirect_url (optional): The url we should redirect to after the customer completes payment. For 3DSecure payments, we’ll append data (the transaction response data) to the URL as query parameters.
• meta (optional): Any extra details you wish to attach to the transaction. For instance, you could include the flight_id or product_url.

See the charge card endpoint for a full list of available options.

Request Payload

{
	"card_number": "5531886652142950",
	"expiry_month": "09",
	"expiry_year": "32",
	"cvv": "564",
	"currency": "NGN",
	"amount": "7500",
	"email": "[e-mail]",
	"fullname": "Flutterwave Developers",
	"phone_number": "[phone]",
	"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
	"redirect_url": "https://example_company.com/success"
}

Preauthorization

Preauthorizing a card is a way to place a “hold” on the amount you plan to charge a customer. This is helpful if you intend to bill the customer after they use your service, but you want to ensure they have enough funds to pay before providing them the service.

For instance, if you run a ride-hailing business or hotel, you’d typically charge the customer after their trip or stay. However, you can estimate how much the trip or stay will cost and preauthorize the charge. This will “lock” the requested amount for a maximum of 7 working days. That way, you can be sure the customer will be able to pay their bill after rendering the service.

Approval Required

Using preauthorization requires approval. Contact us at [e-mail] so we can enable it on your account.

To preauthorize a card, pass a preauthorize parameter in your card charge payload.

{
* "preauthorize": true,
* "usesecureauth": true,// set to true if you want to charge the card with 3DS, set to false to charge with noauth
  "card_number": "-bank-branches",
  "expiry_month": "09",
  "expiry_year": "31",
  "cvv": "789",
  "currency": "NGN",
  "amount": "7500",
  "email": "[e-mail]",
  "fullname": "Flutterwave Developers",
  "phone_number": "[phone]",
  "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
  "redirect_url": "https://example_company.com/success"
}

This will place a hold on the amount but won’t actually charge the card. When the service has been rendered, and you’re ready to charge the customer, you can use the capture pre-auth charge endpoint. You can also pass in the amount you want to charge. Note that the captured amount must be less than or equal to the preauthorized amount.

const axios = require('axios');

await axios.post(
	`https://api.flutterwave.com/v3/charges/${orderRef}/capture`,
	{ amount: 1200 },
	{
		headers: {
			Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`,
			'Content-Type': 'application/json',
		},
	}
);

You can also release the hold on the funds (if the customer does not eventually use the service) or refund part of the held amount. Any holds that you don’t capture, void, or refund will automatically be voided after 7 working days.

External 3DS

External 3D Secure (3DS) is a feature that allows you to control how the identity of your customer (the cardholder) is verified by using a custom provider of your choice.

Unlike the regular 3DS, where the identity verification process is automatically handled for you by the payment system, External 3DS gives you the flexibility to integrate and manage this verification process according to your specific needs.

Approval Required

This feature is unavailable by default. Send us an email at [e-mail] to enable external 3DS on your account.

Encrypt the Payload Request

If you’re using one of our backend SDKs, you should skip this step, as they’ll automatically encrypt the payload for you when sending the request. Head on to the next step.

Next, you’ll encrypt the payload you’ve built up. You’ll need your encryption key (from the Settings > API section of your Dashboard), and you’ll use the 3DES algorithm for encryption. You can see examples of this in our encryption guide.

Now, you’ll wrap the encrypted payload inside a JSON body like this:

{
	"client": "Of8p6iJUVUezgvjUkjjJsP8aPd6CjHR3f9ptHiH5Q0+2h/FzHA/X1zPlDmRmH5v+GoLWWB4TqEojrKhZI38MSjbGm3DC8UPf385zBYEHZdgvQDsacDYZtFEruJqEWXmbvw9sUz+YwUHegTSogQdnXp7OGdUxPngiv6592YoL0YXa4eHcH1fRGjAimdqucGJPurFVu4sE5gJIEmBCXdESVqNPG72PwdRPfAINT9x1bXemI1M3bBdydtWvAx58ZE4fcOtWkD/IDi+o8K7qpmzgUR8YUbgZ71yi0pg5UmrT4YpcY2eq5i46Gg3L+fxFl4tauG9H4WBChF0agXtP4kjfhfYVD48N9Hrt"
}

You can then use this payload to initiate payment.

Initiate Payment

To initiate payment, send your encrypted payload to our charge card endpoint.

If you’re using one of our SDKs, you’ll pass in the payload directly, and we’ll encrypt it for you. Otherwise, you can do the encryption manually as shown above, then call the endpoint:

Node.js

// Installation: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);

const payload = {
card_number: '5531886652142950',
expiry_month: '09',
expiry_year: '32',
cvv: '564',
currency: 'NGN',
amount: '7500',
email: '[e-mail]',
fullname: 'Flutterwave Developers',
phone_number: '[phone]',
tx_ref: 'UNIQUE_TRANSACTION_REFERENCE',
redirect_url: 'https://example_company.com/success',
enckey: process.env.FLW_ENCRYPTION_KEY
}

flw.Charge.card(payload)
.then(response => console.log(response));

Authorize the Payment

This next step will vary depending on the type of card you’re charging. After initiating a charge, the customer may need to authorize the charge on their card. Card authorization methods are typically one of the following:

• PIN: The customer enters the card PIN to authorize the payment.
• AVS (Address Verification System): The customer enters details of the card’s billing address. This is often used for international cards.
• 3DS (3D Secure): The customer needs to be redirected to a secure webpage to complete the payment.
• None: In some cases, the card may not need any authorization steps at all.

The response you get from the previous step (initiating the payment) will tell you the authorization required for the card (if any) in the meta.authorization field. The meta.authorization.mode key indicates the type of authorization that is needed, while the meta.authorization.fields key indicates the fields you need to collect from the customer. For instance:

• If the mode is "pin", then the card requires PIN authentication. You’ll need to collect the customer’s PIN.
• If the mode is "avs_noauth", the card requires AVS authentication. You’ll need to collect the specified fields (for example, city, address, state, country, and zipcode).
• If the mode is "redirect", then you won’t be collecting any extra fields. Instead, you’ll redirect to the specified URL (in meta.authorization.redirect) for the customer to authenticate with their bank.
• In some cases, the card doesn’t need any additional authentication, so you can skip to verifying the payment. In that case, the data.status field will be either "successful" or "failed".

Here are some sample responses for the different scenarios:

PIN Authorization

{
  "status": "success",
  "message": "Charge authorization data required",
  "meta": {
    "authorization": {
      "mode": "pin",
      "fields": [
        "pin"
      ]
    }
  }
}

Handling 3DS Authorization

With 3DS authorization, all you’ll need to do is redirect your user to the specified redirect URL (the meta.authorization.redirect field). The user will then complete the authorization on their bank’s page, then we’ll redirect back to the redirect_url you specified initially, appending the tx_ref and status to the URL as query parameters.

Before redirecting, you should store the transaction ID returned from the 3DS response ( data.id ), as you’ll need it to verify the payment when we redirect back to your app.

Node.js

const transactionId = response.data.id;
const flwRef = response.data.flw_ref;

// Store the transaction ID
// so we can look it up later with the tx_ref
await redis.setAsync(`txref-${txRef}`, transactionId);
const authUrl = response.meta.authorization.redirect;
res.redirect(authUrl);

With 3DS authorization, you don’t need to validate the charge. In your redirect route, you can then skip to verifying the payment.

Handling PIN and AVS Authorization

With PIN and AVS authorization, you’ll need to collect the specified fields (i.e. the card’s PIN or address details) and add them to your initial payload (in an authorization object). Then, you’ll encrypt the new payload and send it to the same charge card endpoint.

This means you’ll be calling the charge card endpoint twice—the first time to find out the authorization mode, and the second to authorize the charge.

In this example, that means we’ll end up with a payload like this:

PIN Authorization

{
  "card_number": "5531886652142950",
  "expiry_month": "09",
  "expiry_year": "32",
  "cvv": "564",
  "currency": "NGN",
  "amount": "7500",
  "email": "[e-mail]",
  "phone_number": "[phone]",
  "fullname": "Flutterwave Developers",
  "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
  "redirect_url":"https://example_company.com/success",
  "authorization": {
    "mode": "pin",
    "pin": "3310"
  }
}

Then, you encrypt the new payload and send it to the charge card endpoint.

Validate the Charge

After encrypting and sending the new payload, if the authorization is successful, you’ll get a response that looks like one of these:

OTP Required

{
  "status": "success",
  "message": "Charge initiated",
  "data": {
    "id": 288192886,
    "tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
    "flw_ref": "FLEG8147171639979534513071",
    "device_fingerprint": "N/A",
    "amount": 7500,
    "charged_amount": 7500,
    "app_fee": 105,
    "merchant_fee": 0,
    "processor_response": "Kindly enter the OTP sent to *******0328",
    "auth_model": "PIN",
    "currency": "NGN",
    "ip": "N/A",
    "narration": "CARD Transaction ",
    "status": "pending",
    "auth_url": "N/A",
    "payment_type": "card",
    "fraud_status": "ok",
    "charge_type": "normal",
    "created_at": "2021-07-15T14:06:55.000Z",
    "account_id": 17321,
    "customer": {
      "id": 370672,
      "phone_number": "2349012345678",
      "name": "Flutterwave Developers",
      "email": "[e-mail]",
      "created_at": "2021-07-15T14:06:55.000Z"
    },
    "card": {
      "first_6digits": "553188",
      "last_4digits": "2950",
      "issuer": "MASTERCARD  CREDIT",
      "country": "NG",
      "type": "MASTERCARD",
      "expiry": "09/32"
    }
  },
  "meta": {
    "authorization": {
      "mode": "otp",
      "endpoint": "/v3/validate-charge"
    }
  }
}

This response tells you how to proceed.

Note that even though the status field is "success" (the charge has been initiated), the data.status field is "pending" , meaning that the transaction hasn’t yet been approved by the customer. You’ll need to validate the transaction to complete it.

As you can see, depending on the type of card you’re charging, you’ll get one of two things in the new meta.authorization.mode field:

• redirect: in this case, you’ll get a processor_response message saying "Pending Validation". You’ll need to redirect your customers to the returned link where they can complete the payment. Afterwards, we’ll redirect the customer back to the redirect_url you specified earlier, with a tx_ref and status. This means you don’t need to do anything else, and your redirect handler can skip to verifying the payment.
• otp: This means an OTP has been sent to your customer’s mobile phone. The processor_response will contain instructions you can display to the cardholder. When the user enters the OTP, you’ll need to validate the transaction by calling our validate charge endpoint with the customer’s OTP and the flw_ref for the transaction (which was returned in the earlier response).

Node.js

const response = await flw.Charge.validate({
    otp: req.body.otp,
    flw_ref: req.session.flw_ref
});

You’ll get a response like this:

Validation Successfully

{
	"status": "success",
	"message": "Charge validated",
	"data": {
		"id": 288192886,
		"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
		"flw_ref": "FLEG8147171639979534513071",
		"device_fingerprint": "N/A",
		"amount": 7500,
		"charged_amount": 7500,
		"app_fee": 105,
		"merchant_fee": 0,
		"processor_response": "successful",
		"auth_model": "PIN",
		"currency": "NGN",
		"ip": "N/A",
		"narration": "CARD Transaction ",
		"status": "successful",
		"auth_url": "N/A",
		"payment_type": "card",
		"fraud_status": "ok",
		"charge_type": "normal",
		"created_at": "2021-07-15T14:06:55.000Z",
		"account_id": 17321,
		"customer": {
			"id": 370672,
			"phone_number": "2349012345678",
			"name": "Flutterwave Developers",
			"email": "[e-mail]",
			"created_at": "2021-07-15T14:06:55.000Z"
		},
		"card": {
			"first_6digits": "553188",
			"last_4digits": "2950",
			"issuer": "MASTERCARD  CREDIT",
			"country": "NG",
			"type": "MASTERCARD",
			"expiry": "09/32"
		}
	}
}

The data.status field indicates that the charge was successful. However, as a safety measure, always verify the payment.

Handling Redirects

When redirecting users, the URL structure typically places the query string before the fragment identifier (#). This is standard web behavior and may cause errors if your application relies on the hash for routing.

https://example.com/path?status=successful&tx_ref=xyz&transaction_id=123#fragment

If your application needs the hash to appear before the query string (e.g. for frontend routing), and Direct Charge is stripping the hash, use #redirect_as_post, to ensure that the hash remains part of the URL during the redirect.

Redirects as a POST Request

To ensure that a redirect is performed using a POST request instead of the default GET request, append #redirect_as_post to the redirect_url.

{
  ...
  "redirect_url": "https://example.com/#/path#redirect_as_post",
  ...
}

After completing your payment, Flutterwave appends the transaction information to the body of the request. The #redirect_as_post helps you retain the fragment identifier needed for correct routing in your application.

• If your redirect_url is a frontend application:
  • The POST request body will not be accessible directly.
  • We recommend the use of webhooks or the verify endpoint to retrieve the transaction status after the redirect.
• If the redirect_url is a backend system:
  • The backend can process both GET and POST requests, making the request body accessible.

Redirects using Ignore_Opener

If you experience issues when redirecting your users to new windows/tabs, e.g. redirect within single-page applications (SPAs), append #ignore_opener to the redirect_url.

This prevents the redirected page from accessing the window.opener property, ensuring it opens separately and can’t immediately redirect to a malicious URL.

{
  ...
  "redirect_url": "https://example.com/#/path#ignore_opener",
  ...
}

Verify the Payment

Almost done! The last step is to verify that the payment was successful before giving value to your customer. To do so, call our verify transaction endpoint with your transaction_id. See our guide on transaction verification for more details.

Node.js

// If we came from a redirect, we'll need to
// fetch the transactionID we stored earlier, using the tx_ref
const txRef = req.query.tx_ref
const transactionId = await redis.getAsync(`txref-${txRef}`);

// Otherwise, if we came from a validate process,
// we can just get the transaction ID from the response
const transactionId = response.data.id;
flw.Transaction.verify({
id: transactionId
});

You’ll get a response that looks like this, and you can see that the data.status field is now "successful".

Payment Successful

{
	"status": "success",
	"message": "Transaction fetched successfully",
	"data": {
		"id": 288192886,
		"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
		"flw_ref": "FLEG8147171639979534513071",
		"device_fingerprint": "N/A",
		"amount": 7500,
		"currency": "NGN",
		"charged_amount": 7500,
		"app_fee": 105,
		"merchant_fee": 0,
		"processor_response": "successful",
		"auth_model": "PIN",
		"ip": "N/A",
		"narration": "CARD Transaction ",
		"status": "successful",
		"payment_type": "card",
		"created_at": "2021-07-15T14:06:55.000Z",
		"account_id": 17321,
		"card": {
			"first_6digits": "553188",
			"last_4digits": "2950",
			"issuer": "MASTERCARD  CREDIT",
			"country": "NG",
			"type": "MASTERCARD",
			"token": "flw-t1nf-dac504fefbc7fcac6b776c0f33c2f774-m03k",
			"expiry": "09/32"
		},
		"amount_settled": 7395,
		"customer": {
			"id": 370672,
			"phone_number": "2349012345678",
			"name": "Flutterwave Developers",
			"email": "[e-mail]",
			"created_at": "2021-07-15T14:06:55.000Z"
		}
	}
}

All done

Examples

Putting it all together, here’s what an implementation of direct card charge might look like:

Node.js

// In an Express-like app:

// The route where we initiate payment (Steps 1 - 3)
app.post('/pay', async (req, res) => {
	const payload = {
		card_number: req.body.card_number,
		cvv: req.body.card_cvv,
		expiry_month: req.body.card_expiry_year,
		expiry_year: req.body.card_expiry_year,
		currency: 'NGN',
		amount: product.price,
		email: req.user.email,
		fullname: req.body.card_name,
		phone_number: req.user.phone_number,
		// Generate a unique transaction reference
		tx_ref: generateTransactionReference(),
		redirect_url: process.env.APP_BASE_URL + '/pay/redirect',
		enckey: process.env.FLW_ENCRYPTION_KEY,
	};
	const response = await flw.Charge.card(payload);

	switch (response?.meta?.authorization?.mode) {
		case 'pin':
		case 'avs_noauth':
			// Store the current payload
			req.session.charge_payload = payload;
			// Now we'll show the user a form to enter
			// the requested fields (PIN or billing details)
			req.session.auth_fields = response.meta.authorization.fields;
			req.session.auth_mode = response.meta.authorization.mode;
			return res.redirect('/pay/authorize');
		case 'redirect':
			// Store the transaction ID
			// so we can look it up later with the flw_ref
			await redis.setAsync(
				`txref-${response.data.tx_ref}`,
				response.data.id
			);
			// Auth type is redirect,
			// so just redirect to the customer's bank
			const authUrl = response.meta.authorization.redirect;
			return res.redirect(authUrl);
		default:
			// No authorization needed; just verify the payment
			const transactionId = response.data.id;
			const transaction = await flw.Transaction.verify({
				id: transactionId,
			});
			if (transaction.data.status == 'successful') {
				return res.redirect('/payment-successful');
			} else if (transaction.data.status == 'pending') {
				// Schedule a job that polls for the status of the payment every 10 minutes
				transactionVerificationQueue.add({
					id: transactionId,
				});
				return res.redirect('/payment-processing');
			} else {
				return res.redirect('/payment-failed');
			}
	}
});

// The route where we send the user's auth details (Step 4)
app.post('/pay/authorize', async (req, res) => {
	const payload = req.session.charge_payload;
	// Add the auth mode and requested fields to the payload,
	// then call chargeCard again
	payload.authorization = {
		mode: req.session.auth_mode,
	};
	req.session.auth_fields.forEach((field) => {
		payload.authorization.field = req.body[field];
	});
	const response = await flw.Charge.card(payload);

	switch (response?.meta?.authorization?.mode) {
		case 'otp':
			// Show the user a form to enter the OTP
			req.session.flw_ref = response.data.flw_ref;
			return res.redirect('/pay/validate');
		case 'redirect':
			const authUrl = response.meta.authorization.redirect;
			return res.redirect(authUrl);
		default:
			// No validation needed; just verify the payment
			const transactionId = response.data.id;
			const transaction = await flw.Transaction.verify({
				id: transactionId,
			});
			if (transaction.data.status == 'successful') {
				return res.redirect('/payment-successful');
			} else if (transaction.data.status == 'pending') {
				// Schedule a job that polls for the status of the payment every 10 minutes
				transactionVerificationQueue.add({
					id: transactionId,
				});
				return res.redirect('/payment-processing');
			} else {
				return res.redirect('/payment-failed');
			}
	}
});

// The route where we validate and verify the payment (Steps 5 - 6)
app.post('/pay/validate', async (req, res) => {
	const response = await flw.Charge.validate({
		otp: req.body.otp,
		flw_ref: req.session.flw_ref,
	});
	if (
		response.data.status === 'successful' ||
		response.data.status === 'pending'
	) {
		// Verify the payment
		const transactionId = response.data.id;
		const transaction = flw.Transaction.verify({
			id: transactionId,
		});
		if (transaction.data.status == 'successful') {
			return res.redirect('/payment-successful');
		} else if (transaction.data.status == 'pending') {
			// Schedule a job that polls for the status of the payment every 10 minutes
			transactionVerificationQueue.add({
				id: transactionId,
			});
			return res.redirect('/payment-processing');
		}
	}

	return res.redirect('/payment-failed');
});

// Our redirect_url. For 3DS payments, Flutterwave will redirect here after authorization,
// and we can verify the payment (Step 6)
app.post('/pay/redirect', async (req, res) => {
	if (req.query.status === 'successful' || req.query.status === 'pending') {
		// Verify the payment
		const txRef = req.query.tx_ref;
		const transactionId = await redis.getAsync(`txref-${txRef}`);
		const transaction = flw.Transaction.verify({
			id: transactionId,
		});
		if (transaction.data.status == 'successful') {
			return res.redirect('/payment-successful');
		} else if (transaction.data.status == 'pending') {
			// Schedule a job that polls for the status of the payment every 10 minutes
			transactionVerificationQueue.add({
				id: transactionId,
			});
			return res.redirect('/payment-processing');
		}
	}

	return res.redirect('/payment-failed');
});

Webhooks

You can also verify the payment in a webhook handler. Here’s an example of the payload we send to your webhook for successful card charges. The event type is charge.completed and the data object contains the transaction information.

{
	"event": "charge.completed",
	"data": {
		"id": 288192886,
		"tx_ref": "UNIQUE_TRANSACTION_REFERENCE",
		"flw_ref": "FLEG8147171639979534513071",
		"device_fingerprint": "N/A",
		"amount": 7500,
		"currency": "NGN",
		"charged_amount": 7500,
		"app_fee": 105,
		"merchant_fee": 0,
		"processor_response": "successful",
		"auth_model": "PIN",
		"ip": "N/A",
		"narration": "CARD Transaction ",
		"status": "successful",
		"payment_type": "card",
		"created_at": "2021-07-15T14:06:55.000Z",
		"account_id": 17321,
		"customer": {
			"id": 370672,
			"name": "Flutterwave Developers",
			"phone_number": "2349012345678",
			"email": "[e-mail]",
			"created_at": "2021-07-15T14:06:55.000Z"
		},
		"card": {
			"first_6digits": "553188",
			"last_4digits": "2950",
			"issuer": "MASTERCARD  CREDIT",
			"country": "NG",
			"type": "MASTERCARD",
			"expiry": "09/32"
		}
	}
}