Handle voids and refunds

United States
Canada
Europe
Latin America

Merchants often need to void or refund a transaction. 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 typeCorresponding CloverConnector method
VoidvoidPayment
RefundrefundPayment
Manual refundmanualRefund

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 a getCloverConnector() call, which initiates the request.
  • A store object that sets the merchant context for retrieving settings before sending requests to the device.

Void

Voids are used by merchants in various businesses to correct mistakes or cancel a recent sale. 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.

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 Track transactions with external IDs for more information.

Manual refunds are not supported in Latin America (LATAM).