Clover Developers WEB API (Tutorial Series : Authorization Flow)

Posted on By Jonathan
Listen to this article

This is the first iteration in my tutorial for OAUTH 2.0 authorization flow and may change.

If you are developing a Web App for Clover Merchants. The best practice is that your app is CORS compliant. This means that your app must gain merchant authorization, receive an Authorization Code, and query the server for an API Token. This will allow your app to access a merchant’s database. And in doing so, this makes it more dynamic to obtain API Tokens.

Before continuing with this tutorial, I assume you are familiar with HTML/PHP or Android Studio (Java). The authorization flow is similar with both cURL in PHP and okHTTP3 in Android Studio and will include sample code for both.

Let’s get started.

In your Developer dashboard (https://www.clover.com/developers/login), under Settings, you must take note of your App ID and App Secret which will be used in future API calls. Make sure your Web Configuration -> Site URL is set correctly and Default OAuth Response is set to Code. Required Permissions is set to the correct permissions your app will Read from and Write to.

For the first step to obtaining an API Token, you must send your APP ID to Clover in order to verify that a Merchant has “Installed” your app on their account. This requires sending the Merchant to the Clover website to login.

This can be accomplished by a simple anchor in HTML/PHP or an Intent with Java.

HTML

<a href="https://sandbox.dev.clover.com/oauth/authorize?client_id=YOUR_APP_ID">Click Here</a>

JAVA

String uri = String.format("https://sandbox.dev.clover.com/oauth/authorize?client_id=%s", YOUR_APP_ID);
Uri authEndpoint = Uri.parse(uri);
Intent intent = new Intent(Intent.ACTION_VIEW, authEndpoint);
intent.putExtra(Browser.EXTRA_APPLICATION_ID, this.getPackageName());
startActivity(intent);

When the Merchant is redirected back to your app, you will receive the Authorization Code as a query string in the URL.

https://www.example.com/oauth_callback?merchant_id={MERCHANT_ID}&client_id={APP_ID}&code={AUTHORIZATION_CODE}

In PHP you can simply use the Global Variable $_GET(‘code’) to get the Authorization Code from the URL when the Merchant is redirected back to your server. In JAVA, in onResume you can use .getQueryParameter(‘code’) to get the Authorization Code from the previous Intent.

After retrieving the Authorization Code, now we’re on to requesting an API Token through cURL in PHP or okHTTP3 in JAVA.

This can be accomplished in PHP and JAVA in the following ways.

PHP

<?php 
$clientId = YOUR_CLIENT_ID;
$clientSecret = YOUR_CLIENT_SECRET;
$code = AUTH_CODE;

$ch = curl_init();
curl_setopt_array($ch, array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_URL => sprintf('https://sandbox.dev.clover.com/oauth/token?client_id=%s&client_secret=%s&code=%s', $clientId, $clientSecret, $code)
));
$result = json_decode(curl_exec($ch));
if ($result === false) {
    echo String.format('%s: %s', 'Curl error', curl_error($ch));
} else {
    echo $result -> access_token;
    curl_close($ch);
}
?>

JAVA

String clientId = YOUR_CLIENT_ID;
String clientSecret = YOUR_CLIENT_SECRET;
String code = AUTH_CODE;

JSONObject data = null;
OkHttpClient client = new OkHttpClient();

String uri = String.format('https://sandbox.dev.clover.com/oauth/token?client_id=%s&client_secret=%s&code=%s', clientId, clientSecret, code);

MediaType JSON = MediaType.parse("application/json; charset=utf-8");
RequestBody body;
HttpUrl reqUrl;

reqUrl = HttpUrl.parse(uri);

Request.Builder builder = new Request.Builder();
String method = params.getJSONObject("params").optString("method");

body = RequestBody.create(JSON, params.getJSONObject("params").optString("body"));
builder.method(method, body);

assert reqUrl != null;
builder.url(reqUrl);
Request request = builder.build();
try {
    Call call = client.newCall(request);
    Response nqResponse = call.execute();

    if (String.valueOf(nqResponse.code()).equals("200")) {
        assert nqResponse.body() != null;
        String response = nqResponse.body().string();
        data = new JSONObject(response);
    } else {
        data = new JSONObject();
    }
} catch (IOException | JSONException e) {
    e.printStackTrace();
}
console.log(data.optString("access_token"));
}

The returned result should be just the Access Token as a string. Instead of printing the Access Token to the screen or logging it to the console, it should be encrypted and saved to a database for further API calls.

More information can be found about how Clover implements CORS and OAUTH 2.0 on their website at https://docs.clover.com/build/web-apps/.

The next part of this tutorial will be a simple API call to retrieve and display the Merchant Information. I will be posting it soon so if you’re interested, keep an eye out.

If there is any part of this code that you don’t understand, have questions, or found an error, feel free to leave a comment. If you like this tutorial, be sure to share it on social media. If you really like this tutorial and would like to see more tutorials like this in the future, my “Tip Jar” is on the right.

Tutorials