Manage Payouts

Overview

The GrailPay Payments API provides endpoints for retrieving payout information, allowing your systems to monitor, audit, and reconcile outgoing funds. Payouts represent the credit leg of an ACH transfer and are typically linked to the original transaction that initiated the flow of funds.

Payout retrieval is handled through two endpoints:

• List Payouts — retrieve a filtered, paginated list of payouts
• Fetch a Payout — retrieve a single payout by its UUID

These replace the previous entity-scoped endpoints, which required a separate call depending on whether the payout was made to a Business, Merchant, Person, or Processor. Payout type and recipient are now expressed as filters on a single unified endpoint.

Note

Payout responses include a modality field that tells you exactly how each payout was sent and how quickly it will arrive. The modality field contains two pieces of information:

• The method used to send the funds (such as ACH or FedNow)
• The speed at which the transfer will complete

This makes it easier to track and report on your payouts, giving you a clearer picture of how money is moving through our system. You’ll see this field in responses from all payout endpoints, as well as in payout webhook events.

Caution

The v1 and v2 payout endpoints are deprecated on April 1, 2027 and sunset on October 1, 2027. Integrate with the v3 endpoints described on this page; the Migration Guide maps every earlier payout endpoint to its replacement.

---

List Payouts

To retrieve a list of payouts, use this endpoint to return all payout records associated with your account. This endpoint supports a rich set of query parameter filters, allowing you to refine results by payout type, status, recipient, related transaction, merchant, amount, date range, ACH trace ID, and return code. Results are paginated and can be sorted by created date or amount.

Payouts can be filtered by type — individual, batch, vendor_fee, or standalone — making it straightforward to isolate a specific class of disbursement without needing separate endpoints for each.

This is especially useful for:

• Reconciling disbursements across multiple transactions
• Reviewing payout history for a specific recipient or merchant
• Powering payout dashboards and internal reporting tools
• Monitoring payout statuses and ACH return codes

For full request and response definitions, including all available filters, refer to the List Payouts OpenAPI Documentation.

---

Fetch a Payout

To retrieve the details of a specific payout, provide the payout UUID. The response includes a complete record of that disbursement, including its status, amount, modality, associated transactions, and timestamps.

For full request and response definitions, refer to the Fetch Payout OpenAPI Documentation.

Note

To obtain the UUID for a payout, you can either use the List Payouts endpoint or handle the payout.* webhook events.

---

Standalone Payouts

A Standalone Payout is a credit issued directly to a recipient without an associated transaction. Rather than being funded by the debit leg of a transfer, standalone payouts draw from a pre-funded FBO account that you maintain with GrailPay.

This is useful for disbursement use cases where funds are not collected from a payer at the time of payment — for example, rebates, incentive payments, or scheduled disbursements from a maintained balance.

To create a standalone payout, submit the amount details and recipient UUID to the standalone payout endpoint. The payout is released against your available pre-funded balance and follows the same processing lifecycle and webhook events as any other payout.

Note

Recipients must be onboarded to GrailPay before a standalone payout can be issued to them. For more information, refer to our Onboard a Person, Onboard a Business, or Onboard a Merchant documentation.

For full request and response definitions, refer to the Create Standalone Payout OpenAPI Documentation.

Note

Standalone Payouts are not enabled by default and require both an approved account and a pre-funded FBO account. If you would like to offer this functionality, contact your GrailPay integration support contact to have it enabled on your account.

Caution

Standalone payouts are limited by the available balance in your pre-funded FBO account. A payout that exceeds your available balance will be rejected.

---

Questions?

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

---