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.

Note

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.

---

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.

You can use the Fetch 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 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 by handling 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 page.

---

Webhooks

To monitor refund activity in real-time, handle the refund.* webhook events. They report each change in the refund’s status, including success or failure, with timestamps and the full refund record.

For the payload of each event, visit the Refund Events page.

---

Questions?

If you’re encountering any issues, please reach out to support@grailpay.com.

---