Handle voids and refunds (US region)
Information in this topic applies to US integrations because refund and void options differ between regions. See Region-specific features and limitations for more information.
Merchants often need the ability to void or refund a transaction, so the Remote Pay software development kits (SDKs) provide methods to start that process on a customer-facing Clover device connected to your point of sale (POS).
Transaction voids and refunds are of three types:
Transaction type | Corresponding CloverConnector method |
---|---|
Void | voidPayment |
Refund | refundPayment |
Manual refund | manualRefund |
In the following explanations, the sample code is from the Remote Pay Android Example POS and uses the following common code:
- An
ICloverConnector
that can accept chained method calls to agetCloverConnector()
call, which initiates the request. - A
store
object that sets the merchant context for retrieving settings before sending requests to the device.
Void
Voids undo two types of transactions—sales and pre-authorizations. A void cancels a sale, but the void must occur within 25 minutes of the original transaction. After that time elapses, the merchant can only refund the customer because the funding process has started. If a void is attempted after 25 minutes, Clover processes it as a refund. Voids are used by merchants in various businesses to correct mistakes or cancel a recent sale.
To void a payment, the VoidPaymentRequest
must reference a specific payment and order, and the reason to void the payment(USER_CANCEL
).
public void voidPayment(){
VoidPaymentRequest vpr = new VoidPaymentRequest();
vpr.setPaymentId(transaction.getId());
vpr.setOrderId(((POSPayment)transaction).getCloverOrderId());
vpr.setVoidReason("USER_CANCEL");
vpr.setDisableReceiptSelection(store.getDisableReceiptOptions() != null ? store.getDisableReceiptOptions() : false);
vpr.setDisablePrinting(store.getDisablePrinting() != null ? store.getDisablePrinting() : false);
Log.d(TAG, "VoidPaymentRequest: " + vpr.toString());
getCloverConnector().voidPayment(vpr);
}
Refund
A refund is a partial or complete repayment given to a customer for a specific order by calling refundPayment()
. For example, a retail customer may want to return an article of clothing that did not fit as expected.
Full refund
To completely refund a payment, set the fullRefund
field to true
. The RefundPaymentRequest
must also reference a specific payment and order.
public void makeFullRefund() {
RefundPaymentRequest refund = new RefundPaymentRequest();
refund.setPaymentId(transaction.getId());
refund.setOrderId(((POSPayment)transaction).getCloverOrderId());
refund.setFullRefund(true);
final ICloverConnector cloverConnector = cloverConnectorWeakReference.get();
Log.d(TAG, "RefundPaymentRequest - Full: " + refund.toString());
cloverConnector.refundPayment(refund);
}
Partial refund
To partially refund a payment, the RefundPaymentRequest
must also reference a specific payment and order. Then, set the fullRefund
field to false
, and set the amount
as the number of cents to be refunded.
public void makePartialRefund(long amount) {
RefundPaymentRequest refund = new RefundPaymentRequest();
refund.setAmount(amount);
refund.setPaymentId(transaction.getId());
refund.setOrderId(((POSPayment)transaction).getCloverOrderId());
refund.setFullRefund(false);
refund.setDisablePrinting(store.getDisablePrinting() != null ? store.getDisablePrinting() : false);
refund.setDisableReceiptSelection(store.getDisableReceiptOptions() != null ? store.getDisableReceiptOptions() : false);
final ICloverConnector cloverConnector = cloverConnectorWeakReference.get();
Log.d(TAG, "RefundPaymentRequest - Partial: " + refund.toString());
cloverConnector.refundPayment(refund);
}
Manual refund
If a merchant needs to refund a customer without tracking the refund against an order, the manualRefund()
method is used. This type of transaction is also referred to as a credit or naked refund.
Manual refunds can be for any amount
, and the request must include an externalPaymentId
to maintain a record of the refund between the POS and the Clover system. Manual refunds cannot be processed when the device is offline. See Tracking transactions with external IDs for more information.
Updated about 1 month ago