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 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 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.