Configuration API (under construction)

We refer to the registration and provision of a terminal as personalisation.
When you install the PhonePOS APK or your own PhonePOS SDK implementation, the installed terminals by default are unpersonalised and need to get activated/personalised. With a successful personalisation you will have an active terminal, i.e., a terminal that is able to process transactions.
This page will give you a short overview of the different personalisation methods that you can evaluate for personalisation.

Personalisation methods

We support multiple ways of personalising a terminal to fit different use cases.
Before choosing a personalisation method, keep in mind that some personalisation methods have prerequisites e.g., an MDM (Mobile Device Management) environment.

Getting started

The personalisation API consists of several operations, and these are the items you need throughout the process. Before starting terminal initialisation, you need to check the terminal status.

To use the personalisation API, first initialise the PhonePos API instance. For that, see the code below.

class SdkLauncherViewController: UIViewController {

    var phonePosApi: PhonePosApi!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Assuming PhonePosFactory and getConfigurationApi are accessible in Swift
        // application id will be provided for you during the scenario
        phonePosApi = PhonePosFactory.getConfigurationApi(applicationId: BuildConfig.APPLICATION_ID_FOR_PHONE_POS_APP)
        
        // Set up any further configurations or UI elements here
    }
    
}

Getting Terminal Status

After obtaining the personalisation API instance, check the terminal status.

tip

If the terminal is already set up, no further steps are required.

Other than "already personalised" there are several responses that you can get.

class MainViewController: UIViewController {

    var phonePosApi: PhonePosApi!
    
    // ... Additional properties and methods

    func retrieveStatus() {
        phonePosApi.getConfigurationApi().getStatus { terminalStatus, errorMessage in
            switch terminalStatus {
            case .statusTerminalOperational:
                // Terminal is fully functional, proceed to payments.
                print("Terminal is operational.")
                
            case .terminalNotOperational, .statusPersonalizationFailed:
                // Check the reason in errorMessage.reason
                if let reason = errorMessage?.reason {
                    switch reason {
                    case .batteryLow:
                        // Ask merchant to charge the phone
                        print("Battery is low, please charge the device.")
                    default:
                        // For other reasons, contact support
                        print("Contact support with error details.")
                    }
                }
                
            case .statusGeneralError:
                // Communicate this case to support team
                print("General error occurred. Contact support.")
                
            case .statusAppIsOutdated:
                // Prompt to update the application
                print("Application is outdated. Please update.")
                
            case .statusPersonalizationNotDoneYet:
                // Can proceed to the next step for personalization
                print("Personalization not done yet. Proceed to the next step.")
                
            default:
                break
            }
        }
    }
}

In case the terminal status is statusPersonalizationNotDoneYet, you can proceed to the next step to set up your terminal.

Starting the Personalisation process

At this stage you should already have checked status of the terminal and it should have shown you that the terminal is NOT personalised yet. The process can be started for the merchant by calling: startPersonalisation(...) function:

class MainViewController: UIViewController {

    var phonePosApi: PhonePosApi!
    
    // ... Additional properties and methods

    private func startPersonalisation() {
        let provider = DataProviderFactory.chooseYourData(...) // Replace with actual parameters
        
        phonePosApi.getConfigurationApi().startPersonalisation(provider: provider) { result, statusCode in
            switch result {
            case .success:
                // Personalisation was successful; user can make payments
                print("Personalisation succeeded. User can now make payments.")
                
            case .failure(let personalisationResult):
                // Personalisation failed; handle the error and statusCode
                if let code = statusCode {
                    print("Personalisation failed with status code: \(code). Please contact support if unknown.")
                } else {
                    print("Personalisation failed with no specific status code. Please contact support.")
                }
            }
        }
    }
}

Reset the terminal

In some rare cases when you need to disable/delete a terminal you can use our reset API You will provide the information about the terminal that needs to be reset and PhonePos will take care of everything

class MainViewController: UIViewController {

    var phonePosApi: PhonePosApi!
    
    // ... 

    private func resetTerminal() {
        let provider = DataProviderFactory.chooseYourData(...) // Replace with actual parameters
        
        phonePosApi.getConfigurationApi().reset { wasResetSuccess in
            if wasResetSuccess {
                // Reset was successful
                print("Terminal reset successfully.")
            } else {
                // Reset was NOT successful; you may want to retry the operation
                print("Reset was not successful. Please try again.")
                // Handle potential retries or alerts to the user
            }
        }
    }
}