Skip to navigation
Online APIOrder Management

Create Refund

This endpoint performs a full or partial refund.

Note

The refund operation is idempotent if a unique requestId and merchantReference are provided.

Note

If using the Deferred Payment Flow, please be aware that only captured funds can be refunded.

Successful Response (201)

Returns a Refund object in response. All request parameters will be echoed in the response. In addition, the response includes the following:

AttributeTypeDescription
refundIdstringThe unique, permanent, Clearpay-generated Refund ID.
refundedAtstringThe UTC timestamp of when the refund was completed, in ISO 8601 format.

Connection Timeouts

TimeoutTime (Seconds)
Open10
Read70

Errors

In addition to the PUT/POST Errors applicable to all POST endpoints, the following errors are specific to Create Refund:

HTTP Status CodeerrorCodeDescription
412
Precondition Failed		precondition_failedThe orderId is invalid, does not exist, or is not eligible for a refund. For example, the order was declined.
422
Unprocessable Entity		invalid_objectThe refundMerchantReference exceeded 128 characters.
422
Unprocessable Entity		invalid_amountThe amount requested exceeded the amount available.
422
Unprocessable Entity		invalid_objectThe currency of the refund does not match the currency of the order (and the Merchant account).

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(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.