Upgrading Your Remote Pay SDK to Accommodate U.S. Credit Card Surcharging

Hi there 🙋🏻‍♀️.

If you’re a developer who has integrated with Clover’s Remote Pay SDK, you may be aware of the deprecation timelines we’ve sent recently. In that email, we shared that 1.x and 2.x versions of the Remote Pay SDKs have been superseded by the 3.x and 4.x versions.

You’re also probably aware that next month, November 2020, select merchants in the U.S. will have the option to enable credit card surcharges when they’re boarded onto Clover. In order to accommodate these merchants, we highly recommend upgrading to the 4.x version of the Remote Pay SDK (even if you have v3.x because the update allows for a more graceful handling of surcharges).

Clover handled receipts will print the surcharge automatically. For apps with custom receipts, or any merchant-facing screens or reports, in order to properly report the credit card surcharge, you’ll need to manually parse data from an object provided by the payment response called additionalCharges and format it to fit your needs.

Below is a simple list of steps on how to do this with Remote Pay iOS v4.0. Although the languages will differ, the same guidance can be applied to the rest of the SDKs.

1. Specify the values we need to display.

/*
**  POSAdditionalChargeAmount.swift
**  CloverConnector iOS Example
**
**  Copyright © 2020 Clover Network. All rights reserved.
*/
import Foundation
public class POSAdditionalChargeAmount {
    var id: String?
    var amount: Int?
    var rate: Int64?
    
    init(id: String?, amount: Int?, rate: Int64?) {
        self.id = id
        self.amount = amount
        self.rate = rate
    }
}

2. Parse the data from the any of the payment responses (sale, pre-auth, or auth).

/*
**  CloverConnectorListener.swift
**  CloverConnector iOS Example
**
**  Copyright © 2020 Clover Network. All rights reserved.
*/
...
// if the SaleResponse had additional charges, make sure they're translated to the POSPayment
if let additionalCharges = payment.additionalCharges?.elements {
    var posAdditionalCharges = [POSAdditionalChargeAmount]()
    
    for additionalCharge in additionalCharges {
        posAdditionalCharges.append(POSAdditionalChargeAmount(id: additionalCharge.id, amount: additionalCharge.amount, rate: additionalCharge.rate))
    }
posPayment.additionalCharges = posAdditionalCharges
}
...

3. Update what will be displayed on the orders screen.

/*
**  OrdersViewController.swift
**  CloverConnector iOS Example
**
**  Copyright © 2017 Clover Network, Inc. All rights reserved.
*/
...
cell.additionalChargesLabel.text = (CurrencyUtils.IntToFormat(order.getAdditionalChargeAmount()) ?? CurrencyUtils.FormatZero())
...

Click here to view the source code of this surcharge example. Here’s a demo of how it works¹:

Alright, that’s it for today. 💁🏻‍♀️ Please make sure to upgrade to the 4.x version and update your code before November 2020 if you haven’t already! If you run into any issues with upgrading, feel free to leave a comment here or contact us at developer-relations@devrel.clover.com.

¹Shout out to Daniel James, one of our awesome Mobile Developers here at Clover, for providing the example code and a demo of it. 🎉