API Integration Guide

Start with the integration checklist, then use this guide for the detailed steps.

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.

Supported payout rails and managed company funding directions
RailRecipient payoutManaged company fundingEnvironment availability
ACHSupportedPayout onlyCheck authenticated capabilities
FedNow ServiceSupportedPayout onlyCheck authenticated capabilities
Real Time PaymentSupportedPayout onlyCheck authenticated capabilities
Same Day ACHSupportedSupportedCheck authenticated capabilities
Wire TransferSupportedSupportedCheck 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.

For developers integrating title software or another partner platform directly with the DirecFunds Experience API.

The API Reference is the source of truth for request and response schemas. You can also import the OpenAPI 3.0 JSON document into your tooling. New integrations should run the Experience API Quickstart before using the advanced granular walkthrough below. New implementers should first follow the Partner Onboarding and Disbursement Guide for the company, trust-account, user, permission, and readiness sequence.

Payment prerequisites and funding settlement

The company must have the Business disbursements product enabled independently of onboarding readiness. Without it, bundled POST /DisbursementRequests/$Validate returns 200 with valid: false and issue code ProductNotEnabled, bundled POST /DisbursementRequests returns a 400 Preflight problem carrying that code, and 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.

Billing payment method. When billing payment-method enforcement is enabled, the API refuses $Verify and $VerifyAndSend with 422 BILLING_PAYMENT_METHOD_REQUIRED (Problem Details type BillingPaymentMethodRequired) until a company administrator saves a chargeable card or US bank account on the Billing page of the DirecFunds portal. GET /Onboarding/Readiness does not check billing, so a ready company can still receive this refusal. If the problem detail says to try again later, the billing check was temporarily unavailable: no company action is needed, so retry later with a new X-Idempotency-Key. No money moves on either refusal.

Offer only rails returned by GET /PaymentRails and marked active: true in GET /DisbursementRequests/Capabilities. Zelle is unavailable in all environments. 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. Bundled $Validate also returns a preflight assessment (create does not): read it separately from valid. InputRequired lists incomplete recipient identity evidence in preflight.findings[] (field path, paymentReference, resolutionOwner, nextAction); VerificationRequired means only that the locally checked input passed. Provider identity verification still happens at approval, 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. Instead of inline bank details, a recipient payment can pay a saved recipient: send a destination with type: "SavedRecipient" and only savedRecipientId (no bank-account fields); the inline recipient object is then optional. A changed saved-recipient bank account has a 24-hour cooling period.

Overview

The DirecFunds Experience API is a RESTful API using OAuth 2.0 for authentication. All requests must include a bearer token obtained from the DirecFunds identity server.

EnvironmentBase URL
Productionhttps://api.direcfunds.com/v1
Testhttps://testapi.direcfunds.com/v1
Begin all development and testing against the test environment. Do not use production credentials for testing.

Versioning. The current contract version is v1, carried by the /v1 prefix in the base URL — path templates never repeat it (call /v1/DisbursementRequests, not /v1/v1/DisbursementRequests). Partner integrations should additionally pin the contract by sending X-Api-Version: 1.0 on every request (the api-version query parameter is an equivalent alternative). A future v2 with breaking changes will run side by side without affecting v1 callers.

Authentication

Step 1 — Generate API Credentials

Log in to the DirecFunds portal as an administrative user. Use the sidebar Manage menu, then Manage API Integration, and toggle the integration on. Your Client ID and Client Secret will be shown. Store both securely.

Step 2 — Request a Bearer Token

Send a POST request to the token endpoint with an application/x-www-form-urlencoded body. Start in Test. Production uses the separate direcfundsprod2 authority and a Production-specific credential pair and scope.

EnvironmentToken endpoint
Test https://direcfundstest2.b2clogin.com/direcfundstest2.onmicrosoft.com/B2C_1A_CLIENT_CREDENTIALS/oauth2/v2.0/token
Production https://direcfundsprod2.b2clogin.com/direcfundsprod2.onmicrosoft.com/B2C_1A_CLIENT_CREDENTIALS/oauth2/v2.0/token
POST https://direcfundstest2.b2clogin.com/direcfundstest2.onmicrosoft.com/B2C_1A_CLIENT_CREDENTIALS/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
scope=https://direcfundstest2.onmicrosoft.com/public/.default

A successful response returns an access_token along with expires_in (3600 seconds). Tokens are valid for 1 hour. Request a new one before it expires — do not wait for a 401 response.

{
  "access_token": "eyJ0eXAiOi...",
  "token_type": "Bearer",
  "not_before": 1765842893,
  "expires_in": 3600,
  "expires_on": 1765846493,
  "resource": "00000000-0000-0000-0000-000000000000"
}

Step 3 — Include the Token on Every Request

Pass the token in the Authorization header on every API call:

Authorization: Bearer eyJ0eXAiOi...

Scopes

Before credentials are created, an administrator selects only the permissions the integration needs in Manage API Integration. That selection is locked after provisioning so routine settings changes cannot silently broaden access. The current Experience API uses these scopes:

  • AccountMangement.Read and AccountMangement.Write for company, branch, address, bank account, and user resources.
  • Disbursement.Read, Disbursement.Write, and Disbursement.Send for the disbursement lifecycle.
  • Alerts.Read and Alerts.Write for alert resources.
  • Audit.Read for the calling integration's audit log.

The spelling AccountMangement is part of the existing authorization contract.

Object Hierarchy

Before integrating, understand how DirecFunds objects relate to each other:

Company
  ├── Branch       (one or more internal payment and permission scopes)
  │     ├── Bank Account  (source of funds, linked to branches)
  │     └── User          (employees with disbursement permissions)
  ├── Address      (used by Branch and Bank Account)
  ├── Phone Number (optional, attached to Branch)
  └── Disbursement Request  (primary closing-level API aggregate)
        └── Disbursement
              ├── Pay In        (draw-down from source account)
              └── Pay Out       (transfer to each recipient)
                    └── Target Account  (recipient's bank account)

A Disbursement is the payment object that bundles Pay Ins and Pay Outs. The total across all Pay Ins must equal the total across all Pay Outs before the disbursement can be verified and sent.

New partner integrations should use /DisbursementRequests as the primary closing-level aggregate. It creates the disbursement and all funding and recipient-payment legs atomically, then returns a normalized status for the closing and an independent status for every recipient payment. The granular /Disbursement, /PayIn, /PayOut, and /TargetAccount resources remain available for integrations that need to manage each resource separately.

DirecFunds does not model the partner's Order and exposes no orderId. Map one Order disbursement to one independent request containing 1 to 100 recipient payments. A multi-Order user action fans out as separate calls with separate references and idempotency keys; there is no atomic cross-request rollback. One Order may create multiple requests over time, but an existing request cannot be appended to and every request needs a company-unique clientReference.

In the primary request workflow, recipient destinations are supplied inline and DirecFunds creates their immutable snapshots atomically. In the advanced granular workflow, Target Accounts are separate objects for Pay Out destinations: create one first, then reference its ID when creating the Pay Out. Pay In holding-account routing is resolved by DirecFunds.

Filtering

Prefer the resource-specific query parameters documented on each collection endpoint (for example status or externalReference). Collection endpoints also accept legacy dynamic-filter JSON in the filter query parameter. GET request bodies remain accepted for compatibility, but integrations that still filter should use the query parameter because intermediaries may ignore a GET body. A filter is limited to 64 KiB, 64 properties, 128 conditions, and 512 values in total.

Filter TypeDescription
MatchWhole-string match; case-insensitive unless the condition sets "caseSensitive": true
ContainsString contains the value; case-insensitive unless the condition sets "caseSensitive": true
EqualNumeric equality
NotEqualValue does not equal the filter value
LessThanNumeric less than
LessThanEqualNumeric less than or equal
GreaterThanNumeric greater than
GreaterThanEqualNumeric greater than or equal

Example — get all addresses in Ohio:

{
  "state": [
    {
      "type": "Match",
      "value": "OH"
    }
  ]
}

Only the endpoint's documented response fields are filterable; property names are matched case-insensitively, but operator names in type are case-sensitive and must be spelled exactly as in the table. accountNumber and routingNumber are never filterable, even though masked values appear in responses. The gateway validates the filter before forwarding it and returns 400 with Problem Details type BadRequest and title Invalid Filter, naming the offending part, when the filter is not valid JSON, is not an object of property-name arrays, names a property that is not filterable on that endpoint, or uses an operator outside the table above. Pagination cursors are bound to the exact filter they were issued for: replaying a cursor with a different filter, or sending a malformed or outdated cursor, also returns 400 — restart the listing from the first page.

Recommended Partner Workflow

The following workflow is the recommended path for new server-to-server integrations. It keeps creation atomic and drives lifecycle and reconciliation from authoritative reads. Where webhook delivery is enabled for your integration, signed notifications tell you when to read; webhook delivery is enabled per integration and depends on the current integration configuration.

StepEndpointPurpose
DiscoverGET /IntegrationConfirm company context, effective permissions, environment, enabled features (including features.webhooks), and discovery links.
Subscribe (when enabled)POST /DisbursementRequests/WebhookSubscriptionsWhen features.webhooks is true, create a signed wildcard subscription and send $Test now: deliveries are queued only for subscriptions that already exist, and earlier events are not backfilled.
Check setupGET /Onboarding/ReadinessRequire the company, KYB/KYC, agreements, branch/account relationship, funding, users, and payment authority to be ready. Readiness does not check the billing payment method.
Discover railsGET /PaymentRailsRead current rail directions, Test availability, limits, finality, and required fields instead of hard-coding them.
PreflightPOST /DisbursementRequests/$ValidateValidate the complete closing payload without creating resources. It returns 200 even when valid is false: read valid, issues[], and the separate preflight assessment.
CreatePOST /DisbursementRequestsAtomically create the disbursement, funding leg, recipient destinations, and recipient payments.
Submit staged requestPOST /DisbursementRequests/{id}/$SubmitForApprovalMove a request created with approvalContext.submitForApproval: false from Initialized to PendingApproval.
Approve and sendPOST /DisbursementRequests/{id}/$VerifyAndSendApply two-party approval rules, verify the request, and submit it through one idempotent operation.
Automatic scheduled dispatchNo partner callAfter the one approval call, DirecFunds holds the request in Scheduled and automatically releases it for routing at or after scheduledFor.
Cancel before dispatchPOST /DisbursementRequests/{id}/$CancelSchedule, /$Cancel, or /$RejectClear a schedule and return to approval, abandon the whole undispatched request, or reject it as the approver.
Cancel one paymentPOST /DisbursementRequests/{id}/RecipientPayments/{paymentReference}/$CancelCancel one recipient payment only when its allowedNextActions includes Cancel.
TrackGET /DisbursementRequests/{id}Read the closing status, each recipient-payment status, failure details, attempts, and allowed next actions.
Catch upGET /DisbursementRequests/{id}/EventsRead append-only history after an identified gap or during an investigation.
ReconcileGET /DisbursementRequests/{id}/ReconciliationCompare completed, outstanding, and failed totals and identify exception ownership.

Use GET /DisbursementRequests/Capabilities for bundle feature discovery. GET /DisbursementRequests/Search?from={utc}&to={utc} finds requests in a required half-open UTC range (inclusive from, exclusive to, maximum 366 days), optionally filtered by status; follow its opaque nextCursor until it is null. GET /DisbursementRequests/Summary?from={utc}&to={utc} returns totals for the same required range. If one recipient payment fails, follow its allowedNextActions and act only on that payment. In the current baseline a payment can be canceled on its own only while the request is still an editable draft; after that no per-payment action is returned and DirecFunds support reconciles the payment; $Retry and $ReplaceDestination are reserved, are not returned as allowed actions, and return 409. Completed payments are never resent. When GET /Integration reports features.webhooks: true, manage signed subscriptions under /DisbursementRequests/WebhookSubscriptions. When features.webhooks is false, those webhook administration endpoints return 404 Webhook Capability Unavailable; ask DirecFunds whether delivery can be enabled for your integration. Webhooks are emitted only for bundled requests created with POST /DisbursementRequests, never for granular /Disbursement resources. The Events feed is the authoritative change record and webhooks are a low-latency signal. Without webhooks, read GET /DisbursementRequests/{id} for open requests at a modest interval within your rate limit, and use GET /DisbursementRequests/Events?after={checkpoint} to catch up across the company. Checkpoint the feed only with its own event id and nextCursor; a webhook sequence comes from a different counter and is not a valid after value.

For a future scheduledFor, one $VerifyAndSend approves and verifies the request, then moves it to Scheduled. DirecFunds automatically releases it for routing at or after the due time. The partner must not make a second approval or send call; use authoritative reads (and signed webhooks where enabled) to observe the transition.

The thirteen-step walkthrough below documents the advanced granular workflow. Existing integrations may continue to use it; the endpoints have not been removed. Granular disbursements do not produce webhooks.

Webhook Subscriptions and Event Catalog

Enabled per integration. Webhook delivery is enabled integration by integration and is available only when enabled for your integration. Check features.webhooks in GET /Integration; when it is false, the subscription endpoints return 404 Webhook Capability Unavailable. Webhooks cover only bundled requests created with POST /DisbursementRequests, not granular disbursements.

When GET /Integration reports features.webhooks: true, manage subscriptions with POST, GET, PUT, and DELETE on /DisbursementRequests/WebhookSubscriptions. Only a public HTTPS callbackUrl is required (no credentials, fragments, localhost, or private addresses). When features.webhooks is false, the same administration routes return 404 Webhook Capability Unavailable and should not be used for certification. Omit signingSecret and DirecFunds generates one and returns it in the create response only, or supply your own 32-to-512-character secret. Omit eventTypes to default to ["*"], or send one to 25 exact catalog values; "*" must be sent by itself. webhook.ping is diagnostic and cannot be subscribed to. Send a fresh UUID v4 X-Idempotency-Key for subscription creation, $Test, and $Redeliver. Reuse the same key and request after an uncertain result; DirecFunds returns the original recorded outcome, including a recorded failure, without repeating the side effect. Create the subscription before lifecycle testing: deliveries are queued only for subscriptions that exist when an event is recorded, and earlier events are not backfilled.

Prefer a UI? The webhooks console manages these same endpoints with your own API token: create and disable subscriptions, browse the delivery log, and redeliver dead-lettered events.

Event types

typeEmitted when
disbursementrequest.updatedAny journaled request or nonterminal leg transition; re-read the request.
payout.completed, payout.failed, payout.rejected, payout.canceledA recipient leg of a bundled request enters that terminal transfer status.
payin.completed, payin.failed, payin.rejected, payin.canceledThe funding leg of a bundled request enters that terminal transfer status.

Delivery contract

Deliveries are at least once, as an application/json POST using the envelope fields eventId, type, occurredAt, monotonic sequence, resource (type, id, status), and links.self. For disbursementrequest.updated, resource.type is Disbursement, resource.id is the request id, and resource.status is omitted when a leg transition caused the update. payout.* and payin.* events carry resource.type PayOut or PayIn, the leg id, and a links.self of /PayOut/{id} or /PayIn/{id}; they do not carry the request id. webhook.ping uses sequence 0. Four headers accompany every delivery:

  • X-DirecFunds-Event-Id — de-duplicate on this value.
  • X-DirecFunds-Timestamp — Unix seconds, UTC.
  • X-DirecFunds-Signature — t=<unixSeconds>,v1=<signature>, where the signature is lowercase-hex HMAC-SHA256 computed with your signing secret over {timestamp}.{rawBody}. Split the header on , and read the v1= element; more elements may be added later, so ignore unrecognized prefixes.
  • X-DirecFunds-Subscription-Id — select the signing secret for this subscription.

Verify the signature in constant time before parsing the JSON, and reject stale timestamps. Each delivery gets up to 10 attempts in total with exponential backoff (roughly 2^attempt × 5 seconds, capped at 1 hour) and is then dead-lettered. Only a 2xx response counts as delivered. A Retry-After header on a non-2xx response replaces the backoff for that attempt, with no minimum and a 1-hour cap, so a short Retry-After can use up all ten attempts within minutes. Read delivery status with GET .../WebhookSubscriptions/{subscriptionId}/Deliveries and queue a dead-lettered attempt again with POST .../Deliveries/{deliveryId}/$Redeliver. Rotate a signing secret in place with PUT .../WebhookSubscriptions/{subscriptionId}; deliveries identify the subscription. Before processing live events, call POST .../WebhookSubscriptions/{subscriptionId}/$Test to send a signed webhook.ping through the production transport. Subscription update, list, and disable operations do not process X-Idempotency-Key; create, $Test, and $Redeliver require a fresh UUID v4 key so an uncertain retry cannot repeat a side effect. Treat notifications as wake-up hints: de-duplicate on X-DirecFunds-Event-Id, coalesce by resource id, ignore a sequence lower than the last one you processed for that resource, then GET the linked request and reconciliation resource. Webhook sequence values and Events-feed ids come from different counters: never use one as a checkpoint for the other. Use the Events feed, with its own ids, to catch up after your receiver was unavailable. A working C# verifier is on the code samples page.

Advanced Granular Integration Walkthrough

Run these steps in order only when your integration needs direct control of the granular resources. All examples use the test environment.

Your company is created during onboarding. Confirm it is active and the approval strategy is correct before proceeding.

GET https://testapi.direcfunds.com/v1/Company
Authorization: Bearer YOUR_TOKEN

Expected response:

{
  "id": "00000000-0000-0000-0000-000000000001",
  "name": "My Company LLC",
  "approvalStrategy": "Two Party Approval",
  "active": true
}

Addresses are shared across branches and bank accounts. Create one before adding either.

POST https://testapi.direcfunds.com/v1/Address
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "address1": "500 Main Street",
  "address2": "Suite 200",
  "city": "Cincinnati",
  "state": "OH",
  "postalCode": "45202"
}

Store the returned id — you will reference it when creating branches and bank accounts.

Phone numbers default to the U.S. — international phone numbers are not currently supported. Phone numbers can be attached to branches.

POST https://testapi.direcfunds.com/v1/PhoneNumber
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "number": "5134448888"
}

A default branch is created during onboarding. Retrieve it to get its ID:

GET https://testapi.direcfunds.com/v1/Branch
Authorization: Bearer YOUR_TOKEN

Expected response:

[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Main Branch",
    "addressId": "00000000-0000-0000-0000-000000000001",
    "active": true
  }
]

If you need additional branches for other office locations, POST to /Branch with a name and your addressId.

A bank account serves as the source of funds for disbursements. Creating it is only the first step: use GET then PUT /Branch/{branchId}/BankAccounts to assign it to the branch, then call POST /BankAccount/{id}/$Verify. The PUT replaces the branch's complete account list, so send every account that should stay assigned. It requires the If-Match ETag from the GET (omitting it returns 428; a stale value returns 412) and an X-Idempotency-Key. The $Verify call also takes an X-Idempotency-Key. User authority is configured separately in Step 6.

DirecFunds checks the nine-digit routing number against Bankers Almanac when bank instructions are created or changed. A missing or unavailable directory result blocks the write; a CAUTION result is retained as an advisory. The API uses the directory bank name and records the directory address and lookup time as server-owned evidence. The supplied bank address remains the account's payment address and should be reviewed against the directory details. DirecFunds retains the status, comment, lookup time, and directory address for operational review. An ABA match does not verify account ownership or prove that a particular payment rail is available; $Verify reports the separate provider-derived ACH and wire capability.

The same directory check applies to direct API writes, TargetAccount setup, saved recipients, and bank instructions submitted through a recipient invitation. Unchanged routing instructions reuse a fresh lookup, including across application instances. In the Test environment only, DirecFunds' reserved synthetic routing numbers use the mock certification path without a paid directory call.

POST https://testapi.direcfunds.com/v1/BankAccount
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "bankName": "DirecFunds UAT Bank",
  "beneficiary": "My Company LLC",
  "accountNumber": "100010004",
  "routingNumber": "100000000",
  "depositAccountType": "Checking",
  "addressId": "YOUR_ADDRESS_ID"
}
POST https://testapi.direcfunds.com/v1/BankAccount/YOUR_BANK_ACCOUNT_ID/$Verify
Authorization: Bearer YOUR_TOKEN
X-Idempotency-Key: NEW_UUID
The $Verify response reports bank capability as supportsAch and supportsWire, plus wireDrawdownReady when the account can fund by reverse wire. Funding readiness is on GET /BankAccount/{id}/Readiness: managed source-account funding supports Same Day ACH debit when achReady is true, or reverse wire when wireReady is true. Standard ACH remains available for payouts only.

For Two Party Approval, create at least two users: one requester and one approver.

Add the requester (e.g. Bob — closing agent at the Satellite branch):

POST https://testapi.direcfunds.com/v1/User
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "givenName": "Bob",
  "surname": "Doe",
  "email": "bob.doe@mycompany.com",
  "phone": "5551234567"
}
Assign payment authority separately. Do not send branchPermissions or bankAccountPermissions in a User create or update request; the API rejects them. By default, assign request/approve rights and source-account access in the DirecFunds portal. If an administrator has enabled Allow Permission Automation for this integration, first GET /User/{userId}/Permissions and retain its ETag, then PUT /User/{userId}/Permissions with the complete desired branches collection, If-Match, and a fresh X-Idempotency-Key. A stale ETag returns 412; reusing a key with different data returns 422.
User lifecycle. New users are active and non-administrator. For a normal profile update or deactivation, first GET /User/{id} and retain its ETag; send that value as If-Match on PUT or DELETE. DELETE /User/{id} soft-deactivates the user: list reads omit it and the by-id read returns 404. Retain the id and required profile fields if recovery may be needed. Reactivate with PUT /User/{retainedId}, the complete required profile, and "active": true; no If-Match is required for that recovery command. Omit active otherwise. "active": false is rejected—use DELETE to deactivate.

The disbursement is the high-level object. Subsequent Pay Ins and Pay Outs reference its ID.

POST https://testapi.direcfunds.com/v1/Disbursement
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Idempotency-Key: NEW_UUID

{
  "branchId": "YOUR_BRANCH_ID",
  "requesterUserId": "BOB_USER_ID"
}

Store the returned disbursement id — you will reference it on every Pay In and Pay Out. The approver is designated later on $Verify; approverUserId is read-only when creating or updating a disbursement.

The Pay In references the source bank account and total amount being drawn down. Omit targetAccountId; routing resolves the company holding account.

POST https://testapi.direcfunds.com/v1/PayIn
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Idempotency-Key: NEW_UUID

{
  "disbursementId": "YOUR_DISBURSEMENT_ID",
  "sourceAccountReferenceId": "YOUR_BANK_ACCOUNT_ID",
  "paymentRail": "Wire",
  "amount": 1.00
}

Pay In paymentRail value: managed source-account Pay Ins accept Wire (reverse wire) or SamedayAch with achDebitAuthorizationAccepted: true. Standard Ach funding is unsupported; Ach and SamedayAch remain available for Pay Outs.

Create a separate Target Account for the Pay Out destination. Repeat this for each Pay Out you'll add.

POST https://testapi.direcfunds.com/v1/TargetAccount
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "bankName": "DirecFunds UAT Bank",
  "accountNumber": "100200200",
  "routingNumber": "100000000",
  "depositAccountType": "Checking",
  "accountBeneficiary": "Beneficiary",
  "bankAddress1": "500 Walnut St",
  "bankCity": "Cincinnati",
  "bankState": "OH",
  "bankPostalCode": "45000"
}

Add one Pay Out per recipient. The amounts across all Pay Outs must sum to the Pay In total.

POST https://testapi.direcfunds.com/v1/PayOut
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Idempotency-Key: NEW_UUID

{
  "disbursementId": "YOUR_DISBURSEMENT_ID",
  "paymentRail": "Wire",
  "amount": 1.00,
  "transactionPurpose": "ClosingRelatedFees",
  "otherPurpose": "Pest control inspection fee",
  "targetAccountId": "PAYOUT_TARGET_ACCOUNT_ID",
  "recipient": {
    "name": "John Doe",
    "dateOfBirth": "1992-10-10T00:00:00Z",
    "address1": "50 Centennial Ave",
    "address2": "Apt C",
    "city": "Cincinnati",
    "state": "OH",
    "postalCode": "45000",
    "phone": "5134556770",
    "email": "john.doe@gmail.com",
    "tin": "123456789",
    "recipientType": "Person"
  },
  "transactionDetails": {
    "memoLine": "Wire Memo"
  }
}

transactionPurpose values: LoanPayoff, SellerProceeds, RealtorCommission, FundsToClose, EarnestMoney, ClosingRelatedFees, Retainer, TitleAgencyCommission, Other. otherPurpose is a free-text note describing the payment; it is required when transactionPurpose is Other and optional otherwise.

recipientType values: Person, Business. Use Business for entity recipients (a dateOfBirth must not be supplied for a Business).

A new disbursement starts in Initialized. Submit it for approval before verification; the requester must have request permission on the branch and source account.

POST https://testapi.direcfunds.com/v1/Disbursement/YOUR_DISBURSEMENT_ID/$Request
Authorization: Bearer YOUR_TOKEN
X-Idempotency-Key: NEW_UUID

The request action returns 204 No Content and moves the disbursement to Pending (the pending-approval state). Before sending, verify the disbursement and its pay outs. approverUserId is required under every approval strategy; the approver is designated in this request and must hold approve permission on the branch and source account. Under Two Party Approval the approver must differ from the requester.

POST https://testapi.direcfunds.com/v1/Disbursement/YOUR_DISBURSEMENT_ID/$Verify
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Idempotency-Key: NEW_UUID

{
  "approverUserId": "ALICE_USER_ID",
  "reviewConfirmed": true
}

A successful response:

{
  "status": "Verified",
  "message": "Disbursement has been verified successfully and is ready to send"
}

Always check status in the body: only Verified permits $Send. A provider verification outcome also returns HTTP 200, with status Failed or Inconclusive; the disbursement is then held and reads RequiresInconclusiveOverride. Precondition failures (amount mismatch, a missing Pay In/Pay Out, permission, or a preflight check) return a 400 Problem Details response, and KYB/KYC or billing refusals return 422. In every case no money moves.

POST https://testapi.direcfunds.com/v1/Disbursement/YOUR_DISBURSEMENT_ID/$Send
Authorization: Bearer YOUR_TOKEN
X-Idempotency-Key: NEW_UUID

Returns 204 No Content on success. The disbursement is now in Routing status and cannot be edited.

Tip: If you want to verify and send in a single call, use the combined action $VerifyAndSend:
POST https://testapi.direcfunds.com/v1/Disbursement/YOUR_DISBURSEMENT_ID/$VerifyAndSend
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
X-Idempotency-Key: NEW_UUID

{ "approverUserId": "ALICE_USER_ID", "reviewConfirmed": true }
This only sends if verification succeeds. A Failed or Inconclusive outcome returns the same 200 verification body and sends nothing, so check status before treating the call as sent.

Get the full resource or use the compact status alias when only the current status is needed:

GET https://testapi.direcfunds.com/v1/Disbursement/YOUR_DISBURSEMENT_ID/Status
Authorization: Bearer YOUR_TOKEN

The response is the status value, for example "Processing".

For an individual Pay Out:

GET https://testapi.direcfunds.com/v1/PayOut/YOUR_PAYOUT_ID/Status
Authorization: Bearer YOUR_TOKEN

The response is the transferStatus value, for example "Completed". On these granular reads Processing also covers a pay out that has not been submitted yet, including before approval; read the disbursement status to tell the two apart.

Use GET /PayOut/Disbursement/YOUR_DISBURSEMENT_ID to list every pay out for the disbursement.

Audit Log and Support Correlation

Integrations granted Audit.Read can retrieve their own API-activity metadata without exposing payment payloads. Use this to reconcile calls and give Support an exact correlation ID when troubleshooting.

GET https://testapi.direcfunds.com/v1/AuditLog?from=2026-07-17T00:00:00Z&limit=100
Authorization: Bearer YOUR_TOKEN

Results are newest first. The optional inclusive UTC from and to filters bound the window; limit defaults to 100 and is capped at 500. Each entry includes traceId, timestamp, HTTP method, allowlisted route template, status code, and server-side duration. Retrieve one entry with GET /AuditLog/{traceId}. Request and response bodies and raw query strings are not retained; the compatibility query field is always empty. An unknown or different-company trace id returns 404. Authenticated requests attributed to the integration are retained, including attributed 403 and 429 refusals. Anonymous authentication failures contribute to aggregate telemetry, not a company AuditLog entry.

Every API response also carries an X-Trace-Id header holding that same id (it appears as traceId in Problem Details error bodies too, and the X-Request-Id header is a compatibility alias for the identical value). Log it on every call: it ties a client-side request to the AuditLog entry above and is the exact id to quote when you contact Support.

Disbursement Bound Actions

Four bound actions are available on a disbursement:

ActionPathDescription
Request/Disbursement/{id}/$RequestSubmits an initialized disbursement for approval. Required before verification.
Verify/Disbursement/{id}/$VerifyVerifies disbursement data and pay out targets, and designates the approver.
Send/Disbursement/{id}/$SendSends the disbursement to be processed. Requires prior verification.
VerifyAndSend/Disbursement/{id}/$VerifyAndSendCombines the verify and send actions in one call.

Payment Rails

A Pay In draws money into the disbursement over a pull rail; a Pay Out sends money out to a recipient. The two directions accept different rails.

RailPay InPay OutNotes
Wire✅✅Same-day when submitted before the wire cutoff. Choose the rail explicitly. Payouts require the recipient address (address1, city of at most 35 characters, two-letter state, postalCode) and a transactionDetails.memoLine.
Ach—✅Standard ACH payout (typically 1–2 business days). Standard ACH managed funding is unsupported.
SamedayAch✅✅Same Day ACH. Subject to a per-transaction dollar limit and a daily cutoff.
InstantPayment—✅Real-time payments (RTP). Account-addressed and irrevocable; transactionDetails.memoLine required, and supply the recipient fields GET /PaymentRails lists as required. The destination routing number must be confirmed as RTP-capable.
Zelle—UnavailableUnavailable for new payouts in all environments; it appears only on historical records. Historical Zelle payouts were limited to $5,000 each.
FedNow—✅Pay-out only. Instant and irrevocable; transactionDetails.memoLine required, and supply the recipient fields GET /PaymentRails lists as required. The destination routing number must be confirmed as FedNow-capable.
Other——Read-only. A record on a non-contract internal rail reads back as Other; it can never be supplied on a create.

For an RTP or FedNow payout, validate the complete request with POST /DisbursementRequests/$Validate before creating it. If network participation cannot be confirmed for the destination routing number, validation returns 200 with valid: false and a reason in issues[].message. Creating the same invalid request returns 400 with the reason in validationFailures[].errorMessages. Confirm the recipient's routing information or select another eligible rail before submitting. The requested paymentRail can differ from the bank's actual instant-payment network; read actualPaymentNetwork on GET /PayOut/{id} when bank confirmation is available.

Rail availability is environment-specific. Read GET /PaymentRails before offering a rail; the current production configuration enables every supported rail except Zelle, which is unavailable in all environments.

Zelle (historical records only): Zelle is unavailable for new payouts in all environments. Existing records may still show paymentRail Zelle with a destination of type: "Zelle" (an email address and/or 10-digit phone number) or type: "SavedRecipient". Historical Zelle payouts were pay-out only, with a $5,000 per-payment maximum.

A managed source-account Pay In supplied with any rail other than Wire or SamedayAch is rejected with 400; SamedayAch also requires achDebitAuthorizationAccepted: true. Standard ACH funding is unsupported, while ACH and Same Day ACH remain available for Pay Outs.

Status Reference

Status is authoritative on the resource itself. New bundled-request integrations should read GET /DisbursementRequests/{id}, triggered by signed webhooks where they are enabled for the integration; use its /Events feed for catch-up or investigation. Granular integrations can read GET /Disbursement/{id} and its status, or GET /PayOut/{id} and its transferStatus. Compact aliases are available when only the status value is needed: GET /Disbursement/{id}/Status and GET /PayOut/{id}/Status. Use GET /PayOut/Disbursement/{id} to list every pay out for one disbursement. These routes read the same resources and do not maintain separate status state. Each value is a read-only, extensible string. The tables below list current known values, not a closed set. Preserve an unknown value, take no money-moving or recovery action based on it, refresh authoritative request and reconciliation state, retain sanitized telemetry, and route the value for operational review. Never coerce an unknown value to success, failure, or Canceled.

Disbursement status

ValueMeaningTerminal
InitializedCreated; not yet submitted for approval. Add pay ins/pay outs, then call $Request.No
PendingSubmitted for approval (the "pending approval" state). Call $Verify.No
VerifiedVerified and ready to send. Call $Send.No
RequiresInconclusiveOverrideVerification is held for review. An account-verification override is available only for an eligible rail and outcome after sanctions screening is independently clear.No
PendingInfoSent, but waiting on funding before routing: a pay in's consumer or payer funding request, including any payer identity verification, is still outstanding. This is not a compliance follow-up.No
RoutingAccepted for processing and being routed to the payment rails.No
ProcessingFunds are moving.No
CompletedAll legs settled.Yes
RejectedRejected during approval/verification; no money moved.Yes
FailedProcessing failed; inspect the individual pay outs.Yes
CanceledTerminal non-success: canceled within the allowed boundary before dispatch; no leg remains eligible to move.Yes

Pay Out transferStatus

ValueMeaningTerminal
ProcessingNot final. On granular reads this also covers a pay out that has not been submitted yet, including before approval. Use the disbursement status (or, for bundled requests, recipientPayments[].status, which reports Pending) to tell an unsent pay out from one in flight.No
SubmittedAccepted by DirecFunds' bank for processing. This is not a confirmation from the receiving bank.No
InconclusiveThe rail returned an inconclusive result (e.g. account verification could not complete).No
PendingAccountActivationWaiting on the source account to finish activation.No
CompletedSettled.Yes
FailedThe transfer failed. Terminal for money movement. It cannot be canceled or retried through the API; contact DirecFunds support with the traceId to reconcile the provider outcome and funding.Yes
RejectedThe transfer was rejected. Terminal for money movement. It cannot be canceled or retried through the API; contact DirecFunds support with the traceId to reconcile the provider outcome and funding.Yes
CanceledTerminal cancellation for that transfer. Do not resend or retry automatically.Yes

A Pay Out also carries verificationStatus (Unverified, Verified, Inconclusive, Failed, NotRequired, ManuallyVerified). ManuallyVerified records an administrator's affirmative out-of-band evidence; it preserves the provider's earlier outcome, does not send money, and still requires the normal approval and send-time gates. Its optional read-only actualPaymentNetwork records the network confirmed by the bank when known; paymentRail remains the requested rail. A Pay In exposes no status enum — track it with the read-only completedAt timestamp, or use GET /Disbursement/{id}/Detailed to see every leg's paymentRail, transferStatus, and verificationStatus at once.

For a held Inconclusive or Unverified result, the DirecFunds administrator portal explains the payout-specific reason and may offer two separate operational choices when the rail is known and sanctions are independently clear: record manual verification and return to normal approval, or use the warned admin override that immediately attempts release. Wire, RTP, and FedNow overrides require an additional irreversible-payment acknowledgement. Failed results, unknown rails, unresolved sanctions, and unknown sanctions decisions are blocked from both paths. The one sanctions exception is an Indeterminate screen (the provider returned no decision): an administrator may record a manual OFAC check, which is stored as ClearedByReview. Potential matches and blocks never qualify. These are administrator workflows, not partner API actions; integrations should refresh the authoritative resource and event history after an operator completes one.

Disbursement Request status

The primary /DisbursementRequests aggregate normalizes the closing lifecycle independently of the granular disbursement status. Its values are Initialized, PendingApproval, Scheduled, Processing, Completed, PartiallyCompleted, NeedsAttention, Rejected, and Canceled. PartiallyCompleted means at least one recipient payment completed while another did not; inspect each payment, act only on a payment whose allowedNextActions lists an action, and contact DirecFunds support about a failed payment.

Each recipientPayments[] item has its own normalized status: Pending, Submitted, Processing, Completed, Failed, Rejected, Canceled, PendingAccountActivation, or NeedsAttention. Do not infer the result of one recipient payment from the closing-level status.

Canceled is terminal non-success and never authorizes an automatic resend or retry. Offer follow-up only when the current resource returns a separately allowed action.

Readiness blocker codes (GET /Disbursement/{id}/Readiness)

The readiness read reports whether $Request, $Verify, and $Send are eligible — each with stable blockerCodes[] — plus findings[] and a nextAction, without changing the disbursement. Branch on the exact code strings. The list below is not closed: treat an unrecognized code as a blocker and route it for review.

CodeBlocksCondition
STATUS_NOT_INITIALIZEDRequestThe disbursement has already been submitted (status is no longer Initialized).
PAY_IN_REQUIREDVerify, SendNo pay in exists yet.
PAY_OUT_REQUIREDVerify, SendNo pay out exists yet.
AMOUNTS_NOT_BALANCEDVerify, SendThe pay-in total does not equal the pay-out total.
STATUS_NOT_READY_FOR_VERIFICATIONVerifyThe disbursement is not in a verifiable state (call $Request first).
STATUS_NOT_VERIFIEDSendThe disbursement has not been verified.
PAY_OUT_NOT_VERIFIEDSendA pay out is not in a verified state.
PAY_IN_AWAITING_CONSUMER_FUNDINGSendA pay in's consumer funding request has not settled.
FUNDING_COMPANY_REQUIREDSendThe disbursement does not identify a company for routing.
FUNDING_HOLDING_ACCOUNT_MISSINGSendNo eligible DirecFunds holding account is configured for the company.
FUNDING_HOLDING_ACCOUNT_AMBIGUOUSSendMore than one holding account matches; DirecFunds must resolve the configuration.
FUNDING_HOLDING_ACCOUNT_INVALIDSendThe configured holding account is invalid.
FUNDING_REVERSE_WIRE_SOURCE_UNRESOLVEDSendA Wire pay in's source account could not be resolved for reverse wire.
FUNDING_REVERSE_WIRE_NOT_PROVISIONEDSendReverse wire funding is not provisioned for the selected source account and holding account (no reverse wire authorization on file with DirecFunds).
FUNDING_REVERSE_WIRE_READINESS_UNAVAILABLESendReverse wire readiness could not be confirmed because a DirecFunds dependency is unavailable; refresh readiness later.

findings[] may additionally include PAY_OUT_TRANSFER_TERMINAL_FAILURE (severity warning) when a pay out ended Failed, Rejected, or Canceled. nextAction is one of Request, Verify, Send, MonitorPaymentEvents, ResolveBlockers, or None.

Error Codes & Refusals

Errors are RFC 7807 Problem Details. Money-movement refusals carry a stable type or errorCode. No money moves. UnverifiedPayOuts can return the disbursement to Pending; reread authoritative state.

Every Problem Details error also carries errorCode, a resolution object (category, owner, retryMode, nextAction), and traceId; the plain-JSON money-movement refusals below gain resolution and traceId alongside their own fields. Branch on errorCode, not on title or type: several refusals share the generic BadRequest type, and titles are human-readable text that may change.

409 Conflict — Problem Details type ($Send, $VerifyAndSend)

typeMeaning
UnverifiedPayOutsA pay out is no longer in a verified state; re-verify before sending.
UnresolvedSanctionsScreening409 with errorCode SANCTIONS_SCREENING_UNRESOLVED; follow each payout nextAction. Account overrides never clear sanctions.
PayInAwaitingConsumerFundingA pay in still awaits consumer funding and has not settled.

422 — errorCode ($Verify, $Send, $VerifyAndSend)

Most of these bodies are plain JSON, { "errorCode": "...", "message": "..." }, plus code-specific fields: companyId on KYB_KYC_NOT_PASSED, nextWindowEasternTime and retryAtUtc on SAME_DAY_ACH_AFTER_CUTOFF, and amount and limit on SAME_DAY_ACH_AMOUNT_LIMIT. BILLING_PAYMENT_METHOD_REQUIRED is a Problem Details body. errorCode is stable and safe to branch on; message is human-readable and may change. $Verify can return only KYB_KYC_NOT_PASSED and BILLING_PAYMENT_METHOD_REQUIRED; the Same Day ACH and funding codes come from $Send and $VerifyAndSend.

errorCodeReturned byMeaning
KYB_KYC_NOT_PASSED$Verify, $Send, $VerifyAndSendThe company's KYB/KYC verification is not confirmed. Resolve company verification with DirecFunds.
BILLING_PAYMENT_METHOD_REQUIRED$Verify, $VerifyAndSendNo chargeable card or US bank account is on file for DirecFunds billing; a company administrator adds one on the Billing page of the DirecFunds portal, then retries with a new key. If detail says to try again later, the billing check was temporarily unavailable and no company action is needed. Returned as a Problem Details body with type BillingPaymentMethodRequired.
SAME_DAY_ACH_AFTER_CUTOFF$Send, $VerifyAndSendSubmitted after the Same Day ACH window, on a weekend, or on a Federal Reserve holiday. The request is not downgraded to standard ACH; send again at or after retryAtUtc.
SAME_DAY_ACH_AMOUNT_LIMIT$Send, $VerifyAndSendAbove the per-transaction Same Day ACH limit.
SAME_DAY_ACH_PROVIDER_CONFIGURATION$Send, $VerifyAndSendSame Day ACH is not configured for the provider. Contact DirecFunds with the traceId.
FUNDING_COMPANY_REQUIRED$Send, $VerifyAndSendThe disbursement does not identify a company for routing.
FUNDING_HOLDING_ACCOUNT_MISSING$Send, $VerifyAndSendNo eligible holding account exists.
FUNDING_HOLDING_ACCOUNT_AMBIGUOUS$Send, $VerifyAndSendMultiple holding accounts require configuration.
FUNDING_HOLDING_ACCOUNT_INVALID$Send, $VerifyAndSendThe configured holding account is invalid.
Two Party Approval: the requester and approver must be different users. The requester is set at create (requesterUserId); the approver is named on $Verify (approverUserId). The optional reviewConfirmed field records that the approver reviewed the amount, funding source, recipient, account, and delivery method: omitting it is treated as confirmation (the deliberate verify call naming an approver is the review), while explicitly sending reviewConfirmed: false is rejected with a 400 Problem Details response (Review Confirmation Required). Supplying the requester as the approver is rejected at $Verify with 400. In every refusal, no money moves.

Response Codes

CodeMeaning
200OK — response body contains the requested data. Granular $Verify and $VerifyAndSend also return 200 when verification ends Failed or Inconclusive, and bundled $Validate returns 200 with valid: false; always read the body.
201Created — inspect the returned resource and Location.
202Accepted — inspect verification and request state; settlement is asynchronous.
304Not Modified — reuse the conditional reporting response.
204No Content — used by DELETE endpoints, $Request, and $Send
400Bad Request — a Problem Details response describes an invalid payload or setup condition. Bundled lifecycle/state refusals use 409. For preflight failures, inspect validationFailures[].errorMessages; detail may be a general summary. Automatic payload validation may instead return an errors map keyed by field path with only a generic title.
401Unauthorized — the bearer token is missing, expired, or invalid.
403Forbidden — the integration does not have the required scope, permission automation is disabled, or (granular POST /Disbursement only) the company does not have the Business disbursements product enabled. Bundled requests report a missing product as issue code ProductNotEnabled instead.
404Not Found — the requested resource does not exist in the caller's company.
409Conflict — a send action cannot continue because a Pay Out is no longer verified, funding is still pending, or sanctions screening is unresolved (SANCTIONS_SCREENING_UNRESOLVED); a bundled lifecycle action is not allowed in the current state (for example a recipient-payment $Cancel after the editable draft stage); or the original request with this X-Idempotency-Key is still being processed (type: IdempotencyKeyInFlight — retry unchanged after a short delay).
412Precondition Failed — the If-Match ETag supplied to an ETag-guarded PUT or DELETE is stale. This applies to every resource that accepts If-Match (for example Disbursement, Pay In, Pay Out, Address, Bank Account, Branch, User, the branch bank-account list, and the permission-automation document). The resource changed after you read it. Re-read it: if it already reflects your change (an earlier attempt may have succeeded), stop; otherwise re-apply the change and retry with the fresh ETag and a new X-Idempotency-Key where one is used.
422Unprocessable Entity — a compliance, payment-policy, or idempotency conflict refusal. Disbursement actions return a machine-readable errorCode; idempotency-key reuse with a different body returns Problem Details type: IdempotencyConflict.
428Precondition Required — a required If-Match header was omitted. The branch bank-account PUT always requires it; other ETag-guarded writes require it when DirecFunds enforces conditional writes. GET the document, retain its ETag, and retry.
429Too Many Requests — the rate limit was exceeded; wait the Retry-After seconds before retrying.
500Internal Server Error — a fault inside the gateway. On a write the outcome is unknown; follow the 5xx recovery rule below before retrying.
502Bad Gateway — an internal DirecFunds dependency failed or timed out. The body is a Problem Details "upstream service error"; internal error details are never relayed. Safe reads may be retried with backoff; on a write the outcome is unknown, so follow the 5xx recovery rule below.
503Service Unavailable — GET /DisbursementRequests/{id}/DeliveryAssessment could not read recorded timing evidence. No payment action was taken; read it again later.

Rate Limits, Throttling & Retries

  • Rate limits. Authenticated integrations default to 600 requests per minute per integration. Unauthenticated requests share a separate, much tighter anonymous allowance (60 per minute), so authenticate before probing. Over-limit requests return 429 with Retry-After.
  • Idempotent retries. Disbursement Request, granular Disbursement, Pay In, Pay Out, and atomic $CreateWithLegs creation plus webhook subscription creation, $Test, $Redeliver, the $Request, $Verify, $Send, and $VerifyAndSend actions, the Disbursement Request $SubmitForApproval, $Cancel, $Reject, and $CancelSchedule actions, recipient-payment $Cancel, POST /Onboarding/$Provision, bank-account $Verify, and the branch bank-account and opt-in permission-automation PUTs all support an X-Idempotency-Key (UUID v4). Production requires the header on protected money operations when configured enforcement is enabled; Test follows its own environment setting. Send it from your first Test call. Webhook subscription creation, $Test, and $Redeliver always require it. Supplied malformed keys always return 400. Reusing the same key for the same supported operation returns the recorded outcome without repeating the side effect. Reusing a key with a different body returns 422 (IdempotencyConflict); a duplicate arriving while the original is still processing returns 409 (IdempotencyKeyInFlight) — retry it unchanged after a short delay. Rejected-request replays retain the status but may provide a shorter Problem Details reason because sensitive validation text is not stored with the key; capture the first response for complete validationFailures. A corrected request needs a new key. Idempotency records expire after 48 hours — use your own clientReference for business-level duplicate detection, never the key record.
  • Held verification. A provider throttle can produce an Inconclusive pay out. Check the authoritative disbursement and payout statuses before taking another action. An exact retry with the same X-Idempotency-Key replays the recorded outcome without a fresh provider inquiry. A distinct verification attempt is available only for an eligible transient technical outcome within the attempt limit and may incur another provider fee. Missing scores, ambiguous evidence, and substantive negative results are held for correction or review.
  • Sanctions and overrides. An account-verification override never clears sanctions screening. Indeterminate, PotentialMatch, Blocked, missing, and unknown sanctions decisions cannot be sent or overridden through the API. A potential match requires independent Compliance review; an indeterminate result requires the underlying data or provider issue to be investigated, or a DirecFunds administrator's recorded manual OFAC check, which stores the decision as ClearedByReview. A documented administrator override may be available for an eligible account result only after sanctions is Clear or ClearedByReview and the destination has been independently confirmed.
  • 5xx recovery. A 500 or 502 on a write means the outcome is unknown. Read authoritative state first: GET /DisbursementRequests?clientReference={yourReference} or GET /DisbursementRequests/{id} for bundled requests, GET /Disbursement?externalReference={yourReference} or GET /Disbursement/{id}/Readiness for granular ones, and GET /PayOut/Disbursement/{id} for its pay outs. Retry only with the same X-Idempotency-Key and byte-identical body, with backoff (start ~1s, cap ~30s). A keyed write that failed is recorded, and a same-key retry replays that failure for up to 48 hours, so if same-key retries keep returning the same 5xx, stop and email support@direcfunds.com with the traceId. Use a new key only after confirming nothing was created. Safe reads may be retried with backoff. Do not use a new key merely to repeat a held verification, and do not retry a 400, 404, or 422 unchanged.
  • Tokens. Refresh the OAuth token before it expires (1 hour) rather than waiting for a 401.

Go-Live Checklist

Before a company can send live money, confirm all of the following. Several are arranged with DirecFunds out-of-band and are not settable through the API.

  1. Production credentials issued. Do not reuse Test credentials, the Test token endpoint, or the Test scope in Production.
  2. Business disbursements product enabled for the company — otherwise bundled validation reports ProductNotEnabled and granular POST /Disbursement returns 403.
  3. Company KYB/KYC passed — otherwise money-movement actions refuse with 422 KYB_KYC_NOT_PASSED.
  4. Billing payment method on file — a company administrator saves a chargeable card or US bank account on the Billing page of the DirecFunds portal; otherwise approvals refuse with 422 BILLING_PAYMENT_METHOD_REQUIRED. Onboarding readiness does not check this.
  5. Idempotency keys on every protected write. Production requires a fresh UUID v4 X-Idempotency-Key on protected money operations when configured enforcement is enabled; Test follows its own environment setting. Send the header in both environments. A missing required key returns 400 (INVALID_IDEMPOTENCY_KEY).
  6. Source bank account verified. A new account starts unverified and must reach an active/verified state (managed by DirecFunds) before it can fund a disbursement.
  7. Reverse wire authorization on file with DirecFunds for each source account that funds by Wire.
  8. Same Day ACH funding ready, if used — the source account is verified, ACH-capable, and classified as Checking or Savings, and each Same Day ACH Pay In sends achDebitAuthorizationAccepted: true.
  9. User permissions assigned — requesters have request permission and approvers have approve permission on the relevant branch and source account.
  10. Approval strategy confirmed on the company (Two Party Approval requires distinct requester and approver users).
  11. Trace-id logging in place — capture the X-Trace-Id response header on every call.

Tips for Integration Testing

  • Use the explicit Test base URL https://testapi.direcfunds.com/v1 for all development work.
  • Begin with GET /Integration, GET /PaymentRails, and GET /DisbursementRequests/Capabilities instead of hard-coding environment behavior.
  • Use POST /DisbursementRequests/$Validate to preflight the full request without creating data.
  • Only a granular Pay Out requires creating a Target Account beforehand, including each pay out in POST /Disbursement/$CreateWithLegs (targetAccountId is required); the primary request flow accepts recipient destinations inline.
  • Use a new X-Idempotency-Key for each distinct write; reuse it only when retrying the same operation after an uncertain outcome.
  • Exercise Test-only sandbox success and failure scenarios, then verify request status, cursor events, reconciliation, recovery actions, and AuditLog trace correlation. When the billing payment-method check is enforced, the Test company needs a billing payment method on file before approvals.
  • Use the request-level $VerifyAndSend for the recommended approval path. The separate granular $Verify and $Send actions remain supported when an advanced workflow needs distinct control points.