Android—OAuth on mobile

United States

Interconnects

The Clover app ties the merchant to the mobile app, and provides authorization from Clover to operate your app on Clover systems. The Clover app is installed on the merchant. The Clover app's ID and Secret are provided to the mobile app.

The merchant provides authorization to their employee(s), the Clover app, and your mobile app. Employees are configured on the merchant. The Clover app is installed on the merchant.

The site URL is validated against a redirect URI provided by your mobile app during OAuth. The redirect URI must have the same base as the site URL configured for your Clover app. The site URL is configured on the Clover app. The redirect URI is configured in the mobile app.

OAuth flow

  1. Initialize the software development kit (SDK):
    • Use the GoSDKCreator.
    • Pass in your built configuration object.
    • In the configuration object, include a CloverPaymentSDK.FullOAuth object for full OAuth Support.
  2. GoSDK attempts to recover a valid token stored securely in EncryptedSharedPreferences. If it finds a valid token, it completes initialization.
  3. If a valid token is not found, GoSDK initiates OAuth login using the system webview. This opens the login page in your configured environment for the user to log in. App identification information from your configuration is passed in at this point to ensure your app is authorized to log in for the merchant and employee.
  4. When login succeeds, GoSDK receives a code.
  5. GoSDK exchanges the code for a token, stores the token back into EncryptedSharedPreferences for future launches, and continues with SDK initialization.

Structure

class GoSdkCreator {
    companion object {
        fun create(configuration: GoSdkConfiguration)
    }
}
class GoSdkConfiguration private constructor(
    val context: Context,
    val appId: String,
    val oAuthFlowRedirectURI: String,
    val oAuthFlowAppID: String,
    val oAuthFlowAppSecret: String,
    val appVersion: String,
    val apiKey: String,
    val apiSecret: String,
    var apiAccessToken: String?,
    val environment: Environment,
    val enableLogging: Boolean,
    val allowDuplicates: Boolean,
) {
    enum class Environment { PROD, SANDBOX, STAGING, DEV }
    data class Builder(
        // URI used in the OAuth flow to get the code/token back to your app. This needs to match what is configured in your Clover App settings for the Site URL
        val oAuthFlowRedirectURI: String,

        // App ID registered on your Clover Developer Portal, used by the OAuth Flow to match permissions to your app when your merchant logs in.
        val oAuthFlowAppID: String,

        // App Secret obtained from your Clover Developer Portal. This is the secret associated with your App ID.
        val oAuthFlowAppSecret: String,

        // API Key for server access. Contact your Developer Relations representative for a valid Key and Secret.
        val apiKey: String,

        // API Secret for server access. Contact your Developer Relations representative for a valid Key and Secret.
        val apiSecret: String,

        // The server environment that we will send all server calls to.
        val environment: Environment,

        val enableLogging: Boolean = false,
        val allowDuplicates: Boolean = false,
    ) {
        fun enableLogging(enableLogging: Boolean) = copy(enableLogging = enableLogging)
        fun allowDuplicates(allowDuplicates: Boolean) = copy(allowDuplicates = allowDuplicates)

        fun build() = GoSdkConfiguration(
            context = context,
            appId = appId,
            appVersion = appVersion,
            apiKey = apiKey,
            apiSecret = apiSecret,
            apiAccessToken = apiAccessToken,
            oAuthFlowRedirectURI = oAuthFlowRedirectURI,
            oAuthFlowAppID = oAuthFlowAppID,
            oAuthFlowAppSecret = oAuthFlowAppSecret,
            environment = environment,
            enableLogging = enableLogging,
            allowDuplicates = allowDuplicates
        )
    }
}

Implementation

When your app launches, any stored tokens are loaded from EncryptedSharedPreferences.  If there is a token, it initializes the SDK. If there is not a token, then it redirects to the default web browser for the user to log in.  When authentication succeeds, the SDK receives the code and exchanges it for a token, stores it securely in EncryptedSharedPreferences, and finishes initializing the SDK.

Refer to the Android—Clover Go SDK quick start guide OAuth section for OAuth implementation instructions.