Troubleshooting Your Bloc API Integration
When you try to integrate the Bloc API, it is very common to run into a few problems that may cause your software to stop working properly.
In this article, you'll learn the different reasons why your integration with the Bloc API may not be working and how you can fix it. This article is best read by your developers or engineering team.
Before you start
- Make sure you have an Organization workspace with us. If you do not have an account, you cannot integrate with our API.
- We advise customers to always test their integration in the sandbox environment (Test Mode), before deciding to go live.
Common problems integrating the Bloc API
- Authentication errors
- "Can't validate customer details" when testing Bills Payment
- Can't get electricity token
- "Unable to make payment" when trying to pass a transaction
- Can't upgrade customer KYC
- Can't fund your test account or Main Balance
- Not receiving webhooks from Bloc.
Authentication errors
Here's what to do when you have issues authenticating your API connection with us.
Make sure you are using the right keys for the right environment.
Test API credentials will not work in Live Mode, and live API credentials will not work in Test Mode. Make sure that you are using the right API credentials.
To do this, confirm what environment you are in by looking at the top right corner of your screen before copying your API credentials. To learn more about our environments, read this article: What is the difference between Live Mode and Test Mode?
Make sure the keys are written correctly
A good rule of thumb is to copy and paste the keys instead of typing them manually. However, in the rare case that you decide to type it in manually, make sure you are typing them correctly. API keys are case-sensitive, make sure all of the special characters and letters are written correctly.
You are using the wrong kind of keys
Your Secret Key is used to authenticate your connection to our infrastructure, while your Public Key is used for client-side communication with our infrastructure.
Make sure you are not using your Public Key in place of your Secret Key. To learn more about API credentials, read this article: Getting Started with the Bloc API.
"Can't validate customer details" when testing Bills Payment
Validating customer details happen when you are trying to make sure that the meter number or card number of the customer actually exists. Here's what you do if you get this error:
Confirm you are using a real meter/card number
When testing your Bills Payment integration, the sandbox environment remains connected to the service provider. A fake meter/card number will not work, because it doesn't exist in their database.
Always provide a real meter/card number. Because we are in Test Mode, a successful transaction will not credit the meter/card with a token (because real money is not transacted in Test Mode).
Confirm that you are using the right operator
Every meter/card number is unique to its operator.
For example, if you want to verify an Ibadan Disco (IBEDC) meter number, but selected Abuja Disco (AEDC) as your provider, our server will return an error.
Operator refers to the service provider that a bills payment product is being bought from.
Confirm that the operator_id and meter number are written correctly
Make sure that you are using the right values for the operator and meter number.
Can't get electricity token
If you've successfully made a payment, but cannot get your electricity token, confirm that you passed the payment reference in your request.
Your payment reference is very important to completing a Bills Payment purchase. Refer to the Bloc API Documentation for more information about this.
"Unable to make payment" when trying to pass a transaction
If you get this error when trying to pass a transaction, here are some of the ways you can fix them.
Confirm that you have enough funds in your Main Balance to process the transaction.
If your Main Balance isn't adequately funded, you will not be able to complete a transaction. To learn how to top-up your Main Balance, please read this article: How to fund your account.
Make sure you are passing the amount as an integer.
amount should always be passed as an integer. If you pass it as a string, your API request will return a failure.
Important to Note:
When passing amount, always pass it in the lowest currency unit. We only accept integers for the amount, nothing else.
Here's a tip. Multiplying the naira value by 100 gives the lowest currency unit. For example, if you want to make a payment of NGN 100, your amount should be 10000. Likewise, all API responses for amount are returned in the lowest currency unit.
Can't upgrade customer's KYC
Confirm that you have enough funds in your Main Balance to process the transaction.
If your Main Balance isn't adequately funded, you will not be able to upgrade your customer to KYC Tier 1. It costs NGN 50.
To learn how to top-up your Main Balance, please read this article: How to fund your account.
Confirm that the image is passed as a Base64 string.
When submitting an image to our API, do not send URLs. Always convert them to a Base64 string before sending them to us.
Confirm the list of IDs that we support.
Call the endpoints for Means of ID first to see the list of IDs that we support and pass the values appropriately.
Can't fund your test account or Main Balance
Call the Simulation endpoint to fund your Main Balance
If you have the account_id of the account you want to fund, you can go to the Simulation endpoint, and pass a test transaction. To get your account_id, call the get id by account number endpoint first.
Fund your account on the Bloc Dashboard
For a test virtual account,
- Go to the Home page, and find the account that you want to fund.
- Follow the steps provided, and click on Test transaction.
- And you are done!
To learn how to fund your Main Balance, read this article here: How to fund your main balance.
Not receiving webhooks from Bloc
Webhooks are how the Bloc API send you notifications about what's going on with your API requests. You use these notifications to determine what next to do for your customer.
We always send webhooks. Most of the problems lie in whether or not you can receive them or not. There are a few reasons why you may not be receiving webhook notifications from our server, and here's how to troubleshoot them:
You haven't configured your webhooks
To set up your webhook, you need a URL to receive notifications with, and a Secret Key to authenticate that you are the right recipient of those notifications. Without these, you cannot receive webhooks from us.
To set up your webhooks, follow the instructions in the API Documentation.
You haven't whitelisted our IP addresses
We use whitelisting to ensure that you can block out requests coming from other IPs, protecting youu from bad actors.
To do this, follow the instructions in the API Documentation.
The webhooks didn't deliver, despite everything being ready
You can access your Webhook logs on the Bloc Dashboard to retry them yourself. To find it, go to Developer under the Settings page and toggle on Access Developer Tools. Navigate to the webhooks section and click on Webhook logs.
It will link you to a page where you can see the status all of your webhooks, and you can retry them yourself.
Can't find your problem here?
Please send a message to the Support team via the chat widget on the bottom-right of your screen, or send an email to [email protected].