> For the complete documentation index, see [llms.txt](https://docs.optty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optty.com/direct-api-orders/order-flow/post-orders-reference-refund.md).

# POST /orders/{reference}/refund

## POST /orders/{orderReference}/refund

> Process a refund for an order ---- \[auth scope:  api-user]

```json
{"openapi":"3.0.0","info":{"title":"Merchant API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"OrderRefundDto":{"type":"object","properties":{"refundReference":{"type":"string","description":"A unique reference identifier for this refund request. This must be unique per merchant."},"refundAmount":{"description":"The currency and amount to be refunded to the customer. The currency must match the currency of the original order. The amount must be a positive number with up to 2 decimal places. For full refund, this should equal the order amount + surcharge amount. For partial refund (if the APM supports it), this can be any amount up to the remaining refundable amount (captured amount minus any previously refunded amounts). The sum of all refunds cannot exceed the total captured amount.","allOf":[{"$ref":"#/components/schemas/OrderRefundAmount"}]},"refundDescription":{"type":"string","description":"A brief description or reason for the refund. This can be used to record why the refund was issued. This may be visible to the payment provider."},"isActivatedViaOAuth":{"type":"boolean","description":"If the provider is activated by oAuth or apiKey/ password "}},"required":["refundReference","refundAmount","refundDescription","isActivatedViaOAuth"]},"OrderRefundAmount":{"type":"object","properties":{"amount":{"type":"number","description":"The monetary amount to be refunded to the customer. Must be a positive number with up to 2 decimal places. For full refund, this should equal the captured amount. For partial refund, this can be any amount up to the remaining refundable amount. The currency must match the original order currency.","minimum":0},"currency":{"type":"string","description":"The currency code for the refund in ISO 4217 format (three-letter currency code, e.g., AUD, USD, AED). This must match the currency of the original order. The refund will be processed in this currency."}},"required":["amount","currency"]},"RefundResponse":{"type":"object","properties":{"refundReference":{"type":"string","description":"Refund Reference"},"bnplProvider":{"type":"number","description":"APM Provider","enum":[]},"refundedAmount":{"type":"string","description":"Refund Amount"},"refundStatus":{"type":"string","description":"Refund Status"},"description":{"type":"string","description":"Refund description"},"refundDate":{"type":"string","description":"Refund date"},"bnplRefundId":{"type":"string","description":"bnplRefundId"},"callbackUrl":{"type":"string","description":"The asynchronous refund-callback url"}},"required":["refundReference","bnplProvider","refundedAmount","refundStatus","description","refundDate","bnplRefundId"]},"BadRequestResponse":{"type":"object","properties":{"statusCode":{"type":"number","description":"statusCode"},"message":{"type":"string","description":"message"}},"required":["statusCode","message"]},"UnauthorizedResponse":{"type":"object","properties":{"statusCode":{"type":"number","description":"statusCode"},"message":{"type":"string","description":"message"}},"required":["statusCode","message"]},"NotFoundResponse":{"type":"object","properties":{"statusCode":{"type":"number","description":"statusCode"},"message":{"type":"string","description":"message"}},"required":["statusCode","message"]}}},"paths":{"/orders/{orderReference}/refund":{"post":{"operationId":"RefundsController_refundOrder","summary":"Process a refund for an order ---- [auth scope:  api-user]","deprecated":false,"parameters":[{"name":"orderReference","required":true,"in":"path","description":"The unique order reference that was provided when creating the order. This is your merchant-specific identifier for the order. Use this reference to identify which order to perform operations on (e.g., capture, void, refund, get status).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRefundDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}},"tags":["refunds"]}}}}
```

## Example Request/Response

{% tabs %}
{% tab title="Sample Request" %}

```javascript
{
    "refundReference": "TgEHcPtpN2HSrTMK-0",
    "refundAmount": {
        "amount": 100,
        "currency": "AUD"
    },
    "refundDescription": "Please refund this order"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200 Refund Successfully" %}

```javascript
{
    "refundReference": "TgEHcPtpN2HSrTMK-0-00",
    "bnplProvider": "KLARNA_AU",
    "refundedAmount": 100,
    "refundStatus": "SUCCESSFUL",
    "description": {},
    "refundDate": "Fri, 08 Oct 2021 06:22:20 GMT",
    "bnplRefundId": "8ba78198-bc4c-48ae-9040-57c687bed51d"
}
```

{% endtab %}

{% tab title="400 Over Refund Limit / Parameters Error " %}

```javascript
//OVER REFUND LIMIT
{
    "statusCode": 400,
    "message": "You can only refund amount up to AUD 24.98",
    "error": "Bad Request"
}

//Invalid Parameters/ Value was sent to optty

{
    "statusCode": 400,
    "message": "Unexpected token a in JSON at position 157",
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="401 Check your credentials and accessToken / Environment live or Staging. " %}

```javascript
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="404 Original OrderID doesn" %}

```javascript
{
    "statusCode": 404,
    "message": "Not Found"
}
```

{% endtab %}

{% tab title="500 Internal Server Error" %}

```javascript
{
    "statusCode": 500,
    "message": "Internal server error"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.optty.com/direct-api-orders/order-flow/post-orders-reference-refund.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.