Work with transaction data (Clover Android SDK)
Retrieve transaction information
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 surcharges (US only)
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. If you are going to display transaction data in your app, you will need to use data from a few different fields. These features are available in Clover Android SDK version 262.2 and higher.
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
. You can also see the merchant's credit card surcharge rate in the value
field.
{
"id": "XV38MPKZKNE05",
"name": "Sandbox Supplies",
...
"programExpresses": {
"elements": [
{
"programCode": "5104",
"programCodeDescription": "MERCHANT SURCHARGE PROGRAM",
"key": "0001",
"keyDescription": "SURCHARGE RATE",
"value": "3.5"
}
]
}
}
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"
}
}
]
}
}
The response includes an additionalCharges
object showing the following:
amount
- the number of cents paid as a surcharge on the credit card transactionrate
- the percentage of the total used to calculate theamount
multiplied by 10000. A 3.5%rate
is represented as35000
.type
- the kind of additional charge processed for the transaction. At the time of this writing, this can be one of two values:CREDIT_SURCHARGE
- a percentage fee added to a credit card transaction to cover the cost of processingINTERAC_V2
- a fixed amount added to Interac debit transactions
payment
- contains the UUID of the associated payment
IMPORTANT
The total amount paid by the customer is the sum of the
amount
(includes bothtax
andadditionalCharges.amount
) and thetip
. In the example, the customer was charged $36.22 (the $35.00amount
plus a 3.5% surcharge of $1.22).
In the following example, you can see how the final amount of tipped credit card transaction can be calculated from the payment data.
final long getAmountWithTipWithAdditionalCharges() {
return getAmount() + getTipAmount() + getAdditionalChargeAmount();
}
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"
}
}
]
}
}
The response includes the following data:
orderRef.total
- the number of unrefunded cents remaining on the orderamount
- the number of cents refunded to the customerpayment.amount
- the number of cents originally paid for the orderadditionalCharges.elements.amount
- the number of surcharged cents refunded to the customeradditionalCharges.elements.rate
- the decimal percentage of the total used to calculate theamount
additionalCharges.elements.type
- the kind of additional charge processed for the transaction. At the time of this writing, this can be one of two values:CREDIT_SURCHARGE
, orINTERAC_V2
additionalCharges.elements.refund
- contains the UUID of the associated refund
In this example, the customer was refunded $15.00 of the original $35.00. Because they paid with a credit card, they are refunded an additional $0.52 of the original surcharge for a total refund of $15.52.
The total amount refunded to the customer is the sum of the refund
amount
andadditionalCharges.amount
. In the example, the customer was refunded $15.52 (the $15.00amount
plus a 3.5% surcharge refund of $0.52).
Tips and surcharge
There are two ways a customer can add a tip to a payment: on the Clover device or on a paper receipt. 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 will be charged an additional a 3.5% surcharge ($1.05) if they pay with a credit card.
(2500 + 500) * 1.035 = 3105
If a tip is added on paper, the tip is not included when calculating the surcharge.
Understand convenience fees
Merchants using 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 will need to use data from a few different fields to ensure proper reporting for these merchants.
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"
}
}
]
}
}
The response includes an additionalCharges
object showing the following:
amount
- the number of cents paid as a convenience fee on the transactiontype
- the kind of additional charge processed for the transaction (in this case,CONVENIENCE_FEE
)payment
- contains the UUID of the associated payment
IMPORTANT
The total amount paid by the customer is the sum of the payment
amount
andadditionalCharges.amount
. In the preceding example, the customer was charged $23.00 (the $20.00amount
plus a $3.00 convenience fee).
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"
}
}
]
}
}
The response includes the following data:
amount
- the number of cents refunded to the customeradditionalCharges.elements.amount
- the number of cents refunded to the customer originally charged as a convenience feeadditionalCharges.elements.type
- the kind of additional charge processed for the transaction (in this case,CONVENIENCE_FEE
)additionalCharges.elements.refund
- contains the UUID of the associated refund
IMPORTANT
The total amount refunded to the customer is the sum of the refund
amount
andadditionalCharges.amount
. In the example, the customer was refunded $18.50 (the $15.50amount
plus a $3.00 convenience fee).
Updated about 1 month ago