At Belvo, we know that it can be challenging to add a new service or feature to any product. But don’t worry, after reading this post (or checking the video below) you’ll have a full picture of the essentials and tools that developers will need in order to integrate with Belvo, without breaking a sweat.
Essential API knowledge 🤓
For those of you that haven’t worked with an API before, let’s cover two things: REST APIs and JSON format.
REST APIs
REST is an acronym for REpresentational State Transfer, an architectural style for distributed hypermedia systems.
The fundamental abstraction of information in REST is a resource. Any information you can name can be a resource. A document, a collection of other resources, a product, or a person – yep, they’re all resources in REST’s eyes.
Then, there are resource methods. Basically, these are “requests” that describe how you can interact with the data in a resource:
- GET: lets you retrieve information.
- POST: create a new resource.
- PATCH: make a partial update to a resource.
- PUT: update an existing resource.
- DELETE: as the name says, deletes a resource.
That’s pretty much all you need to know about REST.
JSON
Now let’s talk about JSON. When you make requests, you need to send information in a standard format that everyone on the internet can understand – and that’s what JSON is. It’s a lightweight data interchange format that’s very easy to use (just have a look at the image below).
If you’d like to read more about JSON, check out json.org
Now the way that this all works together is:
- Your user makes some interaction that requires data from Belvo.
- You make a resource method request to our API.
- Belvo asks the institution for the information you want.
- Belvo sends to you, in JSON format, all the information you requested.
And that’s pretty much it 🙂
Understanding our API 📚
Through our API, you can access information from banks (such as transactions, balance, incomes, and account owner identification) or fiscal information (invoices, compliance, status, and tax returns). You can see our institutions’ coverage per country here.
You can also combine data aggregation with our enrichment products to get easy-to-use insights about your users. We currently offer three enrichment products through our API: Income verification, Risk insights, and Recurring expenses. Read more about how to use them here.
Read up on the specific data you can access in our docs.
Documentation
And of course, we all know how much developers love documentation, so we put some love and care into all of it.
- Get a quick overview of our API and specs.
- Learn about links, institutions, and multi-factor authentication (MFA).
Check-list
Once you can answer “Yes” to the following questions, then you know that you’ve got a good understanding of our API:
- Do you understand what type of data you need for your project?
- Do you know the difference between single and recurrent links?
- Do you understand how to use PATCH requests for accounts that need MFA?
Playing in the sandbox 🏏
Once you’ve read up on Belvo and our documentation, it’s time to start playing around with the data you can retrieve in our Sandbox environment.
We built our sandbox specifically to let you interact with dummy banking and fiscal. This way, you can quickly prototype and iterate your integration so that later on, switching to real-world data is just a matter of changing a couple of parameters.
To get access to our Sandbox environment, as well as get set up with our Postman collection, check out our Getting started guide. It just takes five minutes to get up and running 🙂
Once you’ve tested out our API and gained a good understanding of how it works, it’s time to start integrating our services into your platform.
Getting serious about integrating ⚒️
At Belvo, we want you to integrate as fast as possible. And to make it easy, we’ve created some tools that will ensure it goes as smoothly as possible.
Connect Widget
You can use our Connect Widget to securely connect your users with their institutions, and it’s available for both web and mobile applications.
This optimized login experience for users can be embedded directly into your product. And, as we handle all the login possible scenarios users can face when linking their accounts, it saves you countless hours and headaches, which means you can dedicate your precious resources to actually making the right API calls to get the data you need.
You can also brand and customize the widget to fit your needs.
SDKs
Belvo offers official API libraries for different programming languages, including:
Not using any of those languages? Not a problem: just use the HTTP Request Library for the language your choice – then all you need to do is to consult our API reference and make the relevant calls.
First steps in the real world 🌎
Once you’ve implemented our widget and created your integrations in the Sandbox environment, it’s time to test it out with real-world data. Luckily, Belvo has a special environment, dedicated to just this task: the Development environment.
Here, you can have up to 25 connections with live institutions and start testing out the data you get for real users. And to get access to this environment, all you need to do is request your API keys for this environment, change the sandbox keys you currently have in your code to these new ones, change the base URL to which you make your requests and… no, that’s actually it!
| Tip! We recommend you have at least one user type per institution you want to access. For example, if you want to access banks, make sure that you have at least one user for both Itaú and Nubank. This way you’ll know exactly what kind of data to expect. |
Certification process ✔️
Once you’ve tested out your integration in the Development environment and everything is working just as you want, you’re probably going to want to take your integration into the world. In other words – accessing our Production environment.
Now, before you can do that, we at Belvo will run you through a certification process. Basically, we just check that you’re doing things securely, that your integration handles data properly, and that your user’s data isn’t at risk (after all, banking data is something you definitely need to take very seriously).
So, before you decide to get certified, just make sure that:
- You’re storing your API keys securely.
- You ask your users to register with your platform first and then you use the widget to connect their accounts. You’ll get errors about duplicate links if you don’t.
- You can handle request errors (and store the request_id -> it helps with debugging later on)
- You’ve set up webhooks
- You can delete links and handle the response Belvo sends confirming the deletion
If you tick all those boxes, just schedule a certification meeting, impress our integration engineers with your perfect integration, and then…
It’s alive, baby! ✨
You are ready to receive users and start using Belvo.
And remember: our technical support team will always be available for you, and will guide your developers through the whole process to solve any doubts you may have.
If you are unsure about any of these topics or have any questions during the integration process, contact us at hello@belvo.com
