Transaction data

United States
Canada
Europe
Latin America

Transaction data can be accessed 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:

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://sandbox.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://sandbox.dev.clover.com/v3/merchants/{mId}/default_service_charge \

The id returned by this request is required when your app adds 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, 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 be added from a third-party app. This requires the write orders permission.

Credit surcharge

A surcharge is a percentage of the order total collected to cover the merchant's cost of taking credit cards. Surcharges are only applied when the customer chooses to pay with a credit card; they are not added to debit, cash, or other forms of payments. Surcharge rules are set by the card networks, and there are also legal restrictions or prohibitions on them in some US states. Clover provides US merchants with the option to enable credit surcharging.

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:

Credit surcharges on the Clover platform

  • Merchant editable? No, the surcharge rate is configured by Clover when the merchant is boarded
  • 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 can be added to all transactions or just 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:

Interac surcharges on the Clover platform

  • Merchant editable? Yes, 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. See the Clover Credit Card Surcharging Policy for more information.

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 Virtual Terminal. In this case, 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:

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