Testing

Suggest Edits

The API provides a few features to ease API testing. These features are described below.

Test API Token

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.

Test Currency

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.

Test Numbers

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:

Sending Payments

  • +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.

Testing Webhooks

Triggering test events

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.

Https with invalid certificates

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:

📘

Note

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.

Temporary callback URL (RequestBin)

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:

Viewing logged webhook delivery attempts

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.

Testing in Postman

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

Proceed to test the API requests in your postman collection.

Cross Border Testing

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 6 months ago