The UUID is a 13 character alphanumerical string with letters in all caps that represents the resource internally with Clover for Merchant, Employee, App, Order, Item, Tax, Payment, Refund, etc.

Clover has a tendency to mix IDs and UUIDs and call them both IDs in their own interface and documentation.

Merchants have both a Clover Merchant UUID (13 character alphanumerical) and a Clover Merchant ID (20* digits). Clover calls both of these "Merchant ID".

For the sake of the clarity of this documentation, for the UUID we will always be refering to the 13 digit alphanumerical values unless explicitly specified.

In the scope of this documentation, the Clover Employee is the logged in user. A Clover Employee is a resource with a relation to the Merchant being worked with.

It can be the merchant Owner or one of its admins, it still remains a Clover Employee resource.

In the scope of this documentation, the Clover Merchant is the resource representing a business or franchise within Clover. Some businesses have a single Clover Merchant set up for multiple locations and some have individual Clover Merchants set up for each location.

The Merchant is not the primary resource that represents a user. A user(Clover Employee) has privilege levels to a merchant (such as employee, admin or owner – and the permissions inside can be edited) but is never permanently linked to it. The owner can change, the employee can get fired and kicked out. Employees can also have certain permissions revoked. This can lead to situations where an API key is invalidated. Plan accordingly.

In the scope of this documentation, the Clover App is what an integration type (such as WooCommerce) will use to act on behalf of the Clover Merchant.

Each integrator has their own App.

The Clover Merchant must authorize the permissions asked for by the Clover App in order for the Clover App to act on their behalf. Should the app be uninstalled through the Clover Market, all API keys will be invalidated.

In the scope of this documentation, the Clover PAKMS key represents the public key to use in the front-end to tokenize the credit card. This key does not represent a session. It represents a relation between 2 models:

The key will always stay the same for each set of Clover App + Clover Merchant within an environment.

In the scope of this documentation, the Clover API Key represents a session (valid or not) with some contextual data.

An API key is given at the end of the user authentication and the previous key for the same set of Clover App + Clover Merchant + Clover Employee is instantly invalidated.

Since the authentication is done through WeeConnectPay, we take care of creating the API keys and soft-deleting/invalidating the old API keys as they are generated. This means that as long as you use our API, you will not have to worry about keeping track of which Clover API key is active, it will simply use the active one every time.

This key should never be exposed.

Every time a call to the Clover API is made, the authorization for each of the related models is verified.

Rate limits are set for the number of new API requests your apps can make per second.

In addition to rate limiting, we maintain concurrent rate limiting to better control multiple retry requests to CPU-intensive API endpoints. Concurrent rate limits are set for the number of in-progress API requests your apps can make at the same time.

For instance, if the concurrent rate limit has been set to five, you can make up to five running API requests at the same time. While the server is responding to these five requests, a sixth request will return to a 429 HTTP Too Many Requests error message.

Those rate limits can be increased through us with a request to Clover.

The rate limits for API Keys manually generated in the Clover Merchant dashboard are MUCH lower than what is documented.

Work with API usage and rate limits

In the scope of this documentation, the Clover Order is a resource that represents an order. The order is left in an “open” status until it is either paid, partially paid(unsupported in ecommerce), refunded, partially refunded or cancelled/closed.

The Clover Order belongs to the Clover Merchant. It also is related to the Clover Employee that entered it, but any Clover Employee with sufficient rights can pay or refund it as long as they have access to those permissions within the merchant it belongs to.

A Clover order can have zero or more items.

There is a new way to make orders that gives us a lot more flexibility, including custom tax support that is one of our priorities on our road map.

In the scope of this documentation, the Clover Item is an item with a set quantity, price per unit. Clover Items can be used from the Clover Merchant’s inventory by using the Clover Item UUID, or the UUID can be left blank and a UUID will be given to it and it will be considered a custom item.

In the scope of this documentation, the Clover Tax is a set tax predefined in the Clover Merchant dashboard (or added through the API). It can be left blank on orders to set it as “tax included” or defined by a Clover Tax Rate UUID, a Tax Rate Amount + Tax Rate Name or Tax Rate Percentage + Tax Rate Name.

The Tax Rate UUID and the combinations of Tax Rate Amount/Percentage + Tax Rate Name need to match a Tax Rate that already exists in the Clover Merchant account before using them

There has been quite a lot of changes over the year related to taxes. The previous limitations for ecommerce that need to support dynamic taxes led us to create our items with tax included in our current integrations. This is something on our priority list.

In the scope of this documentation, the Clover Payment is the resource that represents a payment to a Clover Order.

Clover Refunds are a way to partially or totally refund a Clover Payment.

Payments are refundable, but it will not reflect on the invoice what was refunded if done this way. Should you want to have a returned item reflected for the merchant, you should instead use Clover Returns by returning items being refunded.

Clover Returns is very similar to Clover Refund. It does not seem to have its own model within the Clover Model structure as it creates a Clover Refund. The key difference here is that a Clover Return is linked to a Clover Order instead of a Clover Payment like the Clover Refund normally is.
​
This means that, when using the Clover Return, the Clover Order will know and will display to the customer and merchant which item was refunded.

There is currently a bug in the Clover API preventing partial refunds of single items. We are closely working with the Clover engineering team to get this sorted fast.

Used for testing, development and anything that is not ready for production.

An integration is the central model used to connect WeeConnectPay to an external service. It allows to preserve the Clover relational context using a unique ID (UUIDv4 format).

Each integration has a type and a back-end. Those 2 relations are polymorphic to their own tables. For example; the WooCommerce integrations have an integration type of woocommerce and an integration back-end of wordpress.

In the scope of this documentation, when we refer to an integration, we do not mean the integration type, but rather the individual unique integration represented by a UUID (IE: A single WooCommerce instance on a specific website).

We will work with integrators to add the tables for their own integration type and integration back-end to allow WeeConnectPay to find or create unique integrations when pre-authenticating.

Our API Key is a JWT. We do not store the API Key for security reason, we can only generate and validate them. The JWT has custom claims that shows what it represents :

If there is a reasonable need for it that cannot be satisfied otherwise, more JWT custom claims could be added for integrators.

This key should never be exposed as it allows the full range of permissions of the authorized Clover App over the Clover Merchant it represents.

Each API Call done to our API on authenticated endpoints will automatically use the context of the data in the JWT to interact with our models and the Clover API for the requested actions if there is any.

Mostly for use by WeeConnectPay.

WeeConnectPay currently only authenticates integrations of the WooCommerce type. However, we build the API in a way that allows it to support all types of integrations with very few changes.

The terms we will be referring to here are Integration type which is the platform being integrated. In our examples it will be WooCommerce. When we mention an Integration we really refer to the unique instance of WooCommerce we are using the API with. In other words, a single online ecommerce shop.

That chart shows the Pre-authentication and Authentication for WooCommerce

Every integration has its own Integration ID with WeeConnectPay. An Integration ID is a UUIDv4 value that represents a unique instance of an Integration. To authenticate with WeeConnectPay, you need an Integration ID for each unique instance you are authenticating with.

The one thing that will change here for upcoming integrations is the unique values that determine what is a unique instance of an Integration. For WooCommerce it is the wpdb and site_url values of the wordpress instance hosting the WooCommerce being worked with.

For WooCommerce, this logic happens when activating the plugin, as well as when the authentication page is loaded.

This allows us to validate that the authentication is still valid or has not expired.

We use OAuth2 with Clover to authenticate merchants. The authentication flow is as follows.

If the browser does not already have a valid active session in the specific Clover Environment

Only a merchant Admin can authorize a Clover App to act on their behalf. We have no way to check for permissions at this point as the Clover Employee is not done authenticating.

Context data (including Integration ID) is passed as a URL query in the link.

If the browser does not already have a valid active session in the specific Clover Environment.

Only a merchant Admin can authorize a Clover App to act on their behalf. We have no way to check for permissions at this point as the Clover Employee is not done authenticating.

By default Clover Employee has only one Clover Merchant or the Clover Merchant UUID was passed as a parameter or by user interaction.

We obtain a Clover API token valid for 1 year with this.

We will make the switch to refresh token eventually.

This builds all the Clover relational data needed to work with the Clover API using only the Integration ID.

The most important part here is the WeeConnectPay API key. A JWT token that contains custom claims that identify the token as belonging to a specific merchant, employee, app and integration id.

This can help prevent user errors during re-authentications.

Please let us know if you would like to pass more information from the beginning of the flow to the callback at the end. We can customize the call for your integration type to allow for specific values to be passed.

That schema explain the WooConnectPay backend relations used for integration

The employee logging in can change, but only the merchant that has logged in can log in the integration afterwards.

We have a procedure in place to unlink the relationship between the integration and the merchant to let another merchant log in if it is a human error. For example. the Clover Employee logged his West Edmonton location on the Calgary website by mistake.

Since we do not store a lot of data other than the Clover UUIDs required for linking data during API calls to Clover, a lot of the Authorization is done by the Clover Merchant on the Clover Dashboard.

From there, they can decide who is allowed to do what. Since there is a lot of granularity here, we opted for simplicity and do the API calls to Clover and rely on Clover to tell us if a call is unauthorized. If it is the case, it will be logged using Sentry and we can tackle the issue as it comes up.

Should there be any scenario you can reproduce in the sandbox where this is problematic, we will be happy to adapt. Sentry is also set up for the sandbox environment for testing purposes.

We store the read and write permissions for the Clover API keys and as such can be used to expand the current authorization protocols should there be any need. See https://weeconnectpay.atlassian.net/wiki/spaces/WCP/pages/261816325

This section reflects the WooCommerce type integration. WooCommerce has its own way of doing things and is highly customizable. As such, by doing an integration in your own systems, a lot of this information may not be relevant. I will do my best to highlight the bare minimum that always apply regardless of the integration type.

The current implementation of WooCommerce does the checkout process in 3 steps:

Each subsequent step uses IDs from the previous one. IE: A Clover Order is created with a Clover Customer UUID, a Clover Payment is created with the resulting Clover Order UUID we receive from creating it and a tokenized card.

Clover Customer Creation

Minimum requirements:

A Clover Customer UUID will be received when creating one.

There is little incentive to keeping track of Clover Customers as Clover will automatically merge customers on their end to keep a relevant customer purchase history, even if they change email or change credit card. The important part here is to have the Clover Customer UUID ready when creating the Clover Order.

Clover Order Creation

Minimum requirements:

Conditional requirements:

Due to limitations of the Clover API when we built WeeConnectPay for WooCommerce, each item is set to the amount of 1. This was a workaround for a previous lack of support for dynamic taxes. This has changed and is not recommended for any future integration as this workaround is no longer needed. Please talk to our lead developer about more information regarding this previous design choice. It is well documented internally.

Minimum requirements: