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

# Create a Refund

Refunds in the GrailPay Payments API allow you to reverse a completed transaction by returning funds to the original sender.
This guide walks through the process of creating a refund, outlines the requirements, and explains how to test refund
flows in the sandbox environment.

***

### What is a Refund?

A **Refund** represents a reversal of a previously completed transaction. Once a transaction has been successfully
processed and settled, you may issue a refund to return some or all of the original funds back to the payor. Refunds
are commonly used for resolving customer disputes, cancellations, or error corrections.

Every refund is linked to a specific transaction and has its own lifecycle, including statuses such as `REFUND_PENDING`,
`REFUND_COMPLETE`, or `REFUND_FAILED`. Refunds are processed through the ACH network, similar to standard transactions, and
typically result in a new payout to the original payor.

***

### What is a Batch Refund?

A **Batch Refund** is a structured mechanism for processing multiple refund requests together under a single operation.
Instead of initiating individual refund payments one by one, GrailPay groups confirmed refund requests into batches,
processes them collectively, and facilitates a single fund capture per batch.

This is particularly useful in vendor scenarios where a platform (such as a payment aggregator or facilitator) needs to
approve and fund multiple refunds initiated by their underlying merchants. By batching these refunds:

* GrailPay can consolidate refund amounts by merchant or partner
* The platform receives a shared refund ledger to review all refund requests
* Only confirmed refunds are included in the batch and processed
* A batch UUID is generated to track the group of refunds
* A single debit (refund capture) is initiated against the platform’s funding account for the total amount of the batch

This approach improves operational efficiency, ensures partner-level authorization, and simplifies reconciliation for
multi-vendor platforms.

<Info>
  There is no public API endpoint for creating a batch refund. This is by design as batch refunds require an internal
  approval process before they can be processed. Refund requests are initiated individually by vendors, then reviewed
  and confirmed through a shared ledger process. Once approved, GrailPay internally generates batch UUIDs to group the
  confirmed refunds for processing. This ensures proper authorization, accountability, and fund availability before
  initiating any refund captures.
</Info>

***

### Steps to Create a Refund

Follow these steps to successfully create a refund using the GrailPay Payments API.

***

#### 1. Retrieve the Original Transaction UUID

To create a refund, you’ll need the `uuid` of the transaction you wish to refund. Only transactions that have begun the
settlement process (i.e., have reached a **CAPTURE\_ACH\_PENDING** or later status) are eligible for refunds.

<Note>
  A refund can be initiated any time after the original transaction reaches a **CAPTURE\_ACH\_PENDING** status. However, the refund
  itself will not begin processing until the original transaction has fully settled — a process that may take several
  business days.
</Note>

You can use the [Fetch Transaction by UUID](/docs/technical/transactions/manage-transactions#fetch-a-transaction-by-uuid) endpoint to retrieve the
transaction details and confirm eligibility.

***

#### 2. Issue a Refund Request

Once you’ve confirmed the transaction is eligible, you can send a refund request by making a POST call to the refund
endpoint. The request must include the original transaction `uuid` and the `amount` to be refunded.

Refunds can be **partial** or **full**, but the total amount refunded must not exceed the original transaction amount.

Refer to the [Refund a Transaction](https://api.grailpay.com/api/documentation#/Refunds/d88ce5d80658c8999d1ca01633290d01)
OpenAPI documentation for full request and response details.

***

#### 3. Monitor Refund Status

Once submitted, the refund will move through the standard processing lifecycle. You can monitor the status of a refund
y subscribing to the **Refund** webhook events.

We strongly recommend using webhooks to stay updated on refund processing outcomes, especially in production environments.

***

### Testing Refunds

To test refunds in the sandbox environment:

* Ensure the transaction you are refunding has a status of `CAPTURE_ACH_PENDING` or later status
  ( ie. `PAYOUT_ACH_PENDING`, `IN_PAYOUT`). In sandbox, this is typically simulated shortly after creation.
* Use the same transaction UUID for your refund request.
* You may refund the full amount or a partial amount.

For more sandbox testing details, see the [Technical Overview](/docs/technical/overview#testing) page.

***

### Webhooks

To monitor refund activity in real-time, subscribe to the `Refund` webhook events. This event provides updates on the
status of the refund, including success or failure, timestamps, and metadata.

For more details, visit the [Webhook Events](/docs/technical/webhooks/events) page.

***

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

***