Create a Refund

Refunds in the GrailPay Payments API allow you to reverse a transaction whose payout has settled 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’s payout has 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. A transaction is eligible for a refund only once its payout has settled:

Payout rail	Payout status	Webhook
ACH	PAYOUT_COMPLETE	payout.completed
FedNow	DONE	payout.completed

Settlement can take several business days after the transaction is created. See Transaction States for the full payout lifecycle.

Caution

A refund requested before the payout has settled is rejected. It is not created and is not queued to process later. The v3 API returns a 422 with this message:

The transaction is not refundable because it is not processed yet.

The v1 API returns the same message with a 403. Wait for the payout.completed webhook, then send the refund request again.

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’s payout has settled, 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:

• The same rule applies in sandbox: the transaction’s payout must have settled (PAYOUT_COMPLETE for ACH, DONE for FedNow) before you request a refund. Wait for the payout.completed webhook first. A transaction still in CAPTURE_ACH_PENDING, PAYOUT_ACH_PENDING or IN_PAYOUT returns a 422 from the v3 API, or a 403 from v1.
• 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.

---