Integration partner implementation guide
Onboard a title company and fund its first closing
This guide identifies every handoff between an integration partner, the title company, and DirecFunds. It begins before a company has API credentials and ends when the closing is reconciled.
disbursementsEnabled: true before enabling live payments.
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 issue code
ProductNotEnabled, bundled create returns 400 (Preflight) carrying that code, and the
granular POST /Disbursement returns a bare 403 Forbidden. 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.
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. The gateway validates Wire addresses
during validate/create. $Validate also returns a preflight assessment (create does not);
read preflight.findings for missing recipient identity input. Verification remains authoritative:
a successful $Validate does not guarantee $VerifyAndSend can route the request.
Billing payment method. When billing payment-method enforcement is enabled, the API refuses $Verify and
$VerifyAndSend with 422
BILLING_PAYMENT_METHOD_REQUIRED
until a company administrator saves a chargeable card or US bank account in the Portal under
Manage → Billing → Payment method. Onboarding readiness does not check billing, so
disbursementsEnabled: true alone does not prove an approval can proceed.
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.
Responsibilities
| Work | Integration partner | DirecFunds | Title company |
|---|---|---|---|
| Customer experience | Starts and tracks onboarding | Provides requirements and status | Completes requested information |
| Business and owner data | Collects and securely transmits the structured data | Validates and performs KYB/KYC | Provides and certifies the data |
| Agreements and funding authorization | Presents the current DirecFunds-approved forms and retains signature evidence | Supplies approved terms, validates evidence, and records completion | Authorized signer accepts |
| Branches, users, and permissions | Creates and synchronizes them through the Experience API | Enforces company ownership and payment authority | Names authorized staff |
| Trust account | Sends it securely once and stores the returned ID | Creates, verifies, enables, and masks it on readiness reads | Provides account information and authorization |
| Closing instructions | Sends the complete bundled request and explicit rails | Validates, creates atomically, routes, tracks, and reconciles | Requester and approver authorize |
Phase 1: pre-API company onboarding
Experience API credentials are company-scoped, so this phase happens before the partner can call the company API. For partner-managed onboarding, the partner sends the onboarding package through the agreed secure channel. Never use email, chat, logs, or support tickets for full account numbers, identification numbers, signed forms, or secrets.
A company registering itself can instead use the Test registration portal or the Production registration portal. Provide a separate email address and phone number for each control person and beneficial owner. The registration confirmation records the company submission; the administrator must then use the emailed activation link to verify the address and create a password, and the agreement signer receives the MSA. On Basic information, select every product the company intends to use, including Due diligence payments when that is its only purpose. The registration summary shows the requested products before submission. Continue with the readiness checks below before enabling money movement.
If the company registered before Due diligence payments was offered and now needs only that product, email DirecFunds support at support@direcfunds.com with the existing company ID and its product request. Keep the existing account and administrator access; do not register a second company. DirecFunds reviews current product access and payment activity before correcting the request. Product access stays disabled until the required verification, agreement, product approval, and production readiness checks are complete.
What the integration partner must collect and send
- Legal business name, DBA names, EIN/TIN, NAICS code, nature of business, business address, and phone.
- Entity type, incorporation and primary-business countries, annual revenue, and applicable public-company, CIP, and money-services answers.
- The control person's name, title, date of birth, address, phone, email, citizenship, and identification details.
- Each required beneficial owner's identity details and ownership percentage.
- The company administrator, agreement signer, and the person certifying the submission.
- The signed MSA and funding authorization, including form version, signer, timestamp, and immutable signature evidence.
- A stable partner customer reference used to correlate the onboarding package.
- The products the customer requests. Identify a due diligence-only company explicitly; do not collect a company source account merely to satisfy a business-disbursement checklist.
- Confirmation that a company administrator will save a chargeable card or US bank account under Manage → Billing in the Portal. The partner does not collect or transmit payment-method details.
What DirecFunds does
- Creates the company record and default approval strategy.
- Runs business and owner verification and resolves any manual-review findings.
- Records the completed agreements.
- Activates the company's Portal access so a company administrator can create its API credentials (Phase 2). DirecFunds does not send client IDs or secrets.
- Links each integration created in the Portal to exactly one authorized company context.
Phase 2: authenticate and confirm the tenant
- A company administrator creates the credentials in the Portal under Manage → API Integration → Enable API integration: the Test portal for Test, the Production portal for Production. The client secret is shown only once; move the client ID and secret straight into your secret manager.
- Obtain a client-credentials token with those values.
- Call
GET /v1/Integration. Confirm the company, environment, scopes, and features, includingfeatures.webhooks. - Call
GET /v1/Company. Confirm the company name, active flag, and approval strategy. - Persist the partner customer-to-DirecFunds
companyIdmapping.
GET /v1/Integration
GET /v1/Company
Note: stop onboarding if either response identifies an unexpected company or environment.
Rotation: Rotate API credentials in the Portal creates a new app registration. Both the client ID and the secret change, and the old credentials stop working immediately, with no overlap window. Have the deployment ready to take both new values before rotating.
Phase 3: create addresses and branches
- Create each reusable address with
POST /v1/Address. - Use the returned
addressIdwhen callingPOST /v1/Branch. - Store each partner office-to-
branchIdmapping.
POST /v1/Address
{
"address1": "100 Main Street",
"city": "Cincinnati",
"state": "OH",
"postalCode": "45202"
}
POST /v1/Branch
{
"name": "Cincinnati Closing Office",
"addressId": "ADDRESS_ID",
"active": true
}
Phase 4: create, assign, and verify the trust account
The partner sends the account once over TLS. DirecFunds returns a bankAccountId; use that opaque ID
from then on. Keep full bank values out of application logs and mask them in the user interface.
POST /v1/BankAccount
{
"bankName": "Example Bank",
"nickName": "Main Escrow Trust",
"beneficiary": "ABC Title Company LLC",
"accountNumber": "FULL_ACCOUNT_NUMBER",
"routingNumber": "ROUTING_NUMBER",
"depositAccountType": "Checking",
"addressId": "BANK_ADDRESS_ID"
}
A create only records the account. It does not prove ownership or enable money movement.
Assign it to a branch
Read the current document and retain its ETag:
GET /v1/Branch/BRANCH_ID/BankAccounts
Replace the complete assignment with concurrency and retry protection:
PUT /v1/Branch/BRANCH_ID/BankAccounts
If-Match: "ETAG_FROM_GET"
X-Idempotency-Key: NEW_UUID
{
"bankAccountIds": ["BANK_ACCOUNT_ID"]
}
- The body is the complete desired list, not an incremental add.
- An unknown or other-company account returns
422. - A stale ETag returns
412; fetch and retry with a fresh ETag. - If the response is lost, do not blind-retry: a successful first attempt changed the ETag, so a same-key retry returns
412. Re-GETthe document and compare before re-sending.
Verify it
POST /v1/BankAccount/BANK_ACCOUNT_ID/$Verify
X-Idempotency-Key: NEW_UUID
The response reports verificationStatus, supportsAch, supportsWire,
and wireDrawdownReady (true when the account can fund managed disbursements through reverse wire).
GET /v1/BankAccount/BANK_ACCOUNT_ID/Readiness reports the same account's funding readiness,
branch assignment, and blocking finding codes.
Unverified: recorded but not yet verified; call$Verify.Active: ownership verification passed. An account withsupportsAch: trueis eligible for managed Same Day ACH debit funding once assigned to an active payment scope.Drawdown: verification passed and reverse-wire drawdown setup is also complete.Verifying: another verification is in progress; poll readiness rather than submitting repeatedly.InconclusiveorRestricted: stop and follow the returned/onboarding finding.Disabled: the account cannot be used; contact DirecFunds support rather than re-verifying.
Wire PayIns additionally require the signed drawdown authorization and provider repeat-code mapping.
Managed source-account PayIns may use reverse wire or Same Day ACH debit. Same Day ACH requires
achDebitAuthorizationAccepted: true; standard ACH remains available for recipient payouts only.
Phase 5: create users and payment authority
POST /v1/User
{
"givenName": "Bob",
"surname": "Doe",
"email": "bob@example.com",
"phone": "5551234567"
}
Creating a user does not authorize money movement. When permission automation is enabled, read and then replace the separate permission document:
GET /v1/User/USER_ID/Permissions
PUT /v1/User/USER_ID/Permissions
If-Match: "ETAG_FROM_GET"
X-Idempotency-Key: NEW_UUID
{
"branches": [{
"branchId": "BRANCH_ID",
"canRequest": true,
"canApprove": false,
"bankAccountIds": ["BANK_ACCOUNT_ID"]
}]
}
Under Two Party Approval, configure a requester and a different approver on the same branch and source
account. Ordinary POST /User and PUT /User/{id} calls cannot change payment authority.
GET /v1/User/USER_ID/Readiness reports whether that user can request or approve end to end and
which grant is missing.
Upcoming: DirecFunds is adding per-user payment-type permissions. Once they are switched on,
a requester and an approver must each be granted every payment type a request uses. A company administrator
grants them in the Portal, and the API reports them read-only as allowedPaymentRailIds on the
user. Check the changelog for status.
User removal is a recoverable deactivation. Read the active user and retain its ETag before
sending DELETE /v1/User/{id} with If-Match. The deactivated user disappears from
list reads and returns 404 by id. Retain the id and required profile fields if you may need to
restore access; reactivate with PUT /v1/User/{retainedId}, the complete required profile, and
"active": true. Reactivation does not require If-Match. Do not send
"active": false; use DELETE to deactivate.
Phase 6: use one readiness decision
GET /v1/Onboarding/Readiness
On Test, an administrator can use the self-service sandbox or
POST /v1/Sandbox/$Prepare to converge existing Test resources before checking readiness again.
Production has no preparation endpoint.
GET /v1/Onboarding/Checklist returns the same pipeline as ordered steps, each with its completing
endpoint and blocking finding codes, suitable for a setup wizard. POST /v1/Onboarding/$Provision
converges the partner-actionable steps (branch, trust account, branch assignment, users, payment authority) in
one call; it is not transactional, so read each step's outcome.
The response combines the setup checks and returns only masked bank-account display values:
{
"status": "Ready",
"disbursementsEnabled": true,
"companyActive": true,
"kybKycStatus": "Passed",
"agreementsComplete": true,
"branchesConfigured": true,
"usersConfigured": true,
"permissionsConfigured": true,
"bankAccounts": [{
"bankAccountId": "BANK_ACCOUNT_ID",
"displayName": "Main Escrow Trust ••••0042",
"verificationStatus": "Drawdown",
"branchIds": ["BRANCH_ID"],
"achReady": false,
"wireReady": true
}],
"findings": []
}
The partner must use disbursementsEnabled as the go/no-go value for setup
(status is Ready when the findings list is empty, otherwise
ActionRequired). When it is false, branch on the stable findings[].code and
show its human-readable message. Do not attempt to reconstruct KYB/KYC decisions from raw evidence.
Readiness does not check the billing payment method; that is enforced at approval (see
Payment prerequisites above).
findings[].code | Meaning |
|---|---|
COMPANY_NOT_ACTIVE | DirecFunds has not activated the company. |
KYB_KYC_NOT_PASSED | Business and owner verification is not complete. |
AGREEMENTS_INCOMPLETE | Required company agreements have not been completed. |
NO_ACTIVE_BRANCH | Create or activate at least one branch. |
NO_SOURCE_ACCOUNT | Create at least one trust account. |
SOURCE_ACCOUNT_NOT_VERIFIED | At least one trust account must complete bank verification. |
SOURCE_ACCOUNT_NOT_ASSIGNED | Assign at least one verified trust account to an active branch. |
FUNDING_NOT_READY | No trust account is ready for reverse wire or Same Day ACH debit funding. |
NO_ACTIVE_USER | Create or activate the users who will request and approve disbursements. |
PAYMENT_AUTHORITY_INCOMPLETE | Assign requester and approver authority for a ready trust account and branch. |
Phase 7: create the closing bundle
Funding: Wire/reverse-wire or SamedayAch debit. Validate and create, approve and verify, wait for good funds, then observe routing and settlement. Inspect allowedNextActions for recovery; retry and destination replacement are reserved.
- Call
GET /v1/DisbursementRequests/Capabilitiesinstead of hard-coding rails and limits. - Build one request with the branch, source-account ID,
WireorSamedayAchfunding rail, requester, and every recipient payment. ForSamedayAch, sendachDebitAuthorizationAccepted: true. StandardAchfunding is rejected with400; both ACH rails remain available for recipient payouts. - Call
POST /v1/DisbursementRequests/$Validate. This creates nothing and moves no money. It returns200even whenvalidisfalse. - Correct every returned issue, and resolve
preflight.findingsthat block verification. - Call
POST /v1/DisbursementRequestswith a company-uniqueclientReferenceand UUID v4 idempotency key.
DirecFunds calculates the PayIn as the sum of all recipient amounts and atomically creates the disbursement, PayIn, immutable account snapshots, and PayOuts. If any part is invalid, none of the bundle is created.
orderId. Send several selected Orders as separate, non-atomic calls and report each
result independently. One Order may create multiple requests as transactions become ready, but each
needs a distinct clientReference; an existing request cannot be appended to.
submitForApproval: true, creation enters PendingApproval. With
false, it remains Initialized until $SubmitForApproval.Phase 8: approve and start funding
POST /v1/DisbursementRequests/REQUEST_ID/$VerifyAndSend
X-Idempotency-Key: NEW_UUID
{
"approverUserId": "APPROVER_USER_ID",
"reviewConfirmed": true
}
DirecFunds rechecks compliance, account readiness, authority, recipient verification, rail rules, and cutoffs.
When billing payment-method enforcement is enabled, it also confirms the company has a chargeable billing
payment method; without one, or if billing cannot be confirmed right now, the call returns
422 BILLING_PAYMENT_METHOD_REQUIRED before verification runs.
- Wire funding uses the trust account's pre-authorized reverse-wire/drawdown arrangement.
- Managed source-account funding uses retained reverse-wire authorization or an explicitly authorized Same Day ACH debit. Standard ACH remains payout-only.
- The PayIn amount equals the sum of the recipient payments.
- Each PayOut follows the recipient rail the partner selected; DirecFunds does not silently substitute rails.
For an immediate request, 202 Accepted means the API action was accepted; inspect request.status and allowedNextActions because failed/inconclusive verification does not route money. With a future
scheduledFor (send one only when Capabilities reports supportsScheduling: true),
the call instead verifies and holds it in Scheduled.
DirecFunds automatically releases it for routing at or after the due time; no second partner
call is required. Use $CancelSchedule to clear the schedule and return to
PendingApproval, or request-level $Cancel to abandon the entire
undispatched request. Acceptance never means the money has settled.
Phase 9: signed events, status, reconciliation, and audit
POST /v1/DisbursementRequests/WebhookSubscriptions
GET /v1/DisbursementRequests/REQUEST_ID
GET /v1/DisbursementRequests/REQUEST_ID/Events?after=CHECKPOINT
GET /v1/DisbursementRequests/REQUEST_ID/Reconciliation
GET /v1/AuditLog/TRACE_ID
Webhooks are enabled per integration and depend on the current integration configuration. Check
features.webhooks in GET /v1/Integration. When it is false, the subscription
endpoints return 404 "Webhook Capability Unavailable"; ask DirecFunds support to enable webhooks for
the integration and use the event feed meanwhile. Webhooks are emitted only for bundled requests created with
POST /DisbursementRequests. The event feed is the authoritative record.
- When
features.webhooksistrue, register a public HTTPS callback witheventTypes: ["*"]before certification. Subscribe before creating requests: deliveries are queued only for subscriptions that already exist. OmitsigningSecretto receive a generated one in the create response only, store it securely, then prove signature validation with a controlled delivery. - Verify the HMAC signature before parsing, reject stale timestamps, de-duplicate by webhook event id, coalesce bursts by resource id, and process the highest sequence.
- After a notification, read the request and reconciliation resources for authoritative financial state. Treat event type and
resource.statusas wake-up hints. - Preserve unknown lifecycle status strings, take no money-moving action based on them, refresh authoritative state, and route unresolved values to operations. Treat
Canceledas terminal non-success with no automatic retry or resend. - Persist the event feed's own
nextCursorand use it to catch up after an outage or identified delivery gap. A webhooksequenceis not anaftervalue for the feed. Where webhooks are not enabled, read open requests and their feed instead. - Use reconciliation to confirm requested, funded, settled, failed, and exception totals.
- The current baseline reports
supportsPartialFailureRecovery: false. Retry and destination replacement are reserved; cancel only whenallowedNextActionsreturns it, or route the exception to operations. - Never resend a completed recipient payment.
- Capture
X-Trace-Idfrom every response; share it with Support without sharing payment payloads.
What changed from the granular integration
| Before | Recommended now |
|---|---|
| One client operation could be modeled as a closing-wide bundle. | Map each Order disbursement to its own request. Multi-Order selection fans out with per-request results; one Order may create multiple non-appendable requests. |
| The partner assembled Disbursement, Target Accounts, PayIn, and every PayOut separately. | One POST /DisbursementRequests creates the complete graph atomically. |
| Validation happened across multiple writes. | $Validate checks the complete closing without creating data. |
| Setup readiness required manual coordination. | GET /Onboarding/Readiness returns one go/no-go decision and stable findings. |
| Branch/account setup was not exposed as a safe partner document. | Branch bank-account assignments use ETags, company validation, and idempotent replacement. |
| Bank verification was operationally separate. | POST /BankAccount/{id}/$Verify reports verification and bank rail capabilities; capability endpoints remain authoritative for usable funding directions. |
| Support correlation depended on manual searching. | GET /AuditLog/{traceId} exposes sanitized request metadata. |
| Recovery behavior was inferred from status. | Capabilities and allowedNextActions fail closed. The initial baseline reserves retry and destination replacement; only an explicitly returned cancellation action may be used. |
The granular APIs remain supported for advanced integrations. One granular operation has been withdrawn:
direct DELETE /PayOut/{id} now returns 405 to preserve funding totals and audit
history; remove or cancel payments through the disbursement instead.
Go-live checklist
- Test and Production credentials are stored separately and never used in browser code.
- The authenticated company and environment are checked at startup.
- The signed onboarding package and authorization evidence were delivered securely.
GET /Onboarding/ReadinessreturnsdisbursementsEnabled: true.- The Business disbursements product is enabled for the company.
- A company administrator has saved a chargeable card or US bank account under Manage → Billing, and a Test approval has been seen to succeed; the integration handles
422 BILLING_PAYMENT_METHOD_REQUIREDby telling the company to update its billing payment method. - The Test-hosted OpenAPI document lists Test first, publishes
callbacks.partnerEvent, and its SHA-256 is retained with certification evidence. - The generated client models lifecycle statuses as extensible strings, and Test proves that a synthetic unknown value is preserved, does not crash processing, does not move money, and reaches operational review.
- Two-party requester and approver rules have been tested.
- The partner's retry handling is honest about lost responses: money actions are retried with the same idempotency key and exact same body, and if same-key retries keep returning
5xx(the recorded outcome is replayed for 48 hours) the partner stops, reads the request back byclientReference, and contacts support with theX-Trace-Id. For a lost branch bank-account replacement, re-read the document and compare state: a blind same-key retry returns412when the first attempt already applied. A same-key retry of a permission replacement replays the original success. - Event-history catch-up, reconciliation, fail-closed exception handling, and
X-Trace-Idlogging have been tested, plus signed webhook delivery, de-duplication, and burst coalescing when webhooks are enabled for the integration. - Negative Test scenarios confirm that no money moves on validation, compliance, authority, or cutoff failures.