> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/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 icon="lightbulb" title="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.
</Note>

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

<ParamField body="paymentRequestId" type="string" required>
  The payment request ID of the transaction that needs to be refunded. Only
  completed payments can be refunded. <br />
  Note: If you need to know how to generate a payment request ID, refer to <a href="/api-reference/Payment/process-payment">
  Process payment
  </a>.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to be refunded (should not exceed the original transaction amount).
  Decimal values are allowed. Minimum value is 1.
</ParamField>

<ParamField body="currency" type="string" optional>
  The currency of the refund amount. If not specified, the currency of the
  original transaction will be used. Example: "GBP".
</ParamField>

<ParamField body="refundNotes" type="string">
  Refund reason for your internal reference.

  <Info icon="lightbulb" title="Note">
    To simulate a `FAILED` refund in sandbox environment you can pass a note with `FAILURE TEST`
  </Info>
</ParamField>

<ParamField body="metadata" type="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](/api-reference/Refund/getRefundPayments) response, and is included in the [Refund Status Webhook](/api-reference/Webhook/refundStatusWebhookResponse).

  <Info>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.</Info>
</ParamField>

### Response

<ResponseField name="refundId" type="string">
  The unique identifier for the refund transaction. You can use this ID to
  cancel the refund later via the{" "}
  <a href="/api-reference/Refund/cancelRefund">Cancel Refund</a> API.
</ResponseField>

<ResponseField name="paymentRequestId" type="string">
  The ID of the original payment request that is being refunded.
</ResponseField>

<ResponseField name="paymentIdempotencyId" type="string">
  The idempotency ID of the original payment, used to ensure the payment was
  processed only once.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the refund request (e.g., "INITIATED", "COMPLETED",
  "FAILED").
</ResponseField>

<ResponseField name="paidAmount" type="string">
  The original amount that was paid in the transaction being refunded.
</ResponseField>

<ResponseField name="refundAmount" type="string">
  The amount being refunded to the customer.
</ResponseField>

<ResponseField name="currency" type="string">
  The currency code for the refund transaction (e.g., "GBP").
</ResponseField>

<ResponseField name="refundNotes" type="string">
  Notes or reason provided for the refund.
</ResponseField>

<ResponseField name="orderId" type="string">
  The order ID associated with the original transaction.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  The timestamp when this refund request was last updated.
</ResponseField>

<ResponseField name="createdAt" type="string">
  The timestamp when this refund request was created in the system.
</ResponseField>

<ResponseExample>
  ```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": []
  }
  ```
</ResponseExample>