Telecom top-ups and vouchers through the API: adding everyday services to your app
In short
- Telecom top-ups and vouchers are value-added services that bring users back: small amounts, frequent need, immediate result.
- A top-up takes two calls (catalog, execution) when the partner pays, or a prior preview when the customer's wallet is debited.
- A voucher follows a brands, items, preview, confirmation journey; the code is handed over at confirmation.
- Two prerequisites come up everywhere: the module enabled for your partner account and float for debit operations.
Why these two services
In a financial app, phone top-ups and digital voucher purchases play the same role: they give a reason to use the balance often, for small amounts, with a result visible right away. They complement bill payment in Chari Money's value-added services offer.
Our articles on online phone top-up and digital vouchers present these services from the user's point of view. This guide is for the team integrating them.
Before you start
Three things are needed, in the sandbox as in production:
- A valid API key, specific to each environment.
- The module enabled for your partner account: telecom top-ups and vouchers are both enabled on request by the Chari Money team. For vouchers, the catalog must also be provisioned in the sandbox.
- Float on your principal agent's account, since these operations debit a balance.
The principal agent's account is the one that carries your partner status; our article on principal agent status explains what it covers. In production, enabling each of these use cases requires the prior approval of the Banking Supervision Directorate.
Telecom top-up, call by call
The offer catalog
The B2B catalog returns the top-up products available for a number, an amount and an operator, the latter being designated by a numeric code. Each product carries a unique product code, to reuse for the top-up, and an availability flag.
Execution
The top-up is executed with the chosen product code and your principal agent's code, which designates the debited account. Two types of top-up coexist: the classic top-up, expressed in dirhams, and the product top-up, which corresponds to a pass from the catalog.
The customer variant
If the top-up is paid from a customer's wallet, and not by the partner, you use the customer variant. It starts with a preview: the debited wallet and the topped-up number are separate, and the response returns the fees and the total amount. Once the user has validated the preview, execution reuses the same body.
History
A customer's top-up history is paginated and can be filtered by status, several statuses being combinable in the same request.
| B2B top-up | Customer variant | |
|---|---|---|
| Debited account | Principal agent's account | Customer's wallet |
| Prior preview | No | Yes, with fees and total |
| Typical use | Agent network, top-up offered | Consumer app |
Vouchers, from catalog to code
Brands and items
The brand list is paginated and requires the customer's phone number. For a given brand, its item list shows the price and above all the two identifiers required next: the item's identifier at the supplier and the supplier's identifier. Keep them.
Preview
The preview checks that the purchase is feasible. Its body carries five required fields: the customer's phone, the destination phone, the beneficiary's name and the item's two identifiers. The response returns the fees and the total amount: show them before any confirmation.
Confirmation and code delivery
The confirmation reuses the same body. Its response carries the deliverable: the voucher code, with its name, its description and any cashback amount. Store the code securely and hand it to the beneficiary, for example on the receipt screen and in the history.
The API also exposes a catalog of local vouchers, filterable by brand and keyword, which feeds a second, separate purchase flow: do not mix the two journeys in one integration without planning for it.
Errors and tracing
Errors follow standard HTTP codes. A business error comes back as a 400 with, in the body, a Chari error code and its description. The most frequent cases during integration:
- Service not enabled: the module is not enabled for your account; request activation.
- Empty catalog: voucher brands are not provisioned in the sandbox; it is not a bug.
- Missing parameter: a required body field is missing, for example the agent code, the product code or the top-up type, or one of the five fields of a voucher preview.
- 401: API key not authorized or used in the wrong environment.
Include a unique request identifier with every call: it is returned in the response and speeds up any exchange with support.
Designing the experience well
- Show the fees before confirming. That is what the preview is for: the total displayed must be the one debited.
- Keep a record. One receipt per operation, accessible in the history, with the voucher code when there is one.
- Handle failure cleanly. If execution fails, show no debit and offer to try again: the history filtered by status lets you check what really happened before rerunning an operation, which avoids topping up the same line twice.
- Manage the float. On the partner side, watch the principal agent's balance so B2B top-ups do not stop; card deposit, in its agent variant, lets you rebuild it.
Where to place these services in the product
These services do not sell themselves: they go where the user needs them. In a consumer app, a "Top up" tile on the home screen, with recent numbers, often does more than any campaign. For vouchers, a section per category (gaming, entertainment, gift cards) helps find the right brand without browsing the whole catalog.
In an agent network, the logic is different: the agent sells the top-up or the voucher to a walk-in customer, from the principal agent's float. The B2B top-up is made for that use, and Chari Money's agent network is its natural channel.
In both cases, keep the same discipline: a preview that shows the total, an explicit confirmation, a receipt kept in the history, and a voucher code that can be found again later if the beneficiary has lost it.
What about a merchant?
These integrations are for partners operating wallets for their users. A merchant that simply wants to top up its team's lines from the money of its sales needs none of this: ChariPay, the payment platform operated by Chari Money, allows it through the API from the balance of a merchant's payment account. To try it, open an account in test mode: Start in test mode.
Next step
To enable telecom top-ups and vouchers in your sandbox, see the partner API documentation and ask your Chari Money contact to enable the modules and provide test float.
Frequently Asked Questions
- How do you integrate telecom top-ups into an app?
- With Chari Money's API, in two calls for a top-up paid by the partner: fetch the offer catalog for a number, an amount and an operator, then execute the top-up with the chosen product code. A variant debits the customer's wallet, with a prior fee preview.
- What is the difference between the B2B top-up and the customer variant?
- The B2B top-up debits the principal agent's account, that is the partner. The customer variant debits the customer's wallet: you first call the preview to check feasibility, amount and fees, then execute with the same body.
- How does selling a voucher work?
- You browse the brands, fetch a brand's items with their two supplier identifiers, preview the purchase to get the fees and the total, then confirm. It is the confirmation response that carries the voucher code to hand to the beneficiary.
- Why is the voucher catalog empty in the sandbox?
- An empty catalog is not an integration bug: voucher brands must be provisioned in the sandbox by Chari Money for your account. Ask your contact to enable the module, as well as test float for the principal agent, because a purchase is a debit operation.
- How are errors reported?
- Errors follow standard HTTP codes; a business error comes back as a 400 with a Chari error code and its description in the body. Send a unique request identifier with every call: it comes back in the response and eases tracing with support.
- Can a merchant top up lines from its balance?
- Yes, and with no infrastructure project: ChariPay, the payment platform operated by Chari Money, lets a merchant top up telecom lines through the API from the balance of its payment account, with the result received by signed webhook.