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.

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.

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.