Online APIOrder Management

Create Refund

This endpoint performs a full or partial refund. <Note title="Note"> The refund operation is [idempotent](/idempotent-requests) if a unique `requestId` and `merchantReference` are provided. </Note> <Note title="Note"> If using the [Deferred Payment Flow](/deferred-payment-flow), please be aware that only captured funds can be refunded. </Note> ## Successful Response (201) Returns a [Refund object](/refund-object) in response. All request parameters will be echoed in the response. In addition, the response includes the following: | Attribute | Type | Description | | :----------- | :----- | :--------------------------------------------------------------------------------------------------------------------------- | | `refundId` | string | The unique, permanent, Clearpay-generated Refund ID. | | `refundedAt` | string | The UTC timestamp of when the refund was completed, in [ISO 8601](http://www.iso.org/iso/home/standards/iso8601.htm) format. | ## Connection Timeouts | Timeout | Time (Seconds) | | :------ | :------------- | | Open | 10 | | Read | 70 | ## Errors In addition to the [PUT/POST Errors](/put-post-errors) applicable to all POST endpoints, the following errors are specific to Create Refund: | HTTP Status Code | errorCode | Description | | :-- | :-- | :-- | | **412** <br />Precondition Failed | `precondition_failed` | The `orderId` is invalid, does not exist, or is not eligible for a refund. For example, the order was declined. | | **422** <br />Unprocessable Entity | `invalid_object` | The `refundMerchantReference` exceeded 128 characters. | | **422** <br />Unprocessable Entity | `invalid_amount` | The `amount` requested exceeded the amount available. | | **422** <br />Unprocessable Entity | `invalid_object` | The currency of the refund does not match the currency of the order (and the Merchant account). |

Authentication

AuthorizationBasic

Basic authentication of the form Basic <username:password>.

Path parameters

orderIdstringRequired
The unique Clearpay Order ID to apply the refund to.

Headers

User-AgentstringRequired
AcceptstringOptionalDefaults to application/json

Request

This endpoint expects an object.
amountobjectRequired
The refund amount. The refund amount can not exceed the payment total.
requestIdstringOptional
A unique request ID, required for safe retries. It is recommended that the merchant generate a UUID for each unique refund.
merchantReferencestringOptional

The merchant’s internal refund id/reference. This must be included along with the requestId to utilise idempotency. Max length 85 (varchar)

refundMerchantReferencestringOptional
A unique reference for the individual refund event. If provided, the value will appear in the daily settlement file as "Payment Event ID". Limited to 128 characters.