A void cancels a payment transaction before it is settled, while a refund is a repayment to the customer after the transaction is settled. Voids cancel the transaction entirely, whereas refunds return the money to the customer but keep a record of the transaction.

Refund payments

A refund is a repayment to the customer after the transaction has been settled. Refunds are used when a customer returns a product or cancels a service after the transaction has been processed. Refunds can be issued at any time after the transaction is settled. You can refund payments in different scenarios with the Ecommerce API.

Refund payments without order items to be returned

To refund a payment without any order items to be returned, send a POST request to the /v1/orders/{orderId}/returns endpoint. To use this endpoint, the order status value must be either Paid or Fulfilled.

In the following example, set the orderId for the order. Set the authorization: Bearer as your OAuth-generated access_token.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/orders/{orderId}/returns' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json'

In response, the refund status value is returned if the refund was successful.

Refund payments for returned order items

To refund a payment for order items that have been returned, send a POST request to the /v1/orders/{orderId}/returns endpoint, along with a list of the items returned.

In the following example, set items array values for each item returned. The parent (inventory or order line item ID), amount, and type values are required. To retrieve line item IDs associated with the order, send a GET request to /v3/merchants/{mId}/orders/{orderId}/line_items.

Set the authorization: Bearer as your OAuth-generated access_token.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/orders/{orderId}/returns' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"items":[{"parent":"{itemId}","amount":1800,
  "description":"Test item #1","quantity":1,"type":"sku"},
  {"parent":"{itemId}","amount":3000,
  "description":"Test item #2","quantity":1,"type":"sku"}]}'

In response, the refund status value is returned if the refund is successful.

Refund charges

Clover does not support manual refunds as an out-of-the-box feature for Ecommerce implementations. The Clover merchant needs to contact the relationship manager if interested in processing a manual refund for ecommerce transactions.

To refund a payment without any associated orders, create a refund by sending a POST request to the /v1/refunds endpoint. This endpoint can be used only to refund charges created with /v1/charges.

📘

NOTE

The /v1/refunds endpoint does not support partial refunds for charges that include taxes or tips or charges that have more than one line item.

You can partially refund payments created with /v1/orders/{orderId}/pay with the /v1/orders/{orderId}/returns endpoint.

In the following example, set the chargeID value of the payment to be refunded. Set the authorization: Bearer as your OAuth-generated access_token.

curl --request POST \
  --url 'https://scl-sandbox.dev.clover.com/v1/refunds' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"charge":"{charge_id}"}'

In response, the refund status value states whether the refund was successful succeeded or failed. If the merchant is set up for credit surcharging, the additional_charges object provides details of the surcharge for the original payment.

Void transactions

Merchants use voids to correct mistakes or cancel a recent sale. Voids undo two types of transactions—sales and pre-authorizations. A void applies to cancel a sale for 25 minutes of the original transaction. If a void is attempted after 25 minutes, Clover processes it as a refund.

To void a transaction:

1. Send a POST request to the /V2/merchant/{mId}/ecom/void endpoint.
2. Enter the required information—mId, paymentId and the reason as USER_CANCEL.
3. Set the authorization: Bearer as your OAuth-generated access_token.

curl --location 'https://apisandbox.dev.clover.com/v2/merchant/{mId}/ecom/void' \
--header 'Authorization: Bearer xx' \
--header 'Content-Type: application/json' \
--data '{
    "paymentId": "4RPZ729B5HCW0",
    "reason": "USER_CANCEL"
}'