You can access transaction data using the Android SDK, the Platform and Ecommerce REST APIs, or in the responses to CloverConnector or PaymentConnector calls for integrated POS systems.

For more information, see the section for the Clover SDK you are building with:

• Android
• REST API
• Remote Pay SDKs
• Payment Connector

Charges and fees

The Clover platform provides merchants the ability to configure different types of customer fees. These fees are collected for specific reasons and vary in how they are set up and used.

Service charge

A service charge is an additional amount the merchant can collect for reasons like delivering food to the customer's home or accommodating a large party at a restaurant. Third-party apps interact with service charges in a few ways. An app can see the service charge for orders or payments by adding the serviceCharge expansion to the request URL.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?expand=serviceCharge' \

To add a service charge to an order, the app must first retrieve the merchant's default service charge:

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{mId}/default_service_charge' \

Your app needs the id that this request returns to add a service charge to an order using the /v3/merchants/mId/orders/orderId/service_charge endpoint.

{
    "id": "{{serviceChargeId}}",
    "name": "Delivery fee",
    "enabled": true,
    "percentageDecimal": 50000
}

Service charges on the Clover platform

• Merchant editable? Yes, it is configured in the Setup app as a percentage of the order total.
• API read access? Yes, using the GET /v3/payments endpoint with the serviceCharge expansion field. This returns the service charge taken for the individual payment.
• API write access? Yes, a service charge can be added from a third-party app. Requires permission to write orders.

Credit card surcharge

A credit card surcharge is a percentage of the post-tax order total collected to partially or fully cover the merchant's costs associated with processing credit card payments. Some merchants are configured to add a surcharge to eligible credit BIN credit card transactions they process. Surcharges are only applied when the customer pays with an eligible credit BIN credit card; they are not added to debit, cash, or other forms of payment. Surcharge rules are set by the card networks.

Clover onboards merchants for credit card surcharging in the following countries:

• Canada, excluding Quebec
• United States, excluding states with legal restrictions or prohibitions

Canada uses a flat 2.40% credit card surcharge rate, while in the US, the surcharge can vary by merchant, with most US merchants having a surcharge of 3.00%.

Third-party apps interact with surcharging data if they display transaction information to the merchant or customer. For example, your app may include a web dashboard showing daily order totals or print custom receipts as part of a semi-integrated POS system. To accurately report a transaction's total when a surcharge is collected, your app needs to use the data as described in these sections:

• Android
• REST API
• Remote Pay SDKs

Credit surcharges on the Clover platform

• Merchant editable? No, Clover configures the surcharge rate when the merchant is onboarded.
• API read access? Yes, using the GET /v3/payments endpoint with the additionalCharges expansion field
• API write access? No, third-party apps are not allowed to add surcharges. See the Clover Credit Card Surcharging Policy for more information.

Interac surcharge

An Interac surcharge is an optional fee a merchant can collect when a customer pays with an Interac debit card. The surcharge is a fixed amount that a merchant can add to all transactions or to those where the customer requests cash back.

📘

NOTE

Interac surcharges are handled differently in the 3.x and 4.x versions of the Remote Pay SDKs. This page describes the behavior of version 3.x

Third-party apps may need Interac surcharging data if they display transaction information to the merchant or customer. For example, your app may include a web dashboard showing daily order totals or print custom receipts as part of a semi-integrated POS system. To accurately report a transaction's total when a surcharge is collected, your app needs to use the data as described in these sections:

• Android
• REST API
• Remote Pay SDKs

Interac surcharges on the Clover platform

• Merchant editable? Yes, it is configured in the Setup app as a fixed amount.
• API read access? Yes, using the GET /v3/payments endpoint with the additionalCharges expansion field
• API write access? No, third-party apps are not allowed to add surcharges.

Convenience fee

A convenience fee is a fixed amount collected from the customer for the bonafide convenience of using an alternative payment channel outside of the merchant's customary payment channels. Some Clover merchants collect a convenience fee if they take a payment over the phone and enter the card information into the Virtual Terminal. In this case, the Virtual Terminal is the alternative to a physical Clover device at the merchant's business.

Third-party apps interact with convenience fee data if they display transaction information to the merchant or customer. For example, your app may include a web dashboard showing daily order totals or print custom receipts as part of a semi-integrated POS system. To accurately report a transaction's total when a fee is collected, your app needs to use the data as described in these sections:

• Android
• REST API
• Remote Pay SDKs

Convenience fees on the Clover platform

• Merchant editable? Yes
• API read access? Yes, using the GET /v3/payments endpoint with the additionalCharges expansion field
• API write access? No, third-party apps are not allowed to add fees.