> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grailpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Payments API Changelog
### What's new:
GrailPay now supports standalone KYC verification for persons, independent of any merchant or
business onboarding flow. A new API allows clients to verify individuals directly, with support
for both GrailPay-managed and externally provided verification.
### Why it matters:
Previously, KYC verification was only available as part of the merchant onboarding process. With
standalone Person KYC, clients who need to verify individuals outside of a business context—or
ahead of onboarding—can now do so through a dedicated API. This provides greater flexibility in
how and when identity verification is performed while maintaining consistent compliance tracking.
### Highlights:
* New API endpoint for verifying persons independently, without requiring a merchant or business association
* Supports two verification methods: GrailPay-managed verification (via OneFootprint) or externally verified data provided by clients or partners
* Intelligent duplicate detection using identity details such as TIN and personal information
* KYC results are automatically shared with the Identity service for connected users
* Compliance status updates are processed consistently, ensuring accurate tracking and reliable notifications with no disruption to existing integrations
### What's new:
GrailPay has made significant improvements to how payments are created and processed. The system
now responds faster, handles errors more gracefully, and provides greater visibility into payment
status—all without impacting the experience for end users or merchants.
### Why it matters:
Payment processing reliability is the foundation of any payments platform. These improvements
ensure that payments move through the system more predictably, recover automatically from
temporary failures, and provide clear audit trails for operations and support teams. For
integration partners, faster API responses and better error messaging mean a smoother
development experience.
### Highlights:
* Payment creation now returns an immediate response—processing is handled asynchronously in the background for a noticeably faster experience
* Payments follow a clearer lifecycle: created → queued → processed, making it easier to track status at any point
* Failed processing attempts are automatically retried in the next available window, with each attempt logged with a reason and timestamp
* Processing limits are checked before submission—payments wait for the next window rather than failing outright
* Stronger upfront validation ensures payer and payee are valid, active, compliant, and have the correct bank accounts before a payment is created
* Cancelled or paused payments are handled correctly in the queue—cancelled payments will not proceed, and resumed payments pick up where they left off without duplicates
* Updated API documentation with a full list of possible error messages and their meanings
* Improved system logging and monitoring to reduce edge-case issues in production
### What's new:
This release resolves an issue that prevented clients from subscribing to the `NocProcessed`
webhook event.
### Why it matters:
The `NocProcessed` event is essential for receiving real-time notifications when a Notification
of Change (NOC) has been processed. This fix ensures that the event can be successfully registered
during webhook setup.
### Highlights:
* Fixed an issue where the `NocProcessed` webhook event was rejected as invalid during registration despite being a
supported event type
### What's new:
GrailPay now supports onboarding Beneficial Owners using an Individual Tax Identification Number
(ITIN) in place of a traditional Social Security Number (SSN).
### Why it matters:
Not all beneficial owners have a Social Security Number. By accepting ITINs, GrailPay enables a
broader range of legitimate business owners to complete onboarding and pass KYC verification—
expanding access to the platform while maintaining compliance standards.
### Highlights:
* Beneficial Owners can now be onboarded using an ITIN (tax IDs in the 900–999 range)
* ITIN values are validated against IRS formatting rules, with clear error messaging for invalid entries
* Updated SSN validation messaging to accurately reflect accepted formats
### What's new:
Phase 2 of the KYB Compliance Refactor and Beneficial Owner Migration is now complete. Merchant
compliance is no longer stored as a static flag—it is now dynamically computed based on the latest
KYB result from verification providers and the KYC results of all associated Beneficial Owners.
A new `compliance_status` object and `ComplianceStatusChanged` webhook event have been introduced
to give you full visibility into a Merchant's compliance posture.
### Why it matters:
With compliance status now computed in real time, approval decisions always reflect the most current
verification data. This eliminates the risk of stale or outdated compliance states and ensures that
only Merchants with approved KYB and fully verified Beneficial Owners can transact. The new
`compliance_status` object consolidates KYB and KYC information into a single view, and the
`ComplianceStatusChanged` webhook keeps you informed the moment anything changes.
### Highlights:
* Merchant compliance is now dynamically computed—a Merchant is approved only when KYB status is `approved` and all Beneficial Owners have approved KYC statuses
* Merchants processed by third parties are recorded with a status of `approved_externally`
* New `compliance_status` object added to V3 API Merchant responses and webhook payloads, showing the latest KYB status and KYC status of each Beneficial Owner
* New `ComplianceStatusChanged` webhook event fires whenever KYB or KYC status changes — **all clients must subscribe to this event**
* Updates to Merchant or Beneficial Owner data automatically retrigger compliance checks
* All legacy compliance logic and deprecated approval handling have been removed
### What's new:
GrailPay now provides full merchant status management and compliance enforcement, giving you
direct control over merchant activation and ensuring only active, compliant merchants can
process transactions.
### Why it matters:
Managing merchant eligibility is essential for reducing risk and maintaining regulatory compliance.
With dedicated activation and deactivation endpoints—combined with automatic compliance
validation—you can confidently control which merchants are allowed to transact, with full
transparency into status changes and block reasons.
### Highlights:
* New Activate and Deactivate Merchant API endpoints with optional deactivation reason support
* Merchants have a clear `active` / `inactive` status, with deactivation reasons and timestamps recorded
* Compliance enforcement ensures only merchants with an approved compliance status can process transactions
* Transactions are blocked with clear error responses when a merchant is inactive or non-compliant
* Both conditions—active status and approved compliance—must be met before a transaction is allowed
### What's new:
This release improves error messaging when attempting to delete a bank account that is not yet
eligible for deletion.
### Why it matters:
Clear and actionable error messages help you understand why a request was rejected and what
conditions must be met before proceeding—reducing confusion and support overhead.
### Highlights:
* Improved error messaging for bank account deletion requests when the account is not yet eligible for removal
### What's new:
Clawback APIs are now available in GrailPay V3, providing programmatic access to view and track
clawbacks alongside your other financial resources.
### Why it matters:
Clawbacks are a critical part of payment operations, and until now lacked dedicated API support in V3.
With these new endpoints, you can retrieve and monitor clawbacks with the same consistency and
reliability you expect from the rest of the GrailPay API—streamlining reconciliation and reporting.
### Highlights:
* New V3 Clawback API endpoints for viewing and tracking clawbacks
* Consistent resource structure aligned with other V3 financial APIs
* Enables programmatic access for improved reconciliation and reporting workflows
### What's new:
The V3 Account Validation API now supports multiple versions of Account Intelligence, giving you
the flexibility to choose between V1, V2, or V3 intelligence models when validating bank accounts
and routing numbers.
### Why it matters:
Each version of Account Intelligence offers different levels of insight and decisioning capability.
With version selection, you can adopt newer models at your own pace—leveraging enhanced risk signals
and validation accuracy when you're ready, while maintaining compatibility with existing integrations.
### Highlights:
* V3 Account Validation endpoint now accepts a version parameter for Account Intelligence
* Choose between V1, V2, or V3 intelligence models per request
* Newer model versions provide enhanced insights and improved validation accuracy
* Full backward compatibility with existing validation workflows
### What's new:
GrailPay now automatically falls back from FedNow to Fast ACH (same-day) when a FedNow payout fails,
ensuring funds are still delivered without delay.
### Why it matters:
FedNow payouts can occasionally fail due to network issues or recipient bank limitations. Rather than
requiring manual intervention or leaving a payout in a failed state, the platform now automatically
retries via Fast ACH—keeping your payment operations running smoothly and your vendors paid on time.
### Highlights:
* Automatic failover from FedNow to Fast ACH (same-day) for failed individual payouts
* Ensures uninterrupted fund delivery without manual intervention
* Failover is seamless and requires no action on your end
### What's new:
The Bank Link flow has been enhanced to ensure reliable OAuth redirection for mobile applications.
### Why it matters:
During bank linking, users are redirected to their bank's OAuth flow to authorize account access.
Previously, mobile applications could experience session loss after completing OAuth, interrupting
the linking process. This fix ensures a seamless return to the Bank Link flow after authorization.
### Highlights:
* Improved OAuth redirect handling for mobile Bank Link sessions
* Prevents session loss after OAuth completion, allowing the bank linking process to continue without interruption
### What's new:
Processor payouts exceeding \$1,000,000 are now automatically split into multiple smaller payouts to
ensure successful processing without hitting banking or partner-imposed limits.
### Why it matters:
Large processor payouts can fail or be rejected when they exceed thresholds set by banking partners.
Automatic splitting removes this risk, ensuring high-value payouts process reliably without requiring
manual intervention.
### Highlights:
* Processor payouts exceeding \$1M are automatically divided into multiple payouts, each below the threshold
* Applies to both ACH and FedNow processor payouts
* Processing is seamless with no action required on your end
### What's new:
This release includes an update to the Swagger API documentation security schema.
### Why it matters:
Keeping our OpenAPI specification compliant with validation standards ensures a consistent and
warning-free experience when testing authenticated endpoints through the Swagger UI.
### Highlights:
* Updated the Swagger security schema naming to comply with OpenAPI validation rules, eliminating documentation warnings
### What's new:
GrailPay now supports FedNow for processor payouts, along with new webhook events and a standardized
modality response object to give you full visibility into how processor-level payouts are processed.
### Why it matters:
Processor payouts can involve high volumes of batched transactions, making transparency into their
status and payment rail critical. These additions enable real-time tracking of processor payout
lifecycles and provide clear insight into whether funds were sent via ACH or FedNow—improving
reconciliation and confidence in your payout operations.
### Highlights:
* FedNow is now supported as a payment rail for processor payouts
* New webhook events for processor payout lifecycle tracking:
* `ProcessorPayoutCreated`
* `ProcessorPayoutCompleted`
* `ProcessorPayoutFailed`
* A `modality` object is now included in batch payout responses, indicating the payment rail (ACH or FedNow) and processing speed
* Historical payout records have been backfilled with modality data for full consistency
### What's new:
This release resolves issues with our Swagger API documentation that were causing validation failures.
### Why it matters:
Accurate and reliable API documentation is essential for a smooth integration experience. These fixes
ensure the Swagger UI remains a dependable reference for building against the GrailPay API.
### Highlights:
* Resolved OpenAPI specification issues that were causing Swagger validation failures in production
* API documentation now passes all validation checks, ensuring accuracy for developers and integrators using the Swagger UI
### What's new:
This release includes fixes to improve the developer experience when working with the GrailPay API.
### Why it matters:
These updates reduce friction when testing API endpoints and submitting data, helping you integrate
more quickly and avoid common validation errors.
### Highlights:
* Fixed an issue where Swagger UI was not correctly passing the `Authorization: Bearer` header on authenticated requests — tokens entered in the Authorize section now work as expected
* Improved phone number validation messaging to clearly indicate that values must contain exactly 10 digits without the `+1` prefix or special characters
### What's new:
GrailPay now supports FedNow payouts, enabling instant, around-the-clock payout processing for eligible
transactions. Clients approved for FedNow will automatically receive payouts via the FedNow network once their
associated transaction debits have settled.
### Why it matters:
Traditional ACH payouts are limited to banking hours and standard processing windows. With FedNow support,
your vendors can receive funds in real time—24 hours a day, 7 days a week—reducing settlement delays and
improving cash flow for your payment operations.
### Highlights:
* Instant payouts via the FedNow network for enabled vendors
* True 24/7 payout processing with no dependency on banking hours
* Automatic routing ensures FedNow-eligible transactions are processed separately from standard ACH payouts
### What’s new:
We’ve introduced three new `Person` statuses and a new webhook event to improve visibility into why a person may
be placed on hold.
### Why it matters:
These additions provide clearer insight into hold reasons—whether related to sanctions or suspected fraud—so you can
take appropriate action and maintain compliance. The new webhook event ensures real-time notification when a person’s
status changes.
### Highlights:
* New person statuses:
* `ON_HOLD_SANCTIONS`
* `ON_HOLD_FRAUD_PAYER`
* `ON_HOLD_FRAUD_PAYEE`
* New `PersonStatusChanged` webhook event triggers whenever a person enters or exits one of these statuses
* Enhances transparency and traceability for risk-related holds
### What’s new:
We’ve added full transaction lifecycle management to the GrailPay API with three new V3 endpoints: **Pause**,
**Resume**, and **Cancel**.
### Why it matters:
These new controls give vendors and processors more flexibility and control over transaction processing. Whether
halting a transaction for compliance review or canceling a transfer in progress, this release adds powerful
capabilities with complete auditability and real-time notifications.
Please view our updated [Manage Transactions](/docs/technical/transactions/manage-transactions) guide for full details on using
these new endpoints and understanding their behavior.
### Highlights:
* **New V3 endpoints** for pausing, resuming, and canceling transactions
* **New transaction statuses**: `PAUSED` and `AWAITING_CANCELLATION`, with full timestamp tracking
* **Pause** halts the ACH processing for a transaction in progress
* **Resume** re-initiates ACH or syncs with bank state depending on prior progress
* **Cancel** either halts the transaction immediately or initiates a reverse payout if debit has been settled
* **Three new webhook events**: `TransactionPaused`, `TransactionResumed`, and `TransactionAwaitingCancellation`
### What’s new:
We’ve fixed an issue where the `MerchantUpdated` webhook event was not being triggered when a merchant transitioned
to the `IN_REVIEW` state.
### Why it matters:
Merchants moving into review—either due to failed KYC or updates from Middesk—will now properly emit webhook
notifications. This ensures platforms receive real-time updates and can accurately reflect onboarding status in
their workflows.
### Highlights:
* Fixed bug preventing `MerchantUpdated` webhook from triggering on `IN_REVIEW` transitions
* Webhooks now trigger on KYC failure when KYB status moves to `IN_REVIEW`
* Middesk-originated `IN_REVIEW` changes also emit update notifications
### What’s new
No new features were released in this update.
### Why it matters
We’ve made backend improvements to ensure data integrity and consistency across V3 listing endpoints, especially
when handling relational data like linked bank accounts.
### Highlights
* Fixed binding issues between collection objects and resource transformers
* Ensured relational data (e.g., bank accounts) is preserved during transformation
* Added safeguards to prevent data loss during response transformation
### What’s new
We’ve made several enhancements to the V3 API, including unified bank account data across key endpoints and a new
onboarding flow for adding bank accounts to persons.
### Why it matters
These updates give you greater visibility into linked bank accounts, improve onboarding flexibility, and enable
support for additional payment rails like FedNow. You can now onboard and validate accounts via Plaid or manually—all
with consistent structure and improved intelligence.
### Highlights
* **Unified Bank Account Objects:** Bank account details are now included in all V3 listing and detail API responses for
People, Merchants, and Businesses.
* **New V3 Bank Account Onboarding Endpoint:** New v3 API endpoint for adding bank accounts with account intelligence of various versions. This includes:
* Support for both Plaid-based and manual bank account onboarding
* Comprehensive account validation including account holder name verification
* Duplicate detection for manual accounts
* **Cleaner Timestamp Responses:** Removed unused updated\_at fields for a more streamlined response format.
### What’s new:
We’ve added a new status field to all Person-related V3 API responses, including List, Fetch, Onboard, and Update,
as well as the PersonCreated and PersonUpdated webhook event payloads.
### Why it matters:
You can now immediately see the current status of any user in your system. This makes it easier to confirm that a
person is in a valid state to transact before initiating a transfer, helping reduce failed attempts and streamline your integration logic.
### Highlights:
* New status parameter added to V3 API responses for People (List, Fetch, Onboard, Update)
* Included in webhook payloads for both person creation and updates
* Improves visibility into user state and transactional readiness across the platform
### What’s new:
We’ve added a new `kyb_rejected_reason` field to both the Merchant Create and Merchant Update API responses, as
well as the corresponding MerchantCreated and MerchantUpdated webhook event payloads.
### Why it matters:
You can now see the specific reason a merchant’s KYB (Know Your Business) verification failed. This provides greater
transparency and helps streamline your onboarding and support workflows.
#### Highlights:
* New `kyb_rejected_reason` parameter added to API responses ( Onboard, Update, List, Fetch )
* Included in webhook payloads for both merchant creation and updates
* Ensures consistent, actionable KYB feedback across the API and webhooks
### Maintenance Items
* **OpenAPI Documentation Updates:** Fixed an issue with the Webhook Registration OpenAPI documentation to specify
that the `webhook_url` field should be passed as an array to allow for multiple webhook URLs.
### Release Features
* **Optimized Business & Merchant Response Payloads:**
* Responses: Removed full Person objects from create and update responses
* Relations Object: Responses now include a clean relations object containing only the Person UUID
* **OpenAPI Documentation Updates:** Updated OpenAPI documentation for Business and Merchant onboarding and update endpoints
to reflect the new relational data structure.
### Maintenance Items
* **Vendor Object in Relations:** Resolved an issue where the vendor object was incorrectly appearing in List
Person and List Merchant API responses. The relations attribute now correctly returns only allowed UUID references,
ensuring consistency across all V3 endpoints.
### Release Features
* **V3 API Response Standardization:** All V3 APIs of List and Showing (Person, Business, and Merchant) now follow a
unified response contract with consistent structure. Error responses are now standardized across all endpoints,
providing clearer, more consumer-friendly messages with proper attribute naming in validation errors.
* **Enhanced Relational Data:** We've introduced a new relations object across all V3 endpoints, making it easier to
understand entity relationships:
* Person responses now include related Business or Merchant UUIDs.
* Business responses include the associated Person UUID.
* Merchant responses include the associated Person UUID.
* **Webhook Enhancements:** Updated Person and Merchant webhook responses to include the new relations object structure,
providing cleaner, more relevant information for integrations.
### Maintenance Items
* **Billing Improvements:** Fixed filter inconsistencies in Billing Item and Summary endpoints, ensuring accurate and
reliable query results across both endpoints with consistent behavior.