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 asPENDING
,
PROCESSED
, or 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
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 ACH API.1. Retrieve the Original Transaction UUID
To create a refund, you’ll need theuuid
of the transaction you wish to refund. Only transactions that have a status
of PROCESSED
are eligible.
A refund can be initiated any time after the original transaction reaches a PROCESSED status. However, the refund
itself will not begin processing until the original transaction has fully settled — a process that may take several
business days.
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 transactionuuid
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 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
PROCESSED
. 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.
Webhooks
To monitor refund activity in real-time, subscribe to theRefund
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 page.