The API provides a few features to ease API testing. These features are described below.
All the API examples in this documentation include a test API token that actually works. They can be run directly, so feel free to try them out as you read the documentation.
The API provides a test currency, with the following parameters:
Phone Format: +800XXXXXXXX
Currency Code: BXC
The BXC currency is used throughout the examples and you can also use it in your own testing. Payments made in the BXC currency will not affect your live currency accounts. Additionally, depending on the number you are paying, you can test various success and failure scenarios. See “Test Numbers” below
Note: Currently, this test currency works only for outgoing payments and for local wallets. If you are testing cross border transactions, see this section.
Getting access to the test currency
All new organizations should have access to the BXC currency. If for some reason, you don't see a BXC wallet on your account please contact support at [email protected].
Topping up the test currency
The balance on your BXC wallet will be topped-up to 100,000 each night. You are able to send up to 100 test transactions per day.
The API provides test numbers that should be used in conjunction with the test currency. The following numbers are treated in special ways when used with the BXC currency:
- +80000000001 - When you add a contact with this number, the contact will always fail the mobile money registration checks, and therefore payments sent to this number will always fail.
- +800XXXXXXXX - All other numbers in the format +800XXXXXXXX will pass the name checks only if the contact name is “John Doe”. So, set the name to “John Doe” to test the effect of a successful name check, or set it to something else to test the effect of a failed name check.
- Subsequently, all BXC payments to numbers with format +800XXXXXXXX and name “John Doe”, (except +80000000000) will succeed if the amount is greater than or equal to 10 and less than or equal to 1,000 BXC.
To trigger a test notification, simply perform the corresponding action in your account. You can do this via the API or the web portal.
For example, to trigger a ‘contact.created’ event, simply create a contact. Or, to trigger a ‘payment.status.changed’ event, use the Payments API to create a payment with the test currency and test numbers described above.
The API only supports notification urls (also called webhooks or callback urls) that start with “https://”, even when testing. See the “Webhooks” section for more infromation. So, you should set up URL to a dedicated page on your server with a server-side https certificate.
The API will usually validate the https certificate, and if validation fails, the notification will not be sent to your URL. To skip validation while testing, add ?skip-cert-verify to your URL, for example:
Skip-cert-verify only prevents certificate verification. It doesn’t eliminate the “https://” requirement
While you can use skip-cert-verify on your production URLs, we advise you to use valid server-side certificates to maximize the security of your production systems.
To set up a temporary callback URL, and verify the format of the notifications, do the following
If you are not able to set up a dedicated “https://” url while testing, we recommend using a service like RequestBin.
RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way. Use RequestBin to inspect and debug the webhook notifications.
Once you get a RequestBin URL, it uses HTTP by default. Since the API only supports HTTPS, remember to use “https://” and “skip-cert-verify”
For example, if your RequestBin URL is
Then use this for your callback URLs:
The API logs webhook notification delivery attempts for at least 30 days. Both the request and response and response are logged.
These can be viewed by logging into the web portal, and going to “Home” > Settings (Cogwheel) > “Organization Settings” > “Advanced Settings” > “Notification endpoints”
By clicking on “Recent Events”, you will be able to see events and notification attempts, including the responses that the API is getting from your notification server.
Click Run in postman
A postman collection will be created with sample API requests. Create an environment on postman by navigating to New > Environment then create the variables below in the environment
- api_url: https://api.mfsafrica.com/api
- api_key: Your api token or the test api token: ab594c14986612f6167a975e1c369e71edab6900
Proceed to test the API requests in your postman collection.
If you are integrating to the API for cross-border collections or payments, then you will have to test using live transactions with real currency. The BXC currency is not yet available for cross-border integrations.
Updated about 1 year ago