Reloadly Airtime Connector

info@ismena.com

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

Overview

The Reloadly Airtime Connector enables seamless integration with the Reloadly Airtime service, providing access to mobile top-up, operator, and transaction data for various countries and operators. This connector acts as a proxy to simplify data retrieval and interaction, supporting actions for account balance, country and operator information, foreign exchange rates, commissions, promotions, top-ups, transaction reports, and mobile number portability (MNP) lookups.

Integration Overview

This document provides a comprehensive guide for each integration point, its purpose, configuration, and workflow support using the Reloadly Airtime Connector.

Supported Integration Action Points

getAccessToken: Generates an access token for authentication.
getAccountBalance: Retrieves the current account balance for the authenticated user.
getAllCountries: Retrieves a list of all supported countries.
getCountryByCode: Retrieves details for a specific country by its ISO code.
getAllOperators: Retrieves a list of all supported operators.
getOperatorById: Retrieves details for a specific operator by its ID.
autoDetectOperator: Automatically detects the operator for a given phone number and country code.
getOperatorsByCountry: Retrieves operators for a specific country with filtering options.
getFxRate: Retrieves foreign exchange rates for top-up transactions.
getAllCommissions: Retrieves commission details for all operators.
getCommissionById: Retrieves commission details for a specific operator.
getAllPromotions: Retrieves all available promotions.
getPromotionById: Retrieves details for a specific promotion.
getPromotionsByCountry: Retrieves promotions for a specific country.
getPromotionsByOperator: Retrieves promotions for a specific operator.
makeTopup: Initiates a synchronous top-up transaction.
makeAsyncTopup: Initiates an asynchronous top-up transaction.
getTopupStatus: Retrieves the status of a specific top-up transaction.
getAllTransactions: Retrieves a list of all transactions with filtering options.
getTransactionById: Retrieves details for a specific transaction.
mnpLookupGet: Performs an MNP lookup for a phone number and country code.
mnpLookupPost: Performs an MNP lookup for operator details via a POST request.

Detailed Integration Documentation

Authentication

Action	getAccessToken
Purpose	Generates an access token for authenticating requests to the MobileTopUp service. This is the initial step for accessing protected endpoints.
Parameters	Required: JSON payload: Authentication credentials (object, e.g., {client_id: "YOUR_CLIENT_ID", client_secret: "YOUR_CLIENT_SECRET", grant_type: "client_credentials"}). Optional: None.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_MOBILETOPUP_BASE_URL environment variable.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). access_token: Bearer token for authentication (string, e.g., YOUR-TOKEN). token_type: Type of token (string, e.g., Bearer). expires_in: Token expiration time in seconds (integer, e.g., 3600). Failure: Returns error details (e.g., error-type: invalid-client).
Workflow Example	Configure the connector with the appropriate base URL. Execute the getAccessToken action with a JSON payload containing client credentials. Store the access token for use in subsequent authenticated requests.

Account Balance Retrieval

Action	getAccountBalance
Purpose	Retrieves the current balance of the authenticated user's account. This serves as the primary entry point for checking available funds.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: None.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_Reloadly_Airtime_BASE_URL environment variable.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). balance: Account balance details (object, e.g., {amount: 100.50, currency: "USD"}). Failure: Returns error details (e.g., error-type: unauthorized).
Workflow Example	Configure the connector with the appropriate base URL. Execute the getAccountBalance action with a valid Bearer token. Process the response to display the account balance in a dashboard.

Countries Retrieval

Action	getAllCountries
Purpose	Retrieves a list of all supported countries. This helps users identify available countries for top-up services.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). countries: Array of country objects (e.g., [{code: "US", name: "United States"}, {code: "GB", name: "United Kingdom"}]). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getAllCountries action with a valid Bearer token. Use the response to populate a country selection dropdown in the UI.

Country by Code Retrieval

Action	getCountryByCode
Purpose	Retrieves detailed information for a specific country by its ISO code. This provides targeted country data for top-up applications.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). countrycode: ISO country code (string, e.g., US). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). country: Country details (object, e.g., {code: "US", name: "United States", currency: "USD"}). Failure: Returns error details (e.g., error-type: unsupported-code).
Workflow Example	Execute the getCountryByCode action with a valid Bearer token and countrycode=US. Use the response to display country-specific information in the UI.

Operators Retrieval

Action	getAllOperators
Purpose	Retrieves a list of all supported operators. This helps users identify available operators for top-up services.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). operators: Array of operator objects (e.g., [{id: 1, name: "Operator A"}, {id: 2, name: "Operator B"}]). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getAllOperators action with a valid Bearer token. Use the response to populate an operator selection interface.

Operator by ID Retrieval

Action	getOperatorById
Purpose	Retrieves detailed information for a specific operator by its ID. This provides targeted operator data for top-up applications.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). operatorid: Operator ID (integer, e.g., 1). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). operator: Operator details (object, e.g., {id: 1, name: "Operator A", countryCode: "US"}). Failure: Returns error details (e.g., error-type: invalid-operator-id).
Workflow Example	Execute the getOperatorById action with a valid Bearer token and operatorid=1. Use the response to display operator-specific details in the UI.

Auto-Detect Operator

Action	autoDetectOperator
Purpose	Automatically detects the operator for a given phone number and country code. This simplifies operator identification for top-up transactions.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). phone: Phone number (string, e.g., +12025550123). countrycode: ISO country code (string, e.g., US). Optional: suggestedAmountsMap: Include suggested amounts map (boolean, e.g., true). suggestedAmounts: Include suggested amounts (boolean, e.g., true).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). operator: Detected operator details (object, e.g., {id: 1, name: "Operator A"}). Failure: Returns error details (e.g., error-type: invalid-phone-number).
Workflow Example	Execute the autoDetectOperator action with a valid Bearer token, phone=+12025550123, and countrycode=US. Use the detected operator to initiate a top-up transaction.

Operators by Country Retrieval

Action	getOperatorsByCountry
Purpose	Retrieves a list of operators for a specific country with filtering options. This helps users select operators based on specific criteria.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). countrycode: ISO country code (string, e.g., US). Optional: suggestedAmountsMap: Include suggested amounts map (boolean, e.g., true). suggestedAmounts: Include suggested amounts (boolean, e.g., true). includePin: Include PIN-based operators (boolean, e.g., true). includeData: Include data-based operators (boolean, e.g., true). includeBundles: Include bundle-based operators (boolean, e.g., true). includeCombo: Include combo-based operators (boolean, e.g., true). comboOnly: Return only combo-based operators (boolean, e.g., true). bundlesOnly: Return only bundle-based operators (boolean, e.g., true). dataOnly: Return only data-based operators (boolean, e.g., true). pinOnly: Return only PIN-based operators (boolean, e.g., true).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). operators: Array of operator objects (e.g., [{id: 1, name: "Operator A"}, {id: 2, name: "Operator B"}]). Failure: Returns error details (e.g., error-type: unsupported-code).
Workflow Example	Execute the getOperatorsByCountry action with a valid Bearer token, countrycode=US, and optional filters like includeData=true. Use the response to populate an operator selection interface.

Foreign Exchange Rate Retrieval

Action	getFxRate
Purpose	Retrieves foreign exchange rates for top-up transactions. This provides rate information for cross-currency top-ups.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). JSON payload: Details of the transaction (object, e.g., {amount: 10, currency: "USD"}). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). fxRate: Exchange rate details (object, e.g., {rate: 1.2, targetCurrency: "EUR"}). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getFxRate action with a valid Bearer token and a JSON payload. Use the exchange rate for calculating top-up costs in the target currency.

Commissions Retrieval

Action	getAllCommissions
Purpose	Retrieves commission details for all operators. This helps users understand commission structures.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: size: Number of records per page (integer, e.g., 10). page: Page number (integer, e.g., 1).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). commissions: Array of commission objects (e.g., [{operatorId: 1, rate: 0.05}, {operatorId: 2, rate: 0.03}]). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getAllCommissions action with a valid Bearer token and optional parameters like size=10. Use the response to display commission details in a reporting tool.

Commission by ID Retrieval

Action	getCommissionById
Purpose	Retrieves commission details for a specific operator. This provides targeted commission data for analysis.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). operatorid: Operator ID (integer, e.g., 1). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). commission: Commission details (object, e.g., {operatorId: 1, rate: 0.05}). Failure: Returns error details (e.g., error-type: invalid-operator-id).
Workflow Example	Execute the getCommissionById action with a valid Bearer token and operatorid=1. Use the response to analyze commission rates for the operator.

Promotions Retrieval

Action	getAllPromotions
Purpose	Retrieves all available promotions. This helps users identify promotional offers for top-ups.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: size: Number of records per page (integer, e.g., 10). page: Page number (integer, e.g., 1). languageCode: Language code for promotion details (string, e.g., en).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). promotions: Array of promotion objects (e.g., [{id: 1, title: "Promo A"}, {id: 2, title: "Promo B"}]). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getAllPromotions action with a valid Bearer token and optional parameters like languageCode=en. Use the response to display promotions in the UI.

Promotion by ID Retrieval

Action	getPromotionById
Purpose	Retrieves details for a specific promotion. This provides targeted promotion data for user engagement.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). promotionid: Promotion ID (integer, e.g., 1). Optional: languageCode: Language code for promotion details (string, e.g., en).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). promotion: Promotion details (object, e.g., {id: 1, title: "Promo A", description: "Details"}). Failure: Returns error details (e.g., error-type: invalid-promotion-id).
Workflow Example	Execute the getPromotionById action with a valid Bearer token and promotionid=1. Use the response to display promotion details in the UI.

Promotions by Country Retrieval

Action	getPromotionsByCountry
Purpose	Retrieves promotions for a specific country. This helps users discover country-specific offers.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). countrycode: ISO country code (string, e.g., US). Optional: languageCode: Language code for promotion details (string, e.g., en).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: result: Success status (string, e.g., success). promotions: Array of promotion objects (e.g., [{id: 1, title: "Promo A"}, {id: 2, title: "Promo B"}]). Failure: Returns error details (e.g., error-type: unsupported-code).
Workflow Example	Execute the getPromotionsByCountry action with a valid Bearer token and countrycode=US. Use the response to display country-specific promotions.

Promotions by Operator Retrieval

Action	getPromotionsByOperator
Purpose	Retrieves promotions for a specific operator. This provides targeted promotional data for operator-specific top-ups.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). operatorid: Operator ID (integer, e.g., 1). Optional: languageCode: Language code for promotion details (string, e.g., en).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). promotions: Array of promotion objects (e.g., [{id: 1, title: "Promo A"}, {id: 2, title: "Promo B"}]). Failure: Returns error details (e.g., error-type: invalid-operator-id).
Workflow Example	Execute the getPromotionsByOperator action with a valid Bearer token and operatorid=1. Use the response to display operator-specific promotions.

Synchronous Top-Up

Action	makeTopup
Purpose	Initiates a synchronous top-up transaction. This allows immediate processing of top-up requests.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). JSON payload: Top-up details (object, e.g., {phone: "+12025550123", amount: 10, operatorId: 1}). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). transaction: Transaction details (object, e.g., {id: 123, status: "completed"}). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the makeTopup action with a valid Bearer token and a JSON payload. Save the transaction details for reporting or user confirmation.

Asynchronous Top-Up

Action	makeAsyncTopup
Purpose	Initiates an asynchronous top-up transaction. This allows processing of top-ups with delayed confirmation.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., `Bearer YOUR-TOKEN`). JSON payload: Top-up details (object, e.g., `{phone: "+12025550123", amount: 10, operatorId: 1}`). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: `result`: Success status (string, e.g., `success`). `transaction`: Transaction details (object, e.g., `{id: 123, status: "pending"}`). Failure: Returns error details (e.g., `error-type: invalid-request`).
Workflow Example	Execute the `makeAsyncTopup` action with a valid Bearer token and a JSON payload. Monitor the transaction status using the `getTopupStatus` action.

Top-Up Status Retrieval

Action	getTopupStatus
Purpose	Retrieves the status of a specific top-up transaction. This helps users track the progress of top-ups.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). transactionId: Transaction ID (integer, e.g., 123). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). status: Transaction status (string, e.g., completed). Failure: Returns error details (e.g., error-type: invalid-transaction-id).
Workflow Example	Execute the getTopupStatus action with a valid Bearer token and transactionId=123. Use the status to update the user interface or trigger notifications.

Transactions Retrieval

Action	getAllTransactions
Purpose	Retrieves a list of all transactions with filtering options. This supports transaction reporting and analysis.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). Optional: size: Number of records per page (integer, e.g., 10). page: Page number (integer, e.g., 1). countryCode: Filter by country code (string, e.g., US). operatorId: Filter by operator ID (integer, e.g., 1). operatorName: Filter by operator name (string, e.g., Operator A). customIdentifier: Filter by custom identifier (string, e.g., custom123). startDate: Filter by start date (string, e.g., 2025-01-01). endDate: Filter by end date (string, e.g., 2025-12-31).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). transactions: Array of transaction objects (e.g., [{id: 123, amount: 10}, {id: 124, amount: 20}]). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the getAllTransactions action with a valid Bearer token and optional filters like countryCode=US. Use the response to generate transaction reports.

Transaction by ID Retrieval

Action	getTransactionById
Purpose	Retrieves details for a specific transaction. This provides targeted transaction data for analysis.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). transactionId: Transaction ID (integer, e.g., 123). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). transaction: Transaction details (object, e.g., {id: 123, amount: 10, status: completed}). Failure: Returns error details (e.g., error-type: invalid-transaction-id).
Workflow Example	Execute the getTransactionById action with a valid Bearer token and transactionId=123. Use the response to display transaction details in the UI.

MNP Lookup (GET)

Action	mnpLookupGet
Purpose	Performs a mobile number portability lookup for a phone number and country code. This identifies the current operator for a phone number.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). phone: Phone number (string, e.g., +12025550123). countryCode: ISO country code (string, e.g., US). Optional: suggestedAmountsMap: Include suggested amounts map (boolean, e.g., true). suggestedAmounts: Include suggested amounts (boolean, e.g., true).
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). operator: Operator details (object, e.g., {id: 1, name: "Operator A"}). Failure: Returns error details (e.g., error-type: invalid-phone-number).
Workflow Example	Execute the mnpLookupGet action with a valid Bearer token, phone=+12025550123, and countryCode=US. Use the response to confirm the operator for a top-up transaction.

MNP Lookup (POST)

Action	mnpLookupPost
Purpose	Performs a mobile number portability lookup for operator details via a POST request. This supports bulk or complex MNP lookups.
Parameters	Required: Authorization: Bearer token in the request header (string, e.g., Bearer YOUR-TOKEN). JSON payload: Lookup details (object, e.g., {phone: "+12025550123", countryCode: "US"}). Optional: None.
Configuration	Ensure the connector is configured with the correct base URL.
Output	Successful: Returns a JSON object with: result: Success status (string, e.g., success). operator: Operator details (object, e.g., {id: 1, name: "Operator A"}). Failure: Returns error details (e.g., error-type: invalid-request).
Workflow Example	Execute the mnpLookupPost action with a valid Bearer token and a JSON payload. Use the response to confirm operator details for top-up transactions.

Workflow Creation with the Connector

Example Workflow: Mobile Top-Up and Transaction Reporting

Retrieve Supported Countries

Use the getAllCountries action to fetch a list of available countries.
Identify target countries (e.g., US, GB).

Query Operators

Execute the getOperatorsByCountry action with a valid Bearer token and countrycode=US to fetch operators.
Process the response to display operators in a top-up interface.

Perform Top-Up

Use the makeTopup action with a valid Bearer token and a JSON payload to initiate a top-up.
Save the transaction details for user confirmation or reporting.

Monitor Transaction Status

Execute the getTopupStatus action with a valid Bearer token to check the status of an async top-up.
Update the UI with the transaction status.

Generate Transaction Report

Execute the getAllTransactions action with a valid Bearer token and filters like startDate=2025-01-01 to fetch transactions.
Analyze the data for financial reporting or user insights

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to IBM x iSolution Event