Disbursements Guide
A disbursement is the mechanism DirecFunds uses to move funds from your escrow or IOLTA account to one or more recipients. This guide covers the portal workflow, the primary Experience API disbursement-request workflow, and the granular payment resources that remain available for advanced integrations.
Before an integration partner enables this workflow for a newly onboarded company, complete the
partner onboarding and readiness flow and require
GET /Onboarding/Readiness to return disbursementsEnabled: true.
Platform payment rail support
These rails belong to the commercial payout platform. Account access, destination eligibility, payment windows, and funding readiness are checked separately.
Scroll the table to see environment availability.
| Rail | Recipient payout | Managed company funding | Environment availability |
|---|---|---|---|
| ACH | Supported | Payout only | Check authenticated capabilities |
| FedNow Service | Supported | Payout only | Check authenticated capabilities |
| Real Time Payment | Supported | Payout only | Check authenticated capabilities |
| Same Day ACH | Supported | Supported | Check authenticated capabilities |
| Wire Transfer | Supported | Supported | Check authenticated capabilities |
Zelle disabled Zelle remains available on historical records and is excluded from new commercial payouts.
With your own bearer token, read GET /v1/PaymentRails for the environment rail contract and GET /v1/DisbursementRequests/Capabilities for bundled-request funding, payouts, and features. A missing or refused capability needs its actual reason checked; it does not automatically mean your account is disabled.
Payment prerequisites and funding settlement
The company must have the Business disbursements product enabled independently of onboarding readiness.
Without it, bundled $Validate returns 200 with valid: false and the
issue code ProductNotEnabled, bundled create returns 400 (Preflight) with the same
code, and granular POST /Disbursement returns a bare 403. Wire/RTP/FedNow need
transactionDetails.memoLine; purpose Other needs otherPurpose.
Same Day ACH has a $1,000,000 transaction limit and a 2:45 PM Eastern cutoff. A Same Day ACH send after
the cutoff, on a weekend, or on a Federal Reserve holiday is refused with 422
SAME_DAY_ACH_AFTER_CUTOFF and a retryAtUtc; it is never downgraded to another
rail or to next-day settlement. An amount over the limit is refused with 422
SAME_DAY_ACH_AMOUNT_LIMIT. The limit is configurable, so read the current value from
discovery.
Configured risk limits also apply. $Validate reports them as issues and create refuses them
with 400: PaymentAmountLimitExceeded (one payment),
RequestAmountLimitExceeded (one request), and CompanyDebitVelocityLimitExceeded or
CompanyCreditVelocityLimitExceeded (the company's rolling 24-hour totals). These limits are not
published in Capabilities; review the amount with the customer rather than splitting it automatically.
Billing payment method. When billing payment-method enforcement is enabled, the API refuses $Verify and
$VerifyAndSend with 422 and errorCode: BILLING_PAYMENT_METHOD_REQUIRED
(problem type) until a company administrator
saves a chargeable card or US bank account under Manage → Billing → Payment method in the
DirecFunds Portal. Onboarding readiness does not check this. If the refusal's detail says to try
again later, the billing check was temporarily unavailable; retry later with a new idempotency key.
Offer only rails returned by GET /PaymentRails and marked active: true
in GET /DisbursementRequests/Capabilities. Zelle is unavailable in Test and Production.
Each payout must choose its rail explicitly.
Wire recipients require address1, city (at most 35 characters),
state, and postalCode. On Wire, ACH, Same Day ACH, RTP and FedNow,
a Person also needs a past dateOfBirth, full address and 10-digit phone.
A Business needs a 9-digit EIN in tin, or a full address and 10-digit phone;
Wire still requires the address even when an EIN is supplied. A Person's recipient.name and
the destination's accountBeneficiary must be written as a personal name (words of letters,
apostrophes, or hyphens separated by single spaces); digits, underscores, and other punctuation are
refused when the destination account is verified. The gateway validates Wire addresses
during validate/create. The bundled preflight assessment returned by $Validate
(not by create) reports missing identity inputs; provider identity verification still happens at verification,
so a successful $Validate does not guarantee $VerifyAndSend can route the request.
ACH and Same Day ACH inline payout accounts require depositAccountType:
Checking or Savings. Same Day ACH funding also needs a verified,
ACH-capable source account classified as Checking or Savings, plus
achDebitAuthorizationAccepted: true. Account readiness alone does not prove classification.
Same Day ACH funding holds dependent payouts until the debit completes, provider good-funds
confirmation exists, and funding.goodFundsReleaseAt has passed. The request can remain
Processing during this wait. Use the returned UTC release time;
the configured Production hold recorded on October 9, 2026 is 120 hours and may change.
202 Accepted from bundled $VerifyAndSend can include failed or inconclusive
verification with no routing. Inspect request.status, payment verification outcomes,
and allowedNextActions. Granular verify calls can return 200 with
Failed or Inconclusive; proceed only when authoritative state permits sending.
Read approvalRequirements.requiresSeparateApprover. Separation can also be required
by Single Party with Limit, a missing approval limit, the requester's permissions, or the Production
fallback policy. If supplied, intendedApproverUserId must always differ from the requester.
For synthetic Test examples, use https://testapi.direcfunds.com/v1 and routing number
100000000 with DirecFunds UAT Bank. Reserved fixtures are refused outside
Test. Real routing instructions must pass directory validation; the directory replaces
bankName. A changed saved-recipient bank account has a 24-hour cooling period.
How Disbursements Work
A disbursement bundles together:
- Pay Ins — specify the source account funds are drawn from
- Pay Outs — specify the recipients and how each transfer is routed
The total amount across all Pay Ins must equal the total across all Pay Outs before the disbursement can be verified and sent. This amount-matching check is enforced automatically.
Payment rail characteristics
| Rail | Speed | Use Case |
|---|---|---|
| Wire | Same day (if submitted before bank cutoff) | Loan payoffs, seller proceeds, large transfers |
| ACH | 1–3 business days | Routine disbursements, lower-value transfers |
| Same Day ACH | Same business day | Faster routine disbursements |
| Instant Payment (RTP) | Seconds | Time-sensitive transfers to supported banks |
| Zelle | Unavailable | Disabled in Test and Production for new payouts; retained here for historical contracts |
| FedNow | Seconds | Time-sensitive transfers to FedNow-enrolled banks |
API rail rules: Managed source-account Pay Ins support Wire (reverse wire) and authorized SamedayAch debit. Standard Ach funding is unsupported. New Pay Outs support Wire, Ach, SamedayAch, InstantPayment, and FedNow. Zelle is disabled.
Historical Zelle contracts set paymentRail to Zelle and use a destination with
type: "Zelle" plus an email address, a 10-digit phone number, or both. No bank account is
sent for an alias destination. A saved recipient uses type: "SavedRecipient" and
savedRecipientId instead. Zelle is pay-out only and is limited to $5,000 per payment.
Experience API Workflow
New server-to-server integrations should use /DisbursementRequests as the primary closing
object. One request creates the disbursement, calculated funding leg, recipient destinations, and all
recipient payments atomically. The granular /Disbursement, /PayIn,
/PayOut, and /TargetAccount endpoints remain available for integrations that need
to manage each resource separately.
- Call
GET /Integration,GET /PaymentRails, andGET /DisbursementRequests/Capabilitiesto confirm permissions, features, rails, and bundle limits. - Optionally preflight the complete payload with
POST /DisbursementRequests/$Validate. - Create one independent Order disbursement with
POST /DisbursementRequests, a company-uniqueclientReference, and a newX-Idempotency-Key. - If created with
submitForApproval: false, stage it inInitializedand later call$SubmitForApproval. - Approve it once with
$VerifyAndSend. DirecFunds automatically releases a future schedule at or after its due time. - Read
GET /DisbursementRequests/{id}, poll/Eventswith its cursor, and use/Reconciliationto track the outcome. - If one recipient fails, read its
allowedNextActionsand reconcile the provider outcome before taking another action. Recipient-payment$Retryand$ReplaceDestinationare currently capability-disabled; use only a returned allowed action.
DirecFunds has no orderId or multi-request bulk transaction. Fan out multiple Orders as
separate calls and handle partial success per request. One Order may create several requests over
time, but each needs a distinct reference and an existing request cannot be appended to. Before
dispatch, use request-level $CancelSchedule or $Cancel as appropriate.
Individual recipient cancellation is available only while the request is still an editable draft,
funding has not left Pending, the payment has not been sent, and another recipient payment remains.
Otherwise the call returns 409. For a Scheduled request, cancel the schedule
first, then submit the revised request for approval again. Once the request has left the draft
stage, contact DirecFunds support and provide the request and recipient references. A Pending payout
alone does not establish that the bank has not received an instruction. Do not reissue the payment
until its outcome and any collected funding have been reconciled.
Status remains authoritative on each resource. Granular integrations may use the compact
/Disbursement/{id}/Status and /PayOut/{id}/Status aliases, or list all pay outs
for one disbursement with /PayOut/Disbursement/{id}. The append-only
/Events feed records business lifecycle changes; /AuditLog separately
records the calling integration's HTTP activity metadata when its credential has Audit.Read.
Use Test-only /Sandbox scenarios for deterministic outcomes. Use webhook subscriptions only
when GET /Integration reports features.webhooks: true. Treat notifications as
wake-up hints, use company-wide /DisbursementRequests/Events only for controlled catch-up,
and re-read the request plus reconciliation resource for authoritative state.
Disbursement Lifecycle
The Experience API exposes related but intentionally different status models. Use the model belonging to the resource you read; do not translate one status by guessing from another.
Granular Disbursement status
The advanced /Disbursement resource moves through the following states:
| Status | Meaning |
|---|---|
| Initialized | Disbursement created; Pay Ins and Pay Outs can be assembled. |
| Pending | The requester submitted the disbursement for approval. |
| PendingInfo | Sent, but waiting on funding input before routing can continue: an outstanding consumer or payer funding request, or business-funding identity verification. |
| Routing | DirecFunds is preparing the approved payment instructions for processing. |
| RequiresInconclusiveOverride | Verification is held for review. An account override is possible only when sanctions screening is independently clear and the rail and account result are eligible. |
| Verified | Amounts match and the disbursement has been approved; ready to send. |
| Canceled | The disbursement was canceled before completion. |
| Rejected | Disbursement was rejected during the approval process. |
| Processing | Sent to the payment network; transfers are in flight. |
| Completed | All Pay Outs have settled successfully. |
| Failed | One or more Pay Outs failed after submission. |
Disbursement Request status
The primary /DisbursementRequests aggregate reports the outcome of the complete closing across
all recipient payments:
| Status | Meaning |
|---|---|
Initialized | Created and staged, but not yet submitted for approval. Call $SubmitForApproval when it is ready. |
PendingApproval | Waiting for an authorized approver who is different from the requester when two-party approval applies. |
Scheduled | Approved, verified, and held until scheduledFor. DirecFunds automatically releases it for routing at or after the due time; the partner does not call $VerifyAndSend again. |
Processing | Approved and released: DirecFunds is routing it, waiting on funding (including a funding-input or good-funds wait), or a funding or recipient-payment leg is in flight. |
Completed | Every recipient payment completed successfully. |
PartiallyCompleted | At least one recipient payment completed while another failed or was rejected. A payment withdrawn before dispatch does not count when its funding share was removed and it has no bank dispatch or settlement evidence. Other canceled payments remain visible for review. |
NeedsAttention | The closing has an exception that requires an allowed recovery action or operational review. |
Rejected | The closing was rejected before successful submission. |
Canceled | The closing was canceled without resending any completed payment. |
Recipient Payment status
Every recipientPayments[] item reports its own normalized status independently:
Pending, Submitted, Processing, Completed,
Failed, Rejected, Canceled,
PendingAccountActivation, or NeedsAttention. Read its failure details, attempt
history, and allowedNextActions before any recovery. A completed recipient payment is never resent
when a different payment is recovered.
Pay Out Transfer Statuses
Each Pay Out also has its own transfer status that updates as the payment progresses through the network.
The granular transferStatus has no separate pending value, so Processing also
covers a Pay Out that has not been submitted yet, including before approval. To tell them apart, read the
parent disbursement status (Initialized, Pending, or
Verified means nothing has been sent) or, for a bundled request, the recipient payment's
provider reference and attempt history.
| Status | Meaning |
|---|---|
| PendingAccountActivation | Target bank account pending activation before the transfer can proceed. |
| Processing | Not final. Either not yet submitted (including before approval) or accepted and still in progress at the bank; check the parent disbursement status to know which. |
| Submitted | Accepted by DirecFunds' bank for processing. It does not mean the receiving bank has confirmed the payment. |
| Inconclusive | Further review is required before a final transfer result is known. |
| Completed | Funds have settled. |
| Rejected | Transfer rejected by the receiving bank or payment network. |
| Canceled | Transfer canceled before processing. |
| Failed | Transfer failed after submission. |
Pay Out Verification Statuses
A Pay Out also reports the account-verification result separately as Unverified,
Verified, Inconclusive, Failed, NotRequired, or
ManuallyVerified. ManuallyVerified means an authorized administrator recorded
affirmative out-of-band evidence; it does not mean the provider changed its earlier result and it does
not mean money was sent.
Verification status describes destination-account checks; transferStatus describes the actual
movement of funds.
Creating a Disbursement in the Portal
/DisbursementRequests API calculates and creates that Pay In from the recipient-payment
total. Advanced granular integrations create the PayIn resource explicitly. All three represent the same
incoming funding leg.
1. Start the Disbursement
In the portal, go to Disbursements → Request Disbursement and select:
- The branch the disbursement is being created under
- The funding source — an account that is ready for payments and available to the current user
The signed-in user becomes the requester. When approval is required, an eligible approver receives the request in My Reviews.
2. Define the Pay In
A Pay In defines the source account and total amount being drawn down. The portal creates it from the selected funding source and calculates its amount from the payout total, so the user does not enter the amount twice. API integrations provide:
- The source bank account — your escrow/IOLTA account on file
- The payment rail supported for incoming funds
- The total amount to be drawn
3. Add Pay Outs
Each Pay Out represents one transfer to a specific recipient. Add a Pay Out for each party being paid at closing — for example:
- Loan payoff to the lender
- Seller proceeds to the seller's bank
- Realtor commission to the listing agent
- Title agency commission
For each Pay Out you will need:
- Payment rail — Wire, ACH, Same Day ACH, Instant Payment, or FedNow, subject to discovery
- Amount
- Transaction purpose — Loan Payoff, Seller Proceeds, Realtor Commission, Funds to Close, Earnest Money, Closing Related Fees, Retainer, Title Agency Commission, or Other
- Destination — bank details for the selected rail, or a saved recipient
- Recipient details — name and rail-specific identity evidence described above; date of birth and phone are required for a Person on verified rails
RTP and FedNow require the destination routing number to be eligible for the selected network.
The portal checks instant-rail eligibility before final review and checks it again when the
approval request is submitted. A failed check creates no new request and does not substitute
another rail. Review the named recipient's routing number with the recipient's bank, then
deliberately choose an available delivery method. A successful preview is advisory because
eligibility can change before submission. API clients can use
POST /DisbursementRequests/$Validate for the same advisory check; atomic create
performs its own final validation.
Verifying a Disbursement
Once all Pay Ins and Pay Outs are added, the disbursement must be verified before it can be sent. Verification confirms:
- Pay In and Pay Out amounts match exactly
- All recipient and account details pass preflight checks
- The disbursement meets the company's approval strategy requirements
For Two Party Approval, verification requires the approving user to review and sign off. The system enforces that the requester and approver are different users — one person cannot both create and approve the same disbursement.
If verification is inconclusive, the disbursement is held for review. A transient provider
issue may qualify for a bounded fresh verification; persistent missing evidence requires
investigation before a corrected request is resubmitted. An account-verification override
cannot resolve missing or adverse sanctions screening. Potential matches require independent
Compliance review, and only an eligible account outcome with separately cleared sanctions
can be considered for a documented administrator override. The one exception is an
Indeterminate screening result, where the provider returned no decision: an administrator
override may release it only together with a recorded manual OFAC check, which is then stored as cleared
by review. Potential matches, blocks, and payouts that were never screened stay blocked.
Held-result choices
The administrator review screen explains why each payout stopped and presents only the actions allowed by
the current evidence. An Inconclusive or Unverified payout on a known rail with
separately cleared sanctions may offer both of these distinct choices:
-
Record manual verification — select an approved out-of-band method, enter an opaque
case or evidence reference (never bank-account data), explain the decision, and confirm the independent
check. This records a
ManuallyVerifiedaudit fact and returns the request to normal approval. It does not send money, erase the provider result, or bypass send-time controls. - Admin override and send — make a documented immediate-release exception. This can send money, so the screen displays stronger warnings. Wire, RTP, and FedNow also require an explicit acknowledgement that the payout may be irreversible and unrecoverable after routing.
Failed verification, an unknown rail, and unresolved sanctions (a potential match, a block, or
no screening result) are not eligible for either action. An Indeterminate screen is eligible
only for Admin override and send, and only with a recorded manual OFAC check. Otherwise
correct or reject the request, or complete the separately authorized Compliance review. These are
administrator operational workflows in the DirecFunds portal; partner integrations observe the resulting
status and append-only events and do not synthesize either decision from a provider response.
Sending a Disbursement
In the portal, the approver's confirmed approval verifies and sends the request as one guided action. API integrations may call Verify and Send separately, or use VerifyAndSend when the approval model allows it. An immediate request moves to Processing. A future request moves to Scheduled and DirecFunds releases it automatically when due. Payment instructions are already locked once the disbursement is submitted for approval, and after sending, funds move through the payment network according to the rail selected for each Pay Out.
When billing payment-method enforcement is enabled, Verify and VerifyAndSend
first check that the company has a billing payment method on file. A missing chargeable payment method returns 422 with
errorCode: BILLING_PAYMENT_METHOD_REQUIRED; nothing is verified or sent. A company administrator
must save a card or US bank account under Manage → Billing in the Portal before you try again
with a new idempotency key.
Funds Flow Reference
Consumer Funds to Close
When a consumer is funding a closing digitally:
- The closing agent selects Request Consumer Funding, enters the amount and payer details, chooses the destination escrow account, and chooses the funding method: Same Day ACH debit or wire transfer.
- The consumer receives a secure link and confirms the funding request in the Consumer Portal. For a Same Day ACH debit they enter their bank account details; for a wire they receive wire instructions.
- For a Same Day ACH debit, DirecFunds verifies the consumer's account information.
- Funds move from the consumer to the DirecFunds holding account by the chosen method, subject to bank and cutoff eligibility.
- When a consumer processing fee was quoted, the consumer pays it at checkout, and the funding request is marked paid only after both the bank receipt and the fee are confirmed.
- After funding is received, funds route from the holding account to the selected escrow/IOLTA account via Wire.
- The business user tracks the request through Sent → Confirmed → Submitted → Paid → Closed in the portal.
B2B Mortgage Loan Payoff Wire
For post-close disbursements from escrow:
- The closing agent specifies the funding account, amounts, and wire instructions in the portal.
- The approver reviews all instructions before anything moves.
- DirecFunds verifies destination accounts and runs sanctions and fraud prevention checks. A held verification result stops the request before any funds are drawn.
- After verification passes and the request is sent, a reverse wire (or an authorized Same Day ACH debit) draws funds from the Escrow/IOLTA account to the DirecFunds holding account.
- Once funding is received, wires are sent to each destination — loan payoff, seller proceeds, agents, and others.
- If a payout is held or fails after funding has already occurred, Payments Operations reconciles the held funds and follows the documented exception process.
Common Questions
Initialized,
the original requester (who must still have request permission for the branch) can add Pay Outs
and edit their payment instructions. A Pay Out's amount cannot be changed by an edit, and direct
Pay Out deletion is refused with 405; to change amounts, cancel or remove the
disbursement and create a corrected one. After $Request submits it for approval, the
payment instructions are locked. A bundled /DisbursementRequests request has no edit
or append operation; cancel it before dispatch and create a new request instead.
Rejected or Failed. Read its
failure details and allowedNextActions. Recipient-payment $Retry and
$ReplaceDestination are currently capability-disabled. Reconcile the provider outcome
and use only a returned allowed action; never resend a recipient payment that already completed.
Use the event history and reconciliation response when escalating to DirecFunds support.