Working with transaction data (Payment Connector)
Retrieving transaction information
The payment responses returned by the Clover device provide detailed transaction data for your application to use and display.
Understanding 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.
PaymentResponse.payment.additionalCharges
object (where PaymentResponse
can be a 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 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 three values:CREDIT_SURCHARGE
- a percentage fee added to a credit card transaction to cover the cost of processingCONVENIENCE_FEE
- a fixed amount added to a debit or credit transaction processed using an alternative payment channelINTERAC_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 payment
amount
andadditionalCharges.amount
. In the example, the customer was charged $25.12 (the $24.28amount
plus a 3.5% surcharge of $0.84).
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 showing the following:
amount
- the number of surcharged cents refunded or voidedrate
- the decimal percentage of the total used to calculate theamount
type
- the kind of charge added to the original payment. At the time of this writing, this can be one of three values:CREDIT_SURCHARGE
,CONVENIENCE_FEE
, orINTERAC_V2
payment
- contains the UUID of the associated payment
Tips and surcharging
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.
Partial authorizations and surcharging
If a surcharged credit card payment results in a partial authorization, the entire transaction will be declined. The customer will need to use another card or payment method to complete the transaction.
Updated over 1 year ago