Using the Clover Android SDK, your app can retrieve and display detailed transaction data. At a minimum, your application needs the read payments permission to access these endpoints. If your app will allow the merchant to update payment or authorization data, your app must also request permission to write payments.

Understand credit card surcharge

The credit card surcharge feature is available in Clover Android SDK version 262.2 and higher.

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

If you display transaction data in your app, you must include data from a few fields. To check if a merchant is set up for surcharging, use the Merchant.getProgramExpresses() method. In the response, check for the programCode value of 5104 for US merchants and 5239 for Canada merchants. You can also see the merchant's credit card surcharge rate in the value field.

View transaction data and surcharge

{
  "id": "XV38MPKZKNE05",
  "name": "Sandbox Supplies",
  ...
  "programExpresses": {
    "elements": [
      {
        "programCode": "5104",
        "programCodeDescription": "MERCHANT SURCHARGE PROGRAM",
        "key": "0001",
        "keyDescription": "SURCHARGE RATE",
        "value": "3.5"
      }
    ]
  }
}

Request

To retrieve the surcharge data for a transaction, use the Payment.getAdditonalCharges() method.

{
  "id": "RCFSJ33GPYM3D",
  "amount": 3500,
  ...
  "additionalCharges": {
    "elements": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 122,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE",
        "payment": {
          "id": "RCFSJ33GPYM3D"
        }
      }
    ]
  }
}

Response

The response includes an additionalCharges object with the following information:

The total amount paid by the customer is the sum of the amount (includes both tax and additionalCharges.amount) and the tip. In the example, the customer was charged $36.22, which is the $35.00 amount plus a 3.5% surcharge of $1.22.

View payment data and surcharge

In the following example, you can see how the final amount of a tipped credit card transaction can be calculated from the payment data.

final long getAmountWithTipWithAdditionalCharges() {
  return getAmount() + getTipAmount() + getAdditionalChargeAmount();
}

Request

To retrieve the surcharge data for a transaction, use the Refund.getAdditonalCharges() method.

{
  "id": "JRWNWS4Y7SSTP",
  "orderRef": {
    "id": "KTRPNSER0FA5W",
    "total": 2000
  },
  "amount": 1500,
  "payment": {
    "id": "ZV67XE59NGF1Y"
    "amount": 3500,
  },
  "additionalCharges": {
    "elements": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 52,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE",
        "refund": {
          "id": "JRWNWS4Y7SSTP"
        }
      }
    ]
  }
}

Response

The response includes the following data:

The total amount refunded to the customer is the sum of the refund amount and additionalCharges.amount. In this example, the customer was refunded $15.00 of the original $35.00. The customer paid with a credit card, so was refunded an additional $0.52 of the original surcharge for a total refund of $15.52.

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.

Understand convenience fees

Merchants using the Virtual Terminal as an alternative payment channel can collect a fixed amount convenience fee. If you are going to display transaction data in your app, you need to provide data from a few fields to ensure proper reporting for these merchants.

View convenience fee for a paid transaction

Request

To view the convenience fee collected for a transaction, use the Payment.getAdditonalCharges() method.

{
  "id": "MERQ5J3KFETNY",
  "amount": 2000,
  ...
  "additionalCharges": {
    "elements": [
      {
        "id": "3NTR8H89C1D8M",
        "amount": 300,
        "type": "CONVENIENCE_FEE",
        "payment": {
          "id": "MERQ5J3KFETNY"
        }
      }
    ]
  }
}

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 preceding example, the customer was charged $23.00, that is the $20.00 amount plus a $3.00 convenience fee.

View convenience fee for a refund transaction

Request

To get the convenience fee data for a refund, use the Refund.getAdditonalCharges() method.

{
  "id": "CY3XR7R6D9B3P",
  "amount": 1550,
  "additionalCharges": {
    "elements": [
      {
        "id": "12DB2D19N2SXE",
        "amount": 300,
        "type": "CONVENIENCE_FEE",
        "refund": {
          "id": "CY3XR7R6D9B3P"
        }
      }
    ]
  }
}

Response

The response includes the following information:

The total amount refunded to the customer is the sum of the refund amount and additionalCharges.amount. In the example, the customer was refunded $18.50. The refunded amount includes the $15.50 amount plus a $3.00 convenience fee.