Create Refund

POST

/v2/payments/:orderId/refund

This endpoint performs a full or partial refund. The refund operation is idempotent if a unique `requestId` and `merchantReference` are provided. If using the [Deferred Payment Flow](../docs/API-DEVELOPMENT/2b.-Auth-and-Capture.md), please be aware that only captured funds can be refunded. Don't create refunds after 120 days from the date of purchase. **Connection Timeouts** | Timeout | Time (Seconds) | |---------|----------------| | Open | 10 | | Read | 70 |

Create Refund

POST

/v2/payments/:orderId/refund

This endpoint performs a full or partial refund. The refund operation is idempotent if a unique requestId and merchantReference are provided.

If using the Deferred Payment Flow, please be aware that only captured funds can be refunded. Don’t create refunds after 120 days from the date of purchase.

Connection Timeouts

Timeout	Time (Seconds)
Open	10
Read	70

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Path parameters

orderIdstringRequired

The unique Afterpay Order ID to apply the refund to.

Request

This endpoint expects an object.

requestIdstringOptional

Unique ID required for safe retries. Max length 64 (varchar).

amountobjectOptional

Object containing amount and currency.

Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a 422 Unprocessable Entity response. The following is a list of common examples:

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

merchantReferencestringOptional

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

refundMerchantReferencestringOptional<=128 characters

A unique reference for the individual refund event. Max length 128 (varchar).

Response

Returns a 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, Afterpay-generated Refund ID. | | `refundedAt` | string | The UTC timestamp of when the refund was completed, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. |

amountobject

Object containing amount and currency.

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

merchantReferencestring

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

refundIdstringRead-only

The unique, permanent, Afterpay-generated Refund ID.

refundMerchantReferencestring<=128 characters

A unique reference for the individual refund event. Max length 128 (varchar).

refundedAtstringRead-only

requestIdstring

Unique ID required for safe retries. Max length 64 (varchar).

Errors

412

Precondition Failed Error

422

Unprocessable Entity Error

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Path parameters

orderIdstringRequired

The unique Afterpay Order ID to apply the refund to.

Request

This endpoint expects an object.

requestIdstringOptional

Unique ID required for safe retries. Max length 64 (varchar).

amountobjectOptional

Object containing amount and currency.

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

merchantReferencestringOptional

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

refundMerchantReferencestringOptional<=128 characters

A unique reference for the individual refund event. Max length 128 (varchar).

Response

Returns a 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, Afterpay-generated Refund ID.
`refundedAt`	string	The UTC timestamp of when the refund was completed, in ISO 8601 format.

amountobject

Object containing amount and currency.

Example	errorCode	message
`amount` is omitted or null	invalid_object	{Money object}.amount Amount field required
`amount` has more than 2 decimal places	invalid_object amount	must be a valid ISO 4217 format value
`amount` includes a thousands separator comma, for example: “1,000”	invalid_amount	Amount must be a valid ISO 4217 format value
`amount` is not a decimal number, for example: “FREE”, “$2” or an empty string	invalid_object	{Money object}.amount Amount field must be a valid ISO 4217 format value
`currency` is omitted or null	invalid_object	{Money object}.currency Currency field required
`currency` is not a valid currency code, not all uppercase or an empty string	invalid_object	{Money object}.currency Currency not supported for this merchant
`currency` is supported by Afterpay, but not valid for the Merchant account	unsupported_currency	An error occurred

merchantReferencestring

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

refundIdstringRead-only

The unique, permanent, Afterpay-generated Refund ID.

refundMerchantReferencestring<=128 characters

A unique reference for the individual refund event. Max length 128 (varchar).

refundedAtstringRead-only

requestIdstring

Unique ID required for safe retries. Max length 64 (varchar).

Errors

412

Precondition Failed Error

422

Unprocessable Entity Error

$	curl -X POST https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund \
>	-H "User-Agent: User-Agent" \
>	-H "Content-Type: application/json" \
>	-u "<username>:<password>" \
>	-d '{
>	"requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a",
>	"amount": {
>	"amount": "10.00",
>	"currency": "AUD"
>	},
>	"merchantReference": "merchantRefundId-1234",
>	"refundMerchantReference": "merchantRefundId-1234"
>	}'

1	{
2	"amount": {
3	"amount": "10.00",
4	"currency": "AUD"
5	},
6	"merchantReference": "merchantRefundId-1234",
7	"refundId": "67890123",
8	"refundMerchantReference": "merchantRefundId-1234",
9	"refundedAt": "2023-01-01T00:00:00.000Z",
10	"requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a"
11	}

$	curl -X POST https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund \
>	-H "User-Agent: User-Agent" \
>	-H "Content-Type: application/json" \
>	-u "<username>:<password>" \
>	-d '{
>	"requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a",
>	"amount": {
>	"amount": "10.00",
>	"currency": "AUD"
>	},
>	"merchantReference": "merchantRefundId-1234",
>	"refundMerchantReference": "merchantRefundId-1234"
>	}'

1	{
2	"amount": {
3	"amount": "10.00",
4	"currency": "AUD"
5	},
6	"merchantReference": "merchantRefundId-1234",
7	"refundId": "67890123",
8	"refundMerchantReference": "merchantRefundId-1234",
9	"refundedAt": "2023-01-01T00:00:00.000Z",
10	"requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a"
11	}

Create Refund

Create Refund

Authentication

Path parameters

Headers

Request

Response

Errors

Authentication

Path parameters

Headers

Request

Response

Errors