Clover uses the OAuth 2.0 security framework for third-party developers to authenticate their apps with merchant accounts and lets them use Clover public REST APIs on behalf of the merchant.

Use API tokens for testing in sandbox

When you test your app in the sandbox environment, you can generate and use API tokens instead of access and refresh tokens that you need in the production environment. You can use the API token to test Clover REST APIs from the command line.

Prerequisites

When you make server-side requests to Clover REST APIs, you need the following:

• Authorization header with a type of Bearer token token, where you need to enter your {API_Token}.
• Merchant identifier or merchantId that displays in the browser link (URL) of the Merchant Dashboard for your test merchant.

With this information, you can send the following request from your app server to the Clover server.

https://apisandbox.dev.clover.com/v3/merchants/{mId}

See Use test merchant identifier and API token for more information.

Sample REST API requests

To test Clover REST APIs:

1. Set the Authorization header as Bearer token type, and enter the auth_token.
2. Include the merchantId in the request URL in place of {mId}.

To retrieve information about your test merchant, send a GET request to /v3/merchants/mId:

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'

In this request,

• mId is the test merchant's universally unique identifier (UUID), also known as the merchantId
• auth_token is the test API token or access token. See Use test merchant IDs and API tokens for more information.

To update your test merchant's name, send a POST request to /v3/merchants/mId:

curl --request POST \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'
  --data '{"name":"{updated_merchant_name}"}'

Set additional query parameters

To retrieve more information from your REST API requests, set query parameters for supported endpoints in the following format.

[Endpoint URI]?field=value[,additionalValues...]&[additionalQueryParameters...]

In the API documentation, the Query Params section lists the additional parameters available. For example, use the expand query parameter for additional information about a merchant.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}?expand=openingHours' \
  --header 'accept: application/json' \  
  --header 'authorization: Bearer {auth_token}'

See Use expandable fields for more information.

📘

NOTE

You need to use expiring access and refresh tokens in the production environment to secure merchant data. When your app is ready for testing in the production environment, use the following.

• For Web apps: Use the relevant OAuth flow based on regions to generate an auth_token.
• For Android apps: Use the Android SDK to generate an API token and query web services.