Work with transaction data (Remote Pay SDKs)
Retrieve transaction information
Payment responses that the Clover device returns provide detailed transaction data for your application to use and display.
Understand surcharges (US and Canada only)
Note
The information in this section applies to Remote Pay SDKs version 4 and above. Earlier versions of the SDK provided surcharge data for Interac transactions, but this fee was combined with the order total into a single value as the response
amount
field. Integrations upgrading from version 3 need a code change to ensure proper handling of the now separate surcharge and transactionamount
values for Interac transactions.
Prerequisites
To work with surcharge data, your app must use the following minimum SDK version for your language/platform:
Surcharge data for a transaction
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.
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
.
{
"payment": {
"id": "2XPG4P9BK0WYP",
"order": {
"id": "7SBV9RRMT55AM"
},
"tender": {
"label": "Credit Card",
},
"amount": 5457,
"tipAmount": 0,
"taxAmount": 357,
"externalPaymentId": "C80J7Q7YXEME1",
"cardTransaction": {
"cardType": "DISCOVER",
"entryType": "SWIPED",
"last4": "6668",
"type": "AUTH",
"authCode": "590537",
"referenceId": "024500500420",
"transactionNo": "000041",
"state": "CLOSED",
"extra": {
"authorizingNetworkName": "DISCOVER",
"cvmResult": "NO_CVM_REQUIRED"
},
"cardholderName": "DEV KIT DISCOVER TESTCARD",
},
"additionalCharges": [
{
"id": "AGPT72N3N5TDM",
"amount": 190,
"rate": 35000,
"type": "CREDIT_SURCHARGE"
}
]
}
}
The transaction response includes an additionalCharges
object with the following information:
amount
—Number of cents paid as a surcharge on the credit card transaction.rate
—Percentage of the total used to calculate theamount
multiplied by 10000. A 3.5%rate
displays as35000
.type
—Additional charge type 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 debit or credit transaction processed using an alternative payment channel.INTERAC_V2
—Fixed amount added to Interac debit transactions.
Important
The total amount paid by the customer is the sum of the payment
amount
andadditionalCharges.amount
. In the example, the customer is charged $56.47 that is the $54.57amount
plus a 3.5% surcharge of $1.90.
Surcharge data for a refund and void
Surcharge 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": "SAWVHQD257AN4",
"order": {
"id": "N70SW85DW24VY"
},
"amount": 10470,
"tipAmount": 0,
"taxAmount": 31,
"result": "SUCCESS",
"additionalCharges": [
{
"id": "AGPT72N3N5TDM",
"amount": 336,
"rate": 35000,
"type": "CREDIT_SURCHARGE"
}
]
}
}
The response includes an additionalCharges
object with the following information:
amount
—Number of surcharged cents refunded or voided.rate
—Decimal percentage of the total used to calculate theamount
.type
—Charge 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 debit or credit transaction processed using an alternative payment channel.INTERAC_V2
—Fxed amount added to Interac debit transactions.
Tips and surcharging
A customer can add a tip to a payment in two ways—on the Clover device or on a paper receipt.
-
If a tip is added on the device, the
tipAmount
is added to the paymentamount
and then the sum is multiplied by the surchargerate
to determine the total charged to the customer's card. For example, if the orderamount
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
-
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 is declined. The customer needs to use another card or payment method to complete the transaction.
Updated 3 months ago