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.

📘

NOTE

To use the /v1/orders/{orderId}/returns 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 header as your OAuth-generated access_token. See the API reference for more information about other values you can set.

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

Refund charges

To refund a payment without any associated orders, create a refund by sending a POST request to the /v1/refunds endpoint.

📘

NOTE

/v1/refunds can be used only to refund charges created with /v1/charges. 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 charge ID value of the payment to be refunded. Set the authorization' header 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.