Announcing our new and improved API

At Flutterwave, we hold customers' experience and satisfaction above all else. This is why we’ve spent the better part of this year, strategizing on how to get your feedback and improve our services. The plan was to understand the pain points from the user’s perspective to ensure that whatever fix we deploy will improve your experience.

We believe we were able to get the best responses from our campaigns and they have informed the steps we’ve taken to improve our API, hence the new and improved v3 APIs.

What’s new?

All new and improved ways of doing things with our APIs. Better authorization system, Quickdocs on all endpoints, better URLs and much more . . .

1. Improved authorization system

The v3 APIs come with a single way to authorize requests. Simply add an authorization header using your secret key as a bearer token. What this means is, you can authorize requests to any endpoint by simply adding this to your header:

{
    Authorization: Bearer "YOUR_SECRET_KEY"
}

2. Enforced request and response structure consistency

All requests and responses to and from the v3 APIs are normalized to ensure consistent structures across all endpoints. This is also the case for all the parameters that apply to any endpoint. Every endpoint will return the same response structure irrespective of the supplied parameters or values.

3. Shorter, easier-to-read/understand URLs

We’ve implemented REST naming conventions across all our v3 endpoints to simplify our URLs. This will make our endpoints more intuitive and easier to understand. Here’s a bit about the changes in the URL:

//prev transaction verification
{BASEURL}/flwv3-pug/getpaidx/api/v2/verify

//v3 transaction verification
{BASEURL}/transactions/:id/verify

4. Pagination on large data sets

Want to retrieve a list of 2,000 transactions or 5,000 virtual cards on your account? no problem, our new API has no limit on the number of objects you can retrieve and it is well paginated to allow you fetch results in batches.

5. Quickdocs on all endpoints

We've made it easier for you to get all the information you need about any endpoint right from your dev environment. This will help you sustain focus on your tasks and limit your trips to our documentation pages. To access the Quickdocs for any endpoint, simply prefix the endpoint with a /meta. Here's a sample Quickdocs on the /transfers endpoint:

//Create a transfer
POST {{BASE_API_URL}}/transfers

//Access the /transfers quickdocs
POST {{BASE_API_URL}}/meta/transfers

Here's the Quickdocs response for this call:

{
        "description": "This meta shows you how to initiate a transfer",
        "endpoint": "POST /v3/transfers",
        "request_spec": {
            "type": "post_body",
            "spec": {
                "account_bank": "This is the beneficiary bank code",
                "account_number": "This is the beneficiary account number",
                "beneficiary": "This allows you transfer to an existing beneficiary, you can pass this in place of account_bank & account_number.",
                "amount": "This is the amount to transfer to the beneficiary",
                "narration": "This is the narration for the transfer e.g. payments for x services",
                "currency": "This can be NGN, GHS, KES, UGX, TZS, USD",
                "reference": "This is a merchant's unique reference for the transfer, it can be used in querying the status of the transfer",
                "beneficiary_name": "This is the name of the beneficiary.",
                "callback_url": "This is a url passed by you the developer, Rave would pass the final transfer response to this callback url. You can use this in place of Webhooks",
                "debit_currency": "You can pass this when you want to debit a currency balance and send money in another currency. ",
                "destination_branch_code": "This is only required for disbursements into Ghana",
                "meta": "Additional infomation for international transfers for USD and GBP"
            }
        },
        "sample_request": {
            "account_bank": "044",
            "account_number": "0690000040",
            "amount": 5500,
            "narration": "Akhlm Pstmn Trnsfr xx007",
            "currency": "NGN",
            "reference": "akhlm-pstmnpyt-rfxx007_PMCKDU_1",
            "callback_url": "https://webhook.site/b3e505b0-fe02-430e-a538-22bbbce8ce0d",
            "debit_currency": "NGN"
        },
        "sample_response": {
            "status": "success",
            "message": "Transfer Queued Successfully",
            "data": {
                "id": 26251,
                "account_number": "0690000040",
                "bank_code": "044",
                "full_name": "Alexis Sanchez",
                "created_at": "2020-01-20T16:09:34.000Z",
                "currency": "NGN",
                "debit_currency": "NGN",
                "amount": 5500,
                "fee": 45,
                "status": "NEW",
                "reference": "akhlm-pstmnpyt-rfxx007_PMCKDU_1",
                "meta": null,
                "narration": "Akhlm Pstmn Trnsfr xx007",
                "complete_message": "",
                "requires_approval": 0,
                "is_approved": 1,
                "bank_name": "ACCESS BANK NIGERIA"
            }
        }
    }

6. New SDKs

We want to get you quickly started on v3, so we've built brand new SDKs on the new APIs. This will help you integrate faster and also make it possible for you to interact with the code and see how things have changed for yourself. Currently we have v3 SDKs for Node, Python, PHP with more coming soon.

7. More dedicated support

We have revamped our Developer Forum on the docs where our technical heroes will be available at all times to answer any of your development questions and provide assistance where you need one. We have also integrated our live chat support system directly on the documentation page to allow you to immediately speak with any of our support agents when you need to. We have also created a public issue tracking repository where you can log issues or request features/give feedback when you need to.

8. PCI-DSS Compliance

We have enforced the CBN regulation on PCI-DSS compliance. This means that only businesses that provide this PCI-DSS compliance certificate will be enabled to call our direct card charge endpoint on the API level. What does this mean for businesses without the compliance certificate? It means that you can no longer charge cards directly from our v3 API. However, you can continue charging cards via the Inline method, standard, or through our mobile SDKs. This does not affect the businesses currently running on the v2 API.

9. What will happen to businesses on v2

Nothing will change. Support for the existing version will continue until the end of the year. This will give you enough time to familiarize yourself with the new API and upgrade your system. We will be ceasing technical support officially on v2 from January 2021, however, the APIs will still be up and running for your business.

Finally, we want to thank you so much for sticking with us through thick and thin. We are committed, going forward, to delivering quality and hassle-free experiences. We hope this update will amount to increased sales and revenue for your businesses and easier integration process for all Engineers building on Flutterwave.