A quick guide to developer onboarding in v4

Getting started with a new platform should be smooth, quick, and friendly for developers. That’s what Flutterwave v4 is built to offer. In this guide, we’ll walk you through the updated onboarding flow using the v4 sandbox. Whether you're testing integrations or checking out key features, the sandbox gives you a safe space to build and try things out.

You’ll also see what the process looks like when you’re ready to move from testing to going live.

Let’s dive into the new experience, call out what’s changed, and help you get up and running on v4.

Creating an Account

Before v4, creating an account on Flutterwave meant filling in details like your business type, registration number, business name, and more. While this information is essential when you're ready to go live, it's usually easy to provide for businesses looking to integrate a payment gateway. However, it can be a roadblock for solo developers just trying to explore the product. Even developers working within organizations may find it a bit much when they’re only building a proof of concept.

To make things easier, we’ve separated the developer environment (sandbox) from the go-live setup. This change lets developers test features quickly without needing all the business details upfront.

To get started, head to the sandbox and sign up using your basic information.

Once you verify your email, a sandbox account will be created for you. It comes with your API credentials and webhook configurations, so you can jump right into building.

API Key Management

v4 uses OAuth 2.0, a more secure authorization mechanism that connects your application to our servers without exposing static API keys. Before accessing any of the v4 APIs, generate a token using the Client ID and Client Secret on your dashboard.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'grant_type=client_credentials'

You’ll get a response similar to this:

{
    "access_token": "eyJhbGciO...",
    "expires_in": 600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

In v3, you use API keys to access the APIs, which can be easily exploited if leaked. OAuth 2.0 uses access tokens with expiration times, making it much harder for unauthorized users to maintain long-term access.

Check out the authentication process to learn more about OAuth 2.0 best practices.

To get a glimpse of how the v4 API and sandbox can help you build a robust product, let’s explore the direct payout use case.

Sample v4 API Use Case: Transfer Orchestrator (Direct Transfer)

Consider this scenario: you’re building an internal finance tool for a growing logistics startup. At first, the finance team only needs to send payments occasionally. One salary here, a vendor payout there, maybe a refund to a partner.

Sending these payments in bulk would be overkill. What they really need is a simple, reliable way to send one payout at a time, without worrying about retries, duplicate payments, or manual bank transfers. This is where the Flutterwave’s Transfer Orchestrator comes in.

With Flutterwave’s Transfer Orchestrator, you can build an application that can intiate a single, direct payout to a bank account or wallet. Here’s how to use the Transfer Orchestrator for payment:

Create a Transfer Request

To initiate a transfer, use the orchestrator transfer endpoint to specify the recipients’ details and amounts to be transferred.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \
--data '{
    "action": "instant",
    "payment_instruction": {
    "source_currency": "NGN",
    "amount": {
        "applies_to": "destination_currency",
        "value": 50000
    },
    "recipient": {
        "bank": {
        "account_number": "0122333334",
        "code": "044"
        }
    },
    "destination_currency": "NGN"
    },
    "type": "bank",
    "reference": "574874568ufdgjhvbjhcdbchb"
    "narration": "internet installation payment"
}'

The key parameters to pay attention to when making a transfer are action and payment_instruction.

• action controls when Flutterwave processes your transfer request. In the example above, it’s set to instant, which means the payment should be processed immediately. You can also choose to defer the transfer or schedule it for later.
• payment_instruction tells Flutterwave how to handle your transfer. In the request above, it’s instructing Flutterwave to pay your recipient in NGN (destination_currency) from your NGN Flutterwave account (source_currency). You can also send international payments by specifying a different currency. Flutterwave will take care of the conversion and other operational details.

As a best practice, use Flutterwave’s Retrieve Bank and Bank Account Lookup endpoints to fetch the bank code and confirm account details before starting any payments.

You’ll get a response similar to this:

{
    "status": "success",
    "message": "transfer created successfully",
    "data": {
        "id": "btr_kz5sSNP8IrnRWQ",
        "type": "bank",
        "action": "instant",
        "status": "NEW",
        "created_datetime": "2026-01-24T11:09:44.193969884Z"
        "narration": "internet installation payment",
        "source_currency": "NGN",
        "destination_currency": "NGN",
        "amount": {
            "value": 50000,
            "applies_to": "destination_currency"
        },
    }
}

Monitor the Transfer Status

The last step is to check the transfer status to verify that the transaction has been completed successfully. You can use any of the following methods:

1. Webhook (Recommended): Flutterwave sends a webhook with the transaction status if you have webhooks enabled on your dashboard.

{
    "webhook_id":"wbk_yXvsB4LzWSwhUCpAPCBR",
    "timestamp":1739456704200,
    "type":"charge.completed",
    "data":{
        "id":"btr_kz5sSNP8IrnRWQ",
        .....
    }
}

1. Charge Endpoint: You can manually check the transfer status by sending a request to the retrieve a transfer endpoint at a specific interval.

curl --request GET \
--url 'https://developersandbox-api.flutterwave.com/transfers/{id}' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You’ll get a response similar to this:

    {
    "status": "success",
    "message": "Charge updated",
    "data": {
        "id": "chg_zam88NgLb7",
        .....
    }
}

Moving to Live Mode

Once you're done testing your application and simulating transactions that match your use cases, you can follow the steps below to start accepting real payments:

1 Verify your Business

In v4, live mode is completely separate from the sandbox. To start accepting live transactions, you'll need to create an account and complete your Know Your Customer (KYC) verification process to access the live environment. This involves submitting required business documents such as a certificate of incorporation, proof of address, and valid identification. These documents are needed to meet regulatory and compliance requirements.

Depending on your region, you may also need to provide additional details like Nigeria’s Bank Verification Number (BVN) or local equivalents to show your business is legitimate.

2 Update your Credentials to Live Mode

Once your business is approved, you’ll receive production API credentials. Update your codebase to use the live Client ID and Client Secret. You need these credentials to generate an OAuth 2.0 token for accessing the API in production.

3 Activate Settlements and Webhook

Flutterwave needs an account to process and settle funds into when customers pay for your goods or services. You can choose to use your Flutterwave balance, which is a secure, built-in account linked to your profile, or you can use a business or personal bank account. If you choose to add a bank account, you’ll need to verify it to confirm ownership. Once verified, live transaction proceeds will be sent to the account automatically based on the settlement schedule.

We also recommend enabling and configuring webhooks from your Flutterwave dashboard. Webhooks help your application stay updated in real time by sending notifications whenever important events occur, such as a successful payment or failed transaction.

Other v4 API Improvements to Note

Beyond the dedicated sandbox and OAuth 2.0, we also shipped other meaningful improvements in v4. Here are a few key upgrades:

Improved Workflow

Our v4 APIs follow true RESTful principles. Integration is predictable and scalable and follows industry best practices. For example, when initiating a card payment, you no longer need to encrypt the entire payload. Only the card information needs encryption. You also do not need to call the charge card endpoint multiple times to determine the appropriate authorization method.

Better Developer Experience

A major issue with the v3 API was its generic error messages, which did not clearly indicate what went wrong or how to resolve it. In v4, error responses are well-structured and provide clear insights:

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Invalid card number",
        "validation_errors": []
    }
}

v4 also supports more test cases via scenario keys. This mechanism allows you to simulate different payment scenarios with ease.

Scalability
API requests in v4 follow a consistent flow across all payment methods, which reduces technical overhead. You can create reusable helper functions across your codebase, making integrations more efficient and scalable.

Wrapping Up

You've walked through the essentials of setting up your Flutterwave v4 integration, from sandbox testing to going live. With your business verified, API keys configured, and webhooks secured, you’re all set to start accepting real payments with confidence.

Remember, the transition from sandbox to live mode is designed to be seamless. The API endpoints, request structures, and integration flows remain consistent, so there’s no need to rewrite your codebase when switching environments.

Before going live, double-check that:

• Your business verification (KYC) is complete and approved.
• Live API keys are correctly implemented in your environment.
• Webhooks are secured with your secret hash, and signature validation is in place.
• Settlement accounts are set up and verified.

If you encounter any issues, contact the support team for assistance.