Category: Tutorials & Guides || Posted May 26, 2026

Core Integration & Developer Setup (Flutterwave Standard API v3)

For technical builders, e-commerce operators, and fintech creators, relying on manual payment links isn't scalable. To build a fully automated checkout experience, you need to handle transactions programmatically on your backend.

The Flutterwave Standard API (v3) is the cleanest, most secure way to achieve this. It works via a secure server-side redirect: your backend tells Flutterwave how much to charge, Flutterwave hosts the secure checkout page, and then sends the customer back to your site when they are finished.

Here is the step-by-step developer procedure to integrate Flutterwave securely into your application.

1. Locate and Secure Your API Keys

Before writing code, grab your cryptographic credentials from your dashboard.

1. Log into your Flutterwave dashboard and toggle the switch to Test Mode (always build and test in sandbox first).
2. Navigate to Settings -> API Keys (under the Developers tab).
3. Copy your three essential keys:
4. Public Key (FLWPUBK_TEST-...): Safe to expose in your frontend code or mobile apps.
5. Secret Key (FLWSECK_TEST-...): Must never be shared or committed to GitHub. Keep this hidden on your backend server.
6. Encryption Key: Used to secure raw payloads if you handle direct card capture.

🔒 Security Best Practice: Save your Secret Key inside your server's root .env environment file as FLW_SECRET_KEY. Never hardcode it directly into your script files.

2. Initiate the Payment Request (Server-Side)

When a customer clicks "Checkout" on your application, your backend server must make an authenticated POST request to Flutterwave's payment initialization endpoint.

1. Endpoint: [https://api.flutterwave.com/v3/payments](https://api.flutterwave.com/v3/payments)
2. Headers Required: Authorization: Bearer YOUR_SECRET_KEY and Content-Type: application/json

The JSON Payload Blueprint

Construct your request body following this JSON schema structure. Make sure your transaction reference (tx_ref) is completely unique for every single checkout attempt:

JSON

3. Redirect the User to the Hosted Link

When your server submits the payload above, Flutterwave validates the request and returns a JSON response containing an explicit data.link string.

Handling the API Response:

JSON

1. Extract the data.link value from the response payload.
2. Direct your application's router to redirect the user's browser window immediately to that URL.
3. The customer will arrive at a securely hosted Flutterwave modal where they can select cards, bank transfers, USSD, or mobile money to finalize the payment.

4. Verify the Transaction State (The Callback)

Once the user completes or cancels the payment, Flutterwave redirects their browser back to the redirect_url you provided in Step 2.

Flutterwave appends transaction parameters directly onto your callback URL query string:

[https://yourwebsite.com/payment-callback?status=successful&tx_ref=ORD-99203-2026&transaction_id=4029311](https://yourwebsite.com/payment-callback?status=successful&tx_ref=ORD-99203-2026&transaction_id=4029311)

⚠️ The Integrity Rule: Never trust url query parameters blindly. A malicious user can intercept and modify the URL query string to say status=successful without actually paying. You must verify the payment status directly from your server.

The Verification Routine

To verify the transaction, perform a server-to-server GET call using the transaction_id sent to your callback:

1. Endpoint: [https://api.flutterwave.com/v3/transactions/](https://api.flutterwave.com/v3/transactions/){transaction_id}/verify
2. Headers: Authorization: Bearer YOUR_SECRET_KEY

Parse the response on your backend and check for these three conditions before fulfilling the customer's order:

1.Check the Main Status Field:Step 1.Ensure the top-level API response status reads exactly "success".

2.Cross-Check Expected Amount and Currency:Step 2.Verify that data.amount and data.currency match the original item prices stored in your internal database. This stops bad actors from changing a 15,000 NGN item to 15 NGN in their browser console.

3.Update Database and Release Value:Step 3.If the checks pass, update your database record for that specific tx_ref to "Paid" and safely deliver your digital product or confirm the shipping process.