Custom Connector
Reloadly Airtime Connector
Global
The Reloadly Airtime Connector enables seamless integration with the Reloadly Airtime service, providing access to mobile top-up, operator, and transaction data across countries and operators. It supports account balance, country and operator information, FX rates, commissions, promotions, top-ups, transaction reports, and mobile number portability (MNP) lookups.
Overview
Integration Overview
This document provides a comprehensive guide for each integration point, its purpose, configuration, and workflow support using the Reloadly Airtime Connector.
- getAccessToken / getAccountBalance. Generate an access token, and check the authenticated account balance.
- getAllCountries / getCountryByCode. List all supported countries, or fetch one by ISO code.
- getAllOperators / getOperatorById / autoDetectOperator / getOperatorsByCountry. List operators, fetch by ID, auto-detect from a phone number, or filter by country.
- getFxRate. Retrieve foreign-exchange rates for top-up transactions.
- getAllCommissions / getCommissionById. Retrieve commission details for all operators or a specific one.
- getAllPromotions / getPromotionById / getPromotionsByCountry / getPromotionsByOperator. Retrieve promotions globally, by ID, by country, or by operator.
- makeTopup / makeAsyncTopup / getTopupStatus. Initiate synchronous or asynchronous top-ups, and check status.
- getAllTransactions / getTransactionById. Retrieve transaction lists (with filters) or a specific transaction.
- mnpLookupGet / mnpLookupPost. Perform mobile number portability lookups via GET or POST.
Documentation
Detailed Integration Documentation
Authentication & Balance
| Actions | getAccessToken / getAccountBalance |
|---|---|
| Purpose | Generates an OAuth access token from client credentials, and retrieves the authenticated account’s balance. |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | getAccessToken required: JSON payload {client_id, client_secret, grant_type: client_credentials}. getAccountBalance required: Authorization Bearer token. |
| Output | Successful: access_token / token_type / expires_in, or a balance object {amount, currency}. Failure: invalid-client / unauthorized. |
| Workflow example | Call getAccessToken, store the token, then getAccountBalance to display available funds. |
Countries & Operators
| Actions | getAllCountries / getCountryByCode / getAllOperators / getOperatorById / autoDetectOperator / getOperatorsByCountry |
|---|---|
| Purpose | Lists supported countries and operators, fetches one by code/ID, auto-detects an operator from a phone number, and filters operators by country (PIN/data/bundle/combo). |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | Required: Authorization Bearer token; countrycode / operatorid / phone as applicable. Optional: suggestedAmounts(Map); includePin/includeData/includeBundles/includeCombo and *Only flags. |
| Output | Successful: arrays or objects of country/operator details. Failure: unsupported-code / invalid-operator-id / invalid-phone-number. |
| Workflow example | autoDetectOperator with phone=+12025550123 and countrycode=US, then getOperatorsByCountry with includeData=true. |
FX Rates & Commissions
| Actions | getFxRate / getAllCommissions / getCommissionById |
|---|---|
| Purpose | Retrieves foreign-exchange rates for a transaction, and commission details for all operators or a specific one. |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | getFxRate required: Bearer token; JSON payload {amount, currency}. Commissions optional: size; page (and operatorid for by-ID). |
| Output | Successful: fxRate {rate, targetCurrency}, or commission objects {operatorId, rate}. Failure: invalid-request / invalid-operator-id. |
| Workflow example | getFxRate for cross-currency cost, then getAllCommissions with size=10 for a reporting tool. |
Promotions
| Actions | getAllPromotions / getPromotionById / getPromotionsByCountry / getPromotionsByOperator |
|---|---|
| Purpose | Retrieves promotional offers — all, by ID, by country, or by operator. |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | Required: Authorization Bearer token; promotionid / countrycode / operatorid as applicable. Optional: size; page; languageCode. |
| Output | Successful: promotion objects {id, title, description}. Failure: invalid-request / invalid-promotion-id / unsupported-code. |
| Workflow example | getPromotionsByCountry with countrycode=US to display country-specific offers. |
Top-Ups (sync / async / status)
| Actions | makeTopup / makeAsyncTopup / getTopupStatus |
|---|---|
| Purpose | Initiates a synchronous or asynchronous top-up transaction, and retrieves the status of a specific top-up. |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | Top-up required: Bearer token; JSON payload {phone, amount, operatorId}. getTopupStatus required: transactionId. |
| Output | Successful: transaction {id, status: completed/pending}, or a status string. Failure: invalid-request / invalid-transaction-id. |
| Workflow example | makeAsyncTopup with a JSON payload, then poll getTopupStatus with transactionId=123. |
Transactions & MNP Lookup
| Actions | getAllTransactions / getTransactionById / mnpLookupGet / mnpLookupPost |
|---|---|
| Purpose | Retrieves transaction lists (with filters) or a specific transaction, and performs mobile number portability lookups via GET or POST. |
| Configuration | Configure the connector with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL. All calls require a Bearer token in the Authorization header. |
| Parameters | Required: Authorization Bearer token; transactionId / phone+countryCode as applicable. Transactions optional: size, page, countryCode, operatorId/Name, customIdentifier, startDate, endDate. |
| Output | Successful: transaction arrays/objects, or operator details from the MNP lookup. Failure: invalid-request / invalid-transaction-id / invalid-phone-number. |
| Workflow example | getAllTransactions with startDate=2025-01-01 for reporting; mnpLookupGet with phone and countryCode to confirm an operator. |
Example Workflow: Mobile Top-Up & Reporting
| Countries | Use getAllCountries to identify targets (US, GB). |
|---|---|
| Operators | Use getOperatorsByCountry with countrycode=US to populate a top-up interface. |
| Top-up | Use makeTopup with a JSON payload, then getTopupStatus for async confirmation. |
| Report | Use getAllTransactions with startDate=2025-01-01 for financial reporting. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.