Retrieve transaction information

Payment responses that the Clover device returns provide detailed transaction data for your application to use and display.

Understand 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%.

View surcharge for transactions

To display transaction data in your app, you need to use data from different fields. The surcharge data for a transaction is reported in the PaymentResponse.payment.additionalCharges object, where PaymentResponse is one of the following—SaleResponse, AuthResponse, or PreAuthResponse.

Request

{
  "success": true,
  "result": "SUCCESS",
  "payment": {
    "id": "WSPDBEE2RKSEA",
    "result": "SUCCESS",
    "order": {
      "id": "88KCNJ7CS3JN4"
    },
    "amount": 2428,
    "createdTime": 1599672721991,
    "additionalCharges": {
      "elements": [
        {
          "amount": 84,
          "type": "CREDIT_SURCHARGE",
          "id": "AGPT72N3N5TDM",
          "rate": 35000,
          "payment": {"id": "WSPDBEE2RKSEA"}
        }
      ]
    }
  },
  "isSale": true
}

Response

The response includes an additionalCharges object with the following information:

The total amount paid by the customer is the sum of the payment amount and additionalCharges.amount. In the example, the customer is charged $25.12, that is the $24.28 amount plus a 3.5% surcharge of $0.84.

View surcharge for a refund and void

The surcharge data for a transaction is reported in the RefundPaymentResponse.refund.additionalCharges or VoidPaymentResponse.payment.additionalCharges object.

Request

{
  "success": true,
  "result": "SUCCESS",
  "reason": "voidSent",
  "message": "No extended information provided.",
  "payment": {
    "id": "SPLHGTD25ALN4",
    "order": {
      "id": "N70SW8KUW28VY"
    },
    "amount": 2130,
    "tipAmount": 0,
    "taxAmount": 0,
    "result": "SUCCESS",
    "additionalCharges": [
      {
        "amount": 74,
        "type": "CREDIT_SURCHARGE",
        "id": "KHGT70N3N5SSD",
        "rate": 35000,
        "payment": {"id": "SPLHGTD25ALN4"}
        
      }
    ]
  }
}

Response

The response includes an additionalCharges object with the following information:

Surcharge and tips

A customer can add a tip to a payment in two ways:

• On the Clover device—If a customer adds a tip on the device, the tipAmount is added to the payment amount and then the sum is multiplied by the surcharge rate to determine the total charged to the customer's card. For example, if the order amount is $25.00, and the customer adds a 20% tip ($5). If they pay with a credit card, they are charged an additional 3.5% surcharge ($1.05).
  Total amount = (2500 + 500) * 1.035 = 3105

• On a paper receipt—If a customer adds a tip on a paper receipt, the tip is not included when calculating the surcharge.

Surcharge and partial authorizations

If a surcharged credit card payment results in a partial authorization, the entire transaction is declined. The customer needs to use another card or payment method to complete the transaction.