Use Payment Connector for surcharging

United States
Canada
Latin America

Retrieve transaction information

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

Understand surcharges

Some merchants are configured to add a surcharge to all credit card transactions they process. This surcharge is a set percentage of the post-tax order total. To display transaction data in your app, you need to use data from different fields.

Surcharge for transactions

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.

{
  "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
}

The transaction response includes an additionalCharges object with the following information:

ResponseDescription
amountNumber of cents paid as a surcharge on the credit card transaction.
ratePercentage of the total used to calculate the amount multiplied by 10000. A 3.5% rate displays as 35000.
typeAdditional charge processed for the transaction.
Values:
- CREDIT_SURCHARGE— Percentage fee added to a credit card transaction to cover the cost of processing.
- CONVENIENCE_FEE— Fixed amount added to a credit or debit transaction processed using an alternative payment channel.
- INTERAC_V2— Fixed amount added to Interac debit transactions.
paymentUniversal unique identifier (UUID) of the associated payment.

🚧

Important

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.

Surcharge for a refund and void

This expansion can also be used for refunds and voids. The surcharge data for a transaction is reported in the RefundPaymentResponse.refund.additionalCharges or VoidPaymentResponse.payment.additionalCharges object.

{
  "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"}
        
      }
    ]
  }
}

The response includes an additionalCharges object with the following information:

ResponseDescription
amountNumber of surcharged cents refunded or voided.
rateDecimal percentage of the total used to calculate the amount.
typeCharge type added to the original payment.
Values:
- CREDIT_SURCHARGE— Percentage fee added to a credit card transaction to cover the cost of processing.
- CONVENIENCE_FEE— Fixed amount added to a credit or debit transaction processed using an alternative payment channel.
- INTERAC_V2— Fixed amount added to Interac debit transactions
paymentUniversal unique identifier (UUID) of the associated payment.

Surcharge and tips

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

  • On a Clover device—If a tip is added 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), they are charged an additional a 3.5% surcharge ($1.05) if they pay with a credit card.
    Total amount =(2500 + 500) * 1.035 = 3105

  • On a paper receipt—If a tip is added on paper, 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.