Connecting a Vending API to Your VTU Website (VTpass & ArewaBundle)

Your site does not deliver airtime or data by itself. It asks a vending provider to do that, and the provider is paid from the balance you keep with them. Connecting one is quick, but a few details decide whether purchases succeed. This guide walks through the connection, the providers you can use, how routing works, how to build a custom connection, and what happens when a provider is slow or fails.

Where to connect a provider

Open VTU Admin, then Vending, then Vending API. Choose a provider, paste your credentials into the boxes shown and click Save & Activate. Once credentials are saved, the boxes show a masked value, and you can leave a box blank when editing to keep what is already saved.

At the time of writing, these providers are ready to connect, each asking for different credentials:

• VTpass: an API key and a secret key.
• ArewaBundle: an API token.
• ClubKonnect: a UserID and an API key.
• ReliefSub: the email and password of your account.
• Autopilot: an API key.
• SMEPlug: an API key, used as a bearer token.
• Simserver: an API key.

The list on your own site depends on what has been set up on the platform, and it can change, so treat the one on your screen as the truth. Open an account with the provider first, fund it, and generate your credentials in the provider's own dashboard.

Other buttons on the same screen:

• Browse the provider's plans: shows the provider's catalogue so you can import plans instead of typing them in.
• Pin as default: makes this provider the one your site uses unless you say otherwise. A Remove lock option appears afterwards.
• Deactivate: switches the provider off without deleting your details.

If the platform has set a default provider for your site, you may only be asked for your credentials, and the "API Integrations" tab can be hidden. That is normal.

How the platform picks a route

A purchase is sent to the first matching route, in this order:

1. A provider override on the specific plan, if you set one.
2. The vending route set on the network, such as MTN.
3. Your default provider for the whole site.

Only one route is used per purchase. There is no automatic fallback to a second provider. If that provider says no, the purchase fails and the customer is refunded automatically. So if reliability matters to you, check your provider's balance and status regularly, and use plan overrides to send a problem service to a different provider. A plan override can also carry its own network code, for providers that name networks differently from your site.

Reseller sites that share an engine

Many VTU reseller sites run the same underlying software, so they share one API contract and only the web address and token differ. Instead of setting up each endpoint by hand, you choose an engine, enter a label, the base address of the site and your API token. Three engine families are supported:

• ArewaBundle-style sites (token authentication, with endpoints for data, airtime, cable and bills);
• alrahuzdata-style sites (token authentication, with a slightly different set of endpoints);
• Xpiria VTU, our own v1 API, which uses a bearer token and a single purchase endpoint.

Building a custom integration

If your provider is not listed and does not match an engine, open API Integrations and build a connection yourself. You are describing one HTTP request, and how to read the answer:

• Name, Method and URL: for example "My provider data purchase", POST, and the provider's purchase address.
• Map to Service and Map to Category: which of your services and categories this connection serves.
• Headers: usually your authentication, for example the value {{api_key}}.
• Body Template and Query Parameters: the fields the provider expects, filled with variables that the platform replaces for each purchase.
• Response Mapping: where in the provider's reply to find the outcome, using dot paths such as data.status. The three keys are status_field (where the result is), success_value (what value means success) and ref_field (where the provider's own reference is).
• Active and Test Mode switches, and a Test Integration box where you can send sample values and see the result before real customers do.

The variables you can use are phone, amount, amount_int (a whole-number amount), api_id (the plan's provider ID), plan_type, network_code, iuc_number, meter_number, meter_type, customer_name, reference, service_slug, bypass and validate_phone. The last two are opposites: bypass is 1 when the customer has switched phone validation off, and validate_phone is 1 when validation is on. Map whichever one your provider expects.

Illustrative example: the provider, address and field names below are made up to show the idea. If a provider's data endpoint accepts {"mobile": "...", "plan": "...", "ref": "..."} and replies with {"result": {"state": "ok", "id": "A123"}}, you would send mobile as {{phone}}, plan as {{api_id}} and ref as {{reference}}, and map status_field to result.state, success_value to ok and ref_field to result.id. Anything that does not match the success value is treated as a failure, and the comparison ignores upper and lower case.

Or use SIM Host

You can also route a network through SIM Host, which uses real SIM cards on an Android phone, as explained in our SIM hosting guide.

What happens when a provider is slow or fails

The platform treats the different failures differently, because the right answer depends on whether the order may have been delivered.

• A clear "no", an error message, a server error or a provider that cannot be reached at all: nothing was delivered, so the purchase is marked failed and the customer is refunded straight away.
• The provider received the order and then went quiet (a slow reply, or an empty one): the order may have been delivered, so refunding at once could mean paying twice. The purchase is held as pending with a "needs confirmation" label, the customer stays charged, and you can confirm or refund it, or it is refunded automatically after a wait you can set in Settings.
• ArewaBundle is the exception: a slow or empty reply is counted as a success and flagged in the transaction message, because that provider is known to complete orders without answering in time.

Our guide on handling failed transactions and wallet refunds has the full steps, and understanding transactions and provider responses explains each status.

Import plans, then set your prices

After connecting a provider, import its plans using Browse plans, then Import selected plans. The imported plans arrive with your price equal to the provider's cost, which means zero profit. Open the plans and set your own selling prices straight away. We cover this in importing networks and plans and pricing your data plans.

Test every service before you announce it

• Fund your provider account with a small balance first.
• Make a small purchase on each network you plan to sell, from your own phone.
• Check the result in Insights, then Transactions. Expand the row and read the provider message.
• If a purchase fails, check the plan ID or network code, your provider balance and the number format.
• Repeat after any change to plans or providers.

Choosing a provider

Compare more than the headline price. Ask about uptime, how fast purchases complete, how failures are handled, whether there is a test mode, how good the documentation is and how quickly support replies. A slightly cheaper provider that fails often costs you more in refunds and lost customers than it saves. Our guide on what a vending API is explains the basics, and if you do not yet have a site you can start on our VTU solution.