> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Refund | Refunds API

> Initiate refund via the Atoa Refunds API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

> [!NOTE]
>
> Instant refunds are only available for selected merchants with same day payout
> functionality. Please reach out to support if you want to enable refunds in
> your account.

This API creates a refund for a specific successful payment. The refunded amount is credited to the customer's source bank account via a bank transfer within 30 minutes, provided that you have sufficient balance available in your account.
Refund can be either full or partial.

### Authorization

Bearer `<token>`

### Request Body Schema

**paymentRequestId** `string` *required*

The payment request ID of the transaction that needs to be refunded. Only
completed payments can be refunded. \\

Note: If you need to know how to generate a payment request ID, refer to [
Process payment
](https://docs.paywithatoa.com/api-reference/payment/process-payment.md).

**amount** `number` *required*

Amount to be refunded (should not exceed the original transaction amount).
Decimal values are allowed. Minimum value is 1.

**currency** `string`

The currency of the refund amount. If not specified, the currency of the
original transaction will be used. Example: "GBP".

**refundNotes** `string`

Refund reason for your internal reference.
\[!NOTE] Note:- The note must be 200 characters or less.

> [!NOTE]
>
> To simulate a `FAILED` refund in sandbox environment you can pass a note with `FAILURE TEST`

**metadata** `object`

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

* Up to **50** key-value pairs.
* Each key must be **1–40** characters and must not contain `[` or `]`.
* Each value must be a **string** of at most **500** characters.

Once set, metadata is returned in the [Get Refunds](https://docs.paywithatoa.com/api-reference/refund/get-refund-payments.md) response, and is included in the [Refund Status Webhook](https://docs.paywithatoa.com/api-reference/webhook/refund-status-webhook-response.md).

> [!NOTE]
>
> The refund's metadata is independent of the payment's — it is not inherited. Metadata is frozen when the refund is created and cannot be changed afterwards. An empty object (`{}`) is treated as no metadata.

### Response

**refundId** `string`

The unique identifier for the refund transaction. You can use this ID to
cancel the refund later via the&#x20;
[Cancel Refund](https://docs.paywithatoa.com/api-reference/refund/cancel-refund.md) API.

**paymentRequestId** `string`

The ID of the original payment request that is being refunded.

**paymentIdempotencyId** `string`

The idempotency ID of the original payment, used to ensure the payment was
processed only once.

**status** `string`

The current status of the refund request (e.g., "INITIATED", "COMPLETED",
"FAILED").

**paidAmount** `string`

The original amount that was paid in the transaction being refunded.

**refundAmount** `string`

The amount being refunded to the customer.

**currency** `string`

The currency code for the refund transaction (e.g., "GBP").

**refundNotes** `string`

Notes or reason provided for the refund.

**orderId** `string`

The order ID associated with the original transaction.

**updatedAt** `string`

The timestamp when this refund request was last updated.

**createdAt** `string`

The timestamp when this refund request was created in the system.

```json 200 theme={null}
{
    "refundId": "a7c82e45-9f31-42b6-8d15-7e63f1b92c4d",
    "paymentRequestId": "5e8b2c73-1f64-4a97-9c38-d2f6ae15b8c2",
    "paymentIdempotencyId": "ATOA1234567890123",
    "status": "INITIATED",
    "paidAmount": "250.75",
    "refundAmount": "25.50",
    "currency": "GBP",
    "refundNotes": "Customer requested refund",
    "orderId": "987654321",
    "createdAt": "2023-11-15T14:32:45.789Z",
    "updatedAt": "2023-11-15T14:32:45.789Z"
}
```

```json 400 theme={null}
{
  "name": "BadRequestException",
  "message": "Refund amount exceeded"
}
```

```json 401 theme={null}
{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": []
}
```

```json 404 theme={null}
{
  "name": "NOT_FOUND",
  "message": "The payment request ID provided by you does not exist. Please enter a valid one and try again.",
  "status": 404,
  "errors": []
}
```

```json 405 theme={null}
{
  "name": "METHOD_NOT_ALLOWED",
  "message": "Refunds are not available for this account. Please contact support.",
  "status": 405,
  "errors": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.