Getting Started

The High-Level PhonePOS API is a Java- and Kotlin-compatible API designed for seamless integration with the PhonePOS application.
It comprises two specialized sub-APIs: the Configuration API and the Transaction API. These sub-APIs replace previous APIs, including Personalisation API, TerminalHelperService, and mAPI, providing a more streamlined and simpler integration. The following diagram illustrates the capabilities of each sub-API.

Setup

The High-Level PhonePOS API library is designed for use with both PhonePOS APP and SDK. Before you can include the library as a dependency, you need to add the Rubean repository to your project. Please refer to the detailed guide here: Repository Setup.

To integrate the library, add the following line to the dependencies section of your app-level build.gradle file:

dependencies {
    ...
    implementation "com.rubean.phonepos:api:{LATEST_VERSION}"
    ...
}

info

We do regularly update our API to give you the best experience. We will notify you if there is a new version.

warning

PhonePOS API starting from 2.0.0 and above, required gradle plugin version to be 8.0.0 or above.

Example

To get an instance of the PhonePos API, use the PhonePosFactory.getPhonePosApi() function.
This function requires two parameters:

• phoneposEnvironment: Specifies environment variables for identifying terminal.
• context: The active Android context class.

info

To avoid terminal connection leaks, please make sure to properly destroy phonePosApi instance by calling phonePosApi.onDestroy(Context) in onDestroy callback of the Activity (or any other place if applicable).

After destroying the phonePosApi instance it can not be reused. Please create a new one if needed.

public class PhonePosApiActivity extends AppCompatActivity {

    private PhonePosApi phonePosApi;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        phonePosApi = PhonePosFactory.getPhonePosApi(getPhonePosEnvironment(), this);
        
        // to get the configurationAPI execute
        phonePosApi.getConfigurationApi();
        
        // to get the transactionAPI execute
        phonePosApi.getTransactionApi();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        phonePosApi.onDestroy(this);
        phonePosApi = null;
    }

    private PhonePosEnvironment getPhonePosEnvironment() {
        /*
         * For proper functionality of PhonePosApi, return the appropriate applicationId:
         *
         * - If using the PhonePOS APK/AAB:
         *   Return the applicationId of the PhonePOS app.
         *   Ensure the "query" parameter in your AndroidManifest is set correctly.
         *   Refer to the APK setup chapter for additional details.
         *
         * - If using the PhonePOS SDK:
         *   Return the applicationId of your own app.
         *
         * It is critical to return the correct value here, as the PhonePosApi will NOT work otherwise.
         */
        String applicationId = "your_phone_pos_application_id"; // Replace with your applicationId. 
        
        /*
         * apiKey and apiSecret should be provided by PhonePOS support.
         * If you do NOT have access to the data above, please contact the support team.
         */
        String apiKey = "api_key_provided_by_phonepos";
        String apiSecret = "api_secret_provided_by_phonepos";
        
        return PhonePosFactory.getEnvironment(applicationId, apiKey, apiSecret);
    }
}