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.

The simple model: The integration partner gathers the customer information and manages the title-company experience. DirecFunds makes the compliance, bank-verification, funding-readiness, and money-routing decisions. The partner must wait for disbursementsEnabled: true before enabling live payments.
Choose the product during registration. A company may request Business disbursements, Consumer funding, Recurring payments, Due diligence payments, or a combination. DirecFunds reviews and enables each requested product separately after company verification and agreements. A request does not itself grant payment access. A due diligence-only company uses the Portal's Due diligence workflow: the buyer funds an approved property payment, so the company does not need to add its own source bank account for that workflow. Company identity, billing, authorized users, agreements, and recipient verification still apply. The trust-account and bundled disbursement steps in this guide apply when Business disbursements is enabled. Recurring payments use that same company source account and require Business disbursements to be selected and approved as well.
Seller preparation: A brokerage can invite a seller before a buyer or executed contract exists. An active agent with branch request permission first completes DirecFunds' LexisNexis check; current verification is reused across transactions. The seller completes identity and receiving-account checks through a private invitation. The agent must later record and attest to the executed contract, add the buyer and amount, and submit the payment for independent approval. Seller preparation cannot create a buyer funding request.

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

WorkIntegration partnerDirecFundsTitle company
Customer experienceStarts and tracks onboardingProvides requirements and statusCompletes requested information
Business and owner dataCollects and securely transmits the structured dataValidates and performs KYB/KYCProvides and certifies the data
Agreements and funding authorizationPresents the current DirecFunds-approved forms and retains signature evidenceSupplies approved terms, validates evidence, and records completionAuthorized signer accepts
Branches, users, and permissionsCreates and synchronizes them through the Experience APIEnforces company ownership and payment authorityNames authorized staff
Trust accountSends it securely once and stores the returned IDCreates, verifies, enables, and masks it on readiness readsProvides account information and authorization
Closing instructionsSends the complete bundled request and explicit railsValidates, creates atomically, routes, tracks, and reconcilesRequester 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

  1. Creates the company record and default approval strategy.
  2. Runs business and owner verification and resolves any manual-review findings.
  3. Records the completed agreements.
  4. 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.
  5. Links each integration created in the Portal to exactly one authorized company context.
Current boundary: the pre-company KYB/KYC package and signed-document upload are not Experience API operations. Treat this as an explicit secure onboarding handoff; do not invent a company ID in a request body or reuse one customer's credentials for another company.

Phase 2: authenticate and confirm the tenant

  1. 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.
  2. Obtain a client-credentials token with those values.
  3. Call GET /v1/Integration. Confirm the company, environment, scopes, and features, including features.webhooks.
  4. Call GET /v1/Company. Confirm the company name, active flag, and approval strategy.
  5. Persist the partner customer-to-DirecFunds companyId mapping.
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

  1. Create each reusable address with POST /v1/Address.
  2. Use the returned addressId when calling POST /v1/Branch.
  3. Store each partner office-to-branchId mapping.
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-GET the 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 with supportsAch: true is 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.
  • Inconclusive or Restricted: 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[].codeMeaning
COMPANY_NOT_ACTIVEDirecFunds has not activated the company.
KYB_KYC_NOT_PASSEDBusiness and owner verification is not complete.
AGREEMENTS_INCOMPLETERequired company agreements have not been completed.
NO_ACTIVE_BRANCHCreate or activate at least one branch.
NO_SOURCE_ACCOUNTCreate at least one trust account.
SOURCE_ACCOUNT_NOT_VERIFIEDAt least one trust account must complete bank verification.
SOURCE_ACCOUNT_NOT_ASSIGNEDAssign at least one verified trust account to an active branch.
FUNDING_NOT_READYNo trust account is ready for reverse wire or Same Day ACH debit funding.
NO_ACTIVE_USERCreate or activate the users who will request and approve disbursements.
PAYMENT_AUTHORITY_INCOMPLETEAssign 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.

  1. Call GET /v1/DisbursementRequests/Capabilities instead of hard-coding rails and limits.
  2. Build one request with the branch, source-account ID, Wire or SamedayAch funding rail, requester, and every recipient payment. For SamedayAch, send achDebitAuthorizationAccepted: true. Standard Ach funding is rejected with 400; both ACH rails remain available for recipient payouts.
  3. Call POST /v1/DisbursementRequests/$Validate. This creates nothing and moves no money. It returns 200 even when valid is false.
  4. Correct every returned issue, and resolve preflight.findings that block verification.
  5. Call POST /v1/DisbursementRequests with a company-unique clientReference and 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.

One request is one independent Order disbursement. DirecFunds has no 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.
No money moves when the bundle is created. With submitForApproval: true, creation enters PendingApproval. With false, it remains Initialized until $SubmitForApproval.

Use the Quickstart for the complete copy-and-paste request.

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.webhooks is true, register a public HTTPS callback with eventTypes: ["*"] before certification. Subscribe before creating requests: deliveries are queued only for subscriptions that already exist. Omit signingSecret to 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.status as 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 Canceled as terminal non-success with no automatic retry or resend.
  • Persist the event feed's own nextCursor and use it to catch up after an outage or identified delivery gap. A webhook sequence is not an after value 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 when allowedNextActions returns it, or route the exception to operations.
  • Never resend a completed recipient payment.
  • Capture X-Trace-Id from every response; share it with Support without sharing payment payloads.

What changed from the granular integration

BeforeRecommended 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/Readiness returns disbursementsEnabled: 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_REQUIRED by 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 by clientReference, and contacts support with the X-Trace-Id. For a lost branch bank-account replacement, re-read the document and compare state: a blind same-key retry returns 412 when 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-Id logging 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.