Beyonic supports two main features that allow you to get paid via mobile money. These are:

  1. Collections - sometimes called subscriber initiated payments

  2. Collection requests - sometimes called merchant pull, USSD push or merchant initiated collections

Each of these works great out of box, but each one also has additional features that allow you get the most out of Beyonic Collections.

This guide will help you get acquainted with the out-of-box and advanced features.


Summary Checklist:

This checklist is advanced. It's ok to skip this checklist and return to it after reading the rest of this user guide. While implementing ALL these suggestions will help you optimize your collection system, you can start with one or two first, and add the rest as the need arises.

For mission critical applications, if you want get the most out of your collections, we recommend that you read and implement all the following features:

  1. Collection requests (merchant initiated), with a backup SMS which sends alternative instructions to the user, in case they don't get the network billing notification.

  2. Subscriber initiated collections with a good reference code, in case a user wants to send in a payment on their own time, for example if they didn't have enough credit when they received the collection request.

  3.  Retries for your collection requests - the defaults may be sufficient, but you may want to check them.

  4. Claiming missing collections manually using the Dashboard or automatically via the API

  5. Subscribe to both "collectionrequest.status.changed" and "collection.received" events to make sure you get all notifications. Using both is better, but will result in some duplicate notificaitions. See number 6 for how to deal with duplicates:

  6. Use the "network transaction id" AND phone number along with metadata to filter out duplicate notifications

  7. Use a mixture of metadata, network transaction id and the claim feature to match collections up on your side.

Once all 7 of these are implemented, you will get the maximum benefit from Beyonic collections.

Read on for details on how Beyonic Collections and Collection Requests work and how to implement each of these recommendations.



When you get a Beyonic account, you automatically gain the ability to receive funds from your customers on any of the 20+ mobile money networks supported by Beyonic.

How do collections work?

  1. You must first make sure your organization is enabled to receive collections in the specified currency. You can see if collections are enabled, and the allowed currencies by going to Dashboard > Company Settings.

  2. Each network has unique set of instructions that you can share with your customers. See the "Per country" section of our collections guide for the country and network specific instructions.

  3. For these instructions to work you usually need to set up a reference code. This is a short easy to remember word that customers can use to send money to you. You set up the reference code by going to your Dashboard > Company Settings > Advanced Settings > Collection Settings. (See  "A note about reference codes" below for rules governing reference codes)

  4. Once you have set up the reference code, share it with your customers, along with the network specific instructions and you're all set!

A note about reference codes

Choosing the right reference code is important to prevent misrouted payments. It should be easy to understand and remember, and hard to misspell. 

There are some rules to remember when setting up reference codes:

  1. Each reference code must be 4 characters or longer

  2. Reference codes are not case sensitive. For example, "PAYHUB" and "payhub" are the same code. This makes it easier for your users who are typing on a phone.

  3. You can enter multiple reference codes separated by commas. Do this if you notice customers are confusing one word for another frequently, for example; if they're often entering PAHYUB instead of PAYHUB, you should add both codes.

  4. No reference code can be a sub-string of another, for example you cannot have PAYHUB and PAYHUBNOW. Just use PAYHUB - it'll match both.

  5. Beyonic only matches the reference code, so you can include any other information after the reference code. This information will be passed on to you. For example, you can ask your customers to include an order number or account number after the reference code. "PAYHUB 123455" and "PAYHUB Order#1" will both be matched by the PAYHUB reference code.

  6. Reference codes should be unique - if you try to enter a code that is being used elsewhere in our system, it will be rejected.

  7. Lastly, you cannot use common or generic words for reference codes - these include PAYMENT, PAID or RECEIPT. While Beyonic blocks some of these common words, we cannot block all common words, so as you choose a reference code, make sure it's specific. That reduces the likelihood of a subscriber typing the word by mistake.

ADVANCED FEATURE: Verifying a collection before accepting it

This advance feature can help reduce misrouted payments, reconciliation headaches and the need to refund customers later on.

This feature lets you verify a collection before accepting it. Use this if you want to check that the user's information is correct. 

To enable this feature, go to Dashboard > Company Settings > Advanced Settings > Collection Settings and enter a Collection Verification URL. You can also decide whether to accept collections by default or not.

After you do this, Beyonic will send you information about the collection including the phone number of the user, the amount and any reference information they include with the payment. You can check this information against your database and decide if you want to accept the payment.

See for more information on this useful feature.

ADVANCED FEATURE: Claiming an unmatched collection

This advanced feature can help you trace payments that weren't matched to your account because a customer entered the wrong reference information

If you're expecting to receive a payment and it doesn't appear in your account, this feature lets you ask Beyonic to search for the payment. You need to get information about the payment from the user, including the phone number they used, the amount they were trying to pay, and the network receipt number. 

(Some customers collect this information as part of their checkout process, or others have their support center ask users for this information when they call in a complaint)

Once you have that information, you can claim the collection in two ways:

  1. Via the dashboard, go to Collections > Claim Missing Collection

  2. Via the API. See for more information

Other advanced collection features

You can also:

  • Set a success message that gets sent to the user when they have completed the payment. This message supports personalization using placeholders like {firstname}, {amount} and {phone}. You can do this via the dashboard or the API when you create a collection request. See Dashboard > Company Settings > Advanced Settings > Collection Settings and the API documentation at

  • Disable SMS completely. Since SMS costs apply, you can disable them completely via collection settings. See the SMS charges guide for more information.

  • Edit a collection. If you want to change the reference on a collection, you can edit the collection via the dashboard. This is useful if you are sending the information to a third party system that requires a very specific reference.

  • Enable collection instant payment notifications. You can configure a URL which will receive notifications whenever a collection is received. See the "events" section of our API documentation:

Lastly, please see the other collection articles on this site, and also review the collection section of our API documentation.

Collection Requests

Collection requests are the other way to receive funds with Beyonic. They work hand in hand with collections, but have some advantages over just using collections:

Advantages of collection requests

  1. Better user experience. Collections often require your users to go through 5 to 10 steps to send money to you, depending on the network. With a collection request, on most networks the user will just have to enter their PIN code to confirm the payment.

  2. Fewer misrouted payments. Collection requests reduce errors cause when your user forgets the instructions or enters as wrong reference code, because you're the one who initiated the transaction.

  3. Advanced features. Collection requests support advanced features like automatic and configurable retries, future dates and subscriptions or recurring billing

How do collection requests work?

A collection request is an instruction telling Beyonic to bill a user. You can create collection requests via the Dashboard (Collection > Create new request) or the API (see

Once you create the collection request, your user will receive a notification about the request and they just have to accept it. On most networks, this notification comes as a popup on the user's phone (using USSD Push technology). On other networks, this message may be an SMS with instructions on how to authorize the payment.

Once they complete the payment, a matching collection will be created in your account and linked to the collection request.

Collection request expire after 24 hours, but you can change this default.

Beyonic backup SMS

USSD Push technology is convenient and works most of the time, but it is not perfect. There are some conditions when the user may not receive the popup notification. For example:

  1. Older sim-cards or phones may not receive the popup.

  2. On some networks, if the user doesn't have enough credit to fund the transaction, they may never receive the notification

  3. If the user is on a call or texting with their phone, the popup may not appear, or it may be dismissed very fast by mistake.

  4. If the user is in an area with low network coverage, they may not receive the notification

Because of these and other reasons that could prevent the notification from coming, Beyonic can also send a backup SMS with instructions in addition to the network notifications. This ensures that the user gets the message. 

Since this SMS is charged, you can control this SMS behavior as follows:

  1. You can turn off this SMS completely across your whole account by going to Dashboard > Company Settings > Advanced Settings > Collection Settings and unchecking the "Enable Collection Request SMS" option.

  2. You can decide whether to send this SMS for a specific collection request by setting "instructions" to "skip", via the API (See

  3. You can control the contents of this SMS by setting "instructions" to anything you like. Those instructions will be sent instead of the Beyonic default instructions.

ADVANCED FEATURE: Collection request retries

To maximize the success rate of your collection requests, Beyonic comes with two levels of retries:

  1. Automatic retries: If Beyonic gets a response from the network that indicates that the collection request failed, Beyonic tries the collection request up to 5 times separated by about 2 minutes. This feature is enabled by default and you don't have to do anything.

  2. Configurable retries: In addition to the automatic retries, Beyonic will retry failed payments every 2 hours by default, up to 5 times total. You can change the retry interval and the max number of times via our API. E.g if you set retry_interval_minutes to 40, Beyonic will try sending the notification every 40 minutes up to 5 times. Please note that you cannot set a value less than 30 minutes, and cannot set the max number of tries to more than 5. See our API documentation for more information:

Use this retry feature to increase your collection request success rate.

Note: For those who are listening to the "collectionrequest.status.changed" event, note that retries will lead to multiple statuses for the same collection request. For example, if the request fails, you will get a FAILED notification, and then it will return to PENDING state to try again, and you will get another PENDING notification, followed by other FAILED, PENDING, or SUCCESSFUL notifications. Your code should check the collection request id to handle duplicate requests.

Other advanced collection request features

You can also:

  • Set a success message for each collection request. This message supports personalization using placeholders like {firstname}, {amount} and {phone}. See:

  • Set a future start date for each request. Use this if you want to bill a customer at a future date

  • Create a recurring collection request (also called a subscription). Use this if you want to bill the customer at regular intervals, e.g. Once every month. This feature is only available via our API for now.

  • Enable collection request instant payment notifications. Like collections, you can configure a URL which will receive notifications whenever a collection request status changes. The event to configure is called "collectionrequest.status.changed". This has some advantages over the "collection.received" event for collections: With "collection.recieved", you only know successful collections, while "collectionrequest.status.changed" will notify you if the collection request expires or fails or is being retried. However, for collections that aren't matched to a collection request, (customer initiated), you need to listen to the "collection.received" event. Therefore, we recommend that you implement both. See the "events" section of our API documentation:


If you've made it to the end of this page, you are ready to power-charge your collections! Go back to the summary checklist at the top of this page which you can use as a guide while you implement your solution.

Did this answer your question?