Create a Transaction

​

What is a Transaction?

A Transaction in the GrailPay Payments API initiates the movement of funds between two users — typically a payer ( sender ) and a payee ( recipient ) — via the ACH network. It represents the debit leg of the transfer, capturing the withdrawal of funds from the payer’s bank account. Once processed, the transaction will result in a corresponding Payout, which reflects the credit leg — the delivery of funds to the payee. Each transaction is uniquely identified by a uuid and includes metadata such as the amount, participants, and processing status. Transactions can represent:

• Merchant to Merchant payments
• Merchant to Business or Business to Merchant payments
• Merchant to Person disbursements
• Person to Merchant collections
• Person to Person payments

Once created, the transaction enters a processing pipeline that will debit the payer’s bank account and credit the payee’s bank account, subject to ACH network rules and timing.

---

​

Overview

Creating a transaction involves initiating a fund transfer between two parties — a payer (sender) and a payee (recipient). Both parties must be onboarded and must have valid, connected bank accounts within the GrailPay system. When a transaction is successfully created, the API returns a unique uuid that can be used to track its status or retrieve its details later. This guide outlines the required fields, entity prerequisites, and common validation scenarios encountered when initiating a transaction.

---

​

Person to Person Payments

GrailPay supports payments directly between two people, allowing funds to move from one individual to another without a registered Merchant on either side of the transaction. Please note that fulfilling the compliance obligations applicable to ACH operates differently for Person to Person payments than payments with Merchants in our system. To create a Person to Person transaction, both of the following must be true:

• The payee’s KYC status is approved. The individual receiving funds must have successfully passed Know Your Customer (KYC) identity verification and reached the approved status before you create the transaction. Submitting a person for KYC does not immediately approve them — wait for the ComplianceStatusChanged webhook event to report an approved status. A submitted, rejected, or any ON_HOLD_* status does not satisfy this requirement. See Submit Person for KYC to initiate verification for a person.
• Your account is approved for Person to Person payments. This functionality must be explicitly enabled on your integration by GrailPay.

---

​

Destination Account & Batch Payouts

When creating a transaction, you can optionally specify a destination account — the payee’s bank account that will receive the payout — using the destination_bank_account field. How GrailPay uses this value depends on whether the merchant receiving the funds is configured for Batch Payouts. For more on how batch and direct payouts are delivered, see Scenarios: Direct & Batch Payouts. To update a Merchant or Business to receive individual payouts instead of Batch Payouts, please refer to the Manage Users page.

---

​

Transaction Metadata

When creating a transaction, you can optionally include metadata fields that describe the transfer. These values are passed through to the ACH entries and appear on bank statements and in ACH records, helping both the payer and payee recognize the purpose of the payment. All three fields are optional. Any value you send is sanitized before it is used:

• Only letters, numbers, and spaces are kept — any other characters are removed.
• Consecutive spaces are collapsed into a single space.

​

Capture vs. Payout Metadata

Every transfer moves money in two legs, and metadata is applied independently to each:

• Capture — the debit that pulls funds from the payer’s bank account. Uses the values you send at creation.
• Payout — the credit that delivers funds to the payee’s bank account. Derives its own metadata later, drawing on the stored transaction values and the payer’s profile.

Because the two legs are computed separately, they can display different values, and leaving a field blank at creation does not mean it will be empty on the payout.

​

Capture metadata (debit leg)

At creation, the values you provide are applied to the capture ACH entry:

​

Payout metadata (credit leg)

When the transaction reaches payout, metadata for the credit ACH entry is recalculated — it does not simply copy the capture values. Each field falls through the following order until a usable value is found. Because these payout values are derived by GrailPay rather than submitted in your request, they are sanitized and trimmed to fit each field’s limit:

---

​

Testing

To test transactions in GrailPay’s sandbox environment, you’ll need two entities:

• One with a connected bank account to act as the payer
• One with a connected bank account to act as the payee

For more information on creating accounts in our sandbox environment, see the Technical Overview guide. You can provide these details when creating test users via the following endpoints:

• Onboard a Person
• Onboard a Business
• Onboard a Merchant
• Add Bank Account

This setup allows you to perform end-to-end transaction testing — including creation, settlement, and simulated failure — without using real financial data.

---

​

Step 1: Confirm Participants Are Onboarded

Before creating a transaction, both the payer and payee must exist in the system as valid users (i.e. persons or businesses). Each must meet the following criteria:

• Successfully onboarded using the appropriate flow
• Possess a valid uuid
• Have an active, connected bank account (manual or Plaid-linked)

You will reference these participants using:

• payer_uuid — the sender of funds
• payee_uuid — the recipient of funds

If either party is missing or has an invalid account, the transaction will be rejected.

---

​

Step 2: Determine Transaction Type and Amount

Each transaction must include:

• amount — The dollar value to be transferred
• speed — Indicates processing tier (e.g., standard or sameday, if available in your integration)

Optional fields include:

• client_reference_id — Optional reference ID from your system
• description — Optional metadata for reporting

All amounts must be denominated in USD and specified in cents (e.g., $10.00 = 1000).

---

​

Step 3: Submit the Transaction

To initiate the transaction, send a POST request to the following endpoint: /3p/api/v1/transactions with the required fields. Upon success, the API will return a uuid representing the newly created transaction. This can be used to fetch status updates or cancellation requests.

​

Character Limits

When creating a new transaction, certain fields are subject to strict character limits. These constraints are imposed by the ACH network and our banking partners to ensure compatibility with downstream systems: Make sure your values do not exceed these limits, or the transaction may be rejected during processing. See the Create Transaction OpenAPI documentation for the full schema, including all required and optional fields.

---

​

Step 4: Monitor the Transaction Status

Once submitted, a transaction may move through multiple states depending on processing speed, ACH timing, and risk evaluation. Possible states include:

• CAPTURE_PENDING
• CAPTURE_ACH_PENDING
• CAPTURE_ACH_FAILED
• CANCELED
• IN_PAYOUT

To see a full list of states and their definitions, refer to the Transaction States documentation. To monitor the state of a transaction, you can use one of the following methods:

• Webhook Notifications: Set up webhooks to receive real-time Webhook Events on transaction status changes.
• API Polling: Use the GET /3p/api/v2/transactions/{transaction_uuid} endpoint to fetch the current status of a specific transaction.

---

​

Questions?

If you’re encountering any issues, contact your GrailPay integration support contact or open a support request via the portal.

---

​

Resources

Below you will find some helpful resources to assist with understanding how transactions work in GrailPay.

• Transaction States
• ACH Return Codes
• Scenarios: Direct & Batch Payouts
• Transaction Queues