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.
| Rail | Recipient payout | Managed company funding | Environment availability |
|---|---|---|---|
| ACH | Supported | Payout only | Check authenticated capabilities |
| FedNow Service | Supported | Payout only | Check authenticated capabilities |
| Real Time Payment | Supported | Payout only | Check authenticated capabilities |
| Same Day ACH | Supported | Supported | Check authenticated capabilities |
| Wire Transfer | Supported | Supported | Check authenticated capabilities |
Zelle disabled Zelle remains available on historical records and is excluded from new commercial payouts.
With your own bearer token, read GET /v1/PaymentRails for the environment rail contract and GET /v1/DisbursementRequests/Capabilities for bundled-request funding, payouts, and features. A missing or refused capability needs its actual reason checked; it does not automatically mean your account is disabled.
For developers integrating title software or another partner platform directly with the DirecFunds Experience API.
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.
| Environment | Base URL |
|---|---|
| Production | https://api.direcfunds.com/v1 |
| Test | https://testapi.direcfunds.com/v1 |
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.
| Environment | Token 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.ReadandAccountMangement.Writefor company, branch, address, bank account, and user resources.Disbursement.Read,Disbursement.Write, andDisbursement.Sendfor the disbursement lifecycle.Alerts.ReadandAlerts.Writefor alert resources.Audit.Readfor 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 Type | Description |
|---|---|
Match | Whole-string match; case-insensitive unless the condition sets "caseSensitive": true |
Contains | String contains the value; case-insensitive unless the condition sets "caseSensitive": true |
Equal | Numeric equality |
NotEqual | Value does not equal the filter value |
LessThan | Numeric less than |
LessThanEqual | Numeric less than or equal |
GreaterThan | Numeric greater than |
GreaterThanEqual | Numeric 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.
| Step | Endpoint | Purpose |
|---|---|---|
| Discover | GET /Integration | Confirm company context, effective permissions, environment, enabled features (including features.webhooks), and discovery links. |
| Subscribe (when enabled) | POST /DisbursementRequests/WebhookSubscriptions | When 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 setup | GET /Onboarding/Readiness | Require 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 rails | GET /PaymentRails | Read current rail directions, Test availability, limits, finality, and required fields instead of hard-coding them. |
| Preflight | POST /DisbursementRequests/$Validate | Validate the complete closing payload without creating resources. It returns 200 even when valid is false: read valid, issues[], and the separate preflight assessment. |
| Create | POST /DisbursementRequests | Atomically create the disbursement, funding leg, recipient destinations, and recipient payments. |
| Submit staged request | POST /DisbursementRequests/{id}/$SubmitForApproval | Move a request created with approvalContext.submitForApproval: false from Initialized to PendingApproval. |
| Approve and send | POST /DisbursementRequests/{id}/$VerifyAndSend | Apply two-party approval rules, verify the request, and submit it through one idempotent operation. |
| Automatic scheduled dispatch | No partner call | After the one approval call, DirecFunds holds the request in Scheduled and automatically releases it for routing at or after scheduledFor. |
| Cancel before dispatch | POST /DisbursementRequests/{id}/$CancelSchedule, /$Cancel, or /$Reject | Clear a schedule and return to approval, abandon the whole undispatched request, or reject it as the approver. |
| Cancel one payment | POST /DisbursementRequests/{id}/RecipientPayments/{paymentReference}/$Cancel | Cancel one recipient payment only when its allowedNextActions includes Cancel. |
| Track | GET /DisbursementRequests/{id} | Read the closing status, each recipient-payment status, failure details, attempts, and allowed next actions. |
| Catch up | GET /DisbursementRequests/{id}/Events | Read append-only history after an identified gap or during an investigation. |
| Reconcile | GET /DisbursementRequests/{id}/Reconciliation | Compare 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.
Webhook Subscriptions and Event Catalog
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
type | Emitted when |
|---|---|
disbursementrequest.updated | Any journaled request or nonterminal leg transition; re-read the request. |
payout.completed, payout.failed, payout.rejected, payout.canceled | A recipient leg of a bundled request enters that terminal transfer status. |
payin.completed, payin.failed, payin.rejected, payin.canceled | The 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 thev1=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
$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"
}
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.
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.
$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:
| Action | Path | Description |
|---|---|---|
Request | /Disbursement/{id}/$Request | Submits an initialized disbursement for approval. Required before verification. |
Verify | /Disbursement/{id}/$Verify | Verifies disbursement data and pay out targets, and designates the approver. |
Send | /Disbursement/{id}/$Send | Sends the disbursement to be processed. Requires prior verification. |
VerifyAndSend | /Disbursement/{id}/$VerifyAndSend | Combines 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.
| Rail | Pay In | Pay Out | Notes |
|---|---|---|---|
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 | — | Unavailable | Unavailable 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.
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
| Value | Meaning | Terminal |
|---|---|---|
Initialized | Created; not yet submitted for approval. Add pay ins/pay outs, then call $Request. | No |
Pending | Submitted for approval (the "pending approval" state). Call $Verify. | No |
Verified | Verified and ready to send. Call $Send. | No |
RequiresInconclusiveOverride | Verification is held for review. An account-verification override is available only for an eligible rail and outcome after sanctions screening is independently clear. | No |
PendingInfo | Sent, 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 |
Routing | Accepted for processing and being routed to the payment rails. | No |
Processing | Funds are moving. | No |
Completed | All legs settled. | Yes |
Rejected | Rejected during approval/verification; no money moved. | Yes |
Failed | Processing failed; inspect the individual pay outs. | Yes |
Canceled | Terminal non-success: canceled within the allowed boundary before dispatch; no leg remains eligible to move. | Yes |
Pay Out transferStatus
| Value | Meaning | Terminal |
|---|---|---|
Processing | Not 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 |
Submitted | Accepted by DirecFunds' bank for processing. This is not a confirmation from the receiving bank. | No |
Inconclusive | The rail returned an inconclusive result (e.g. account verification could not complete). | No |
PendingAccountActivation | Waiting on the source account to finish activation. | No |
Completed | Settled. | Yes |
Failed | The 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 |
Rejected | The 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 |
Canceled | Terminal 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.
| Code | Blocks | Condition |
|---|---|---|
STATUS_NOT_INITIALIZED | Request | The disbursement has already been submitted (status is no longer Initialized). |
PAY_IN_REQUIRED | Verify, Send | No pay in exists yet. |
PAY_OUT_REQUIRED | Verify, Send | No pay out exists yet. |
AMOUNTS_NOT_BALANCED | Verify, Send | The pay-in total does not equal the pay-out total. |
STATUS_NOT_READY_FOR_VERIFICATION | Verify | The disbursement is not in a verifiable state (call $Request first). |
STATUS_NOT_VERIFIED | Send | The disbursement has not been verified. |
PAY_OUT_NOT_VERIFIED | Send | A pay out is not in a verified state. |
PAY_IN_AWAITING_CONSUMER_FUNDING | Send | A pay in's consumer funding request has not settled. |
FUNDING_COMPANY_REQUIRED | Send | The disbursement does not identify a company for routing. |
FUNDING_HOLDING_ACCOUNT_MISSING | Send | No eligible DirecFunds holding account is configured for the company. |
FUNDING_HOLDING_ACCOUNT_AMBIGUOUS | Send | More than one holding account matches; DirecFunds must resolve the configuration. |
FUNDING_HOLDING_ACCOUNT_INVALID | Send | The configured holding account is invalid. |
FUNDING_REVERSE_WIRE_SOURCE_UNRESOLVED | Send | A Wire pay in's source account could not be resolved for reverse wire. |
FUNDING_REVERSE_WIRE_NOT_PROVISIONED | Send | Reverse 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_UNAVAILABLE | Send | Reverse 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)
type | Meaning |
|---|---|
UnverifiedPayOuts | A pay out is no longer in a verified state; re-verify before sending. |
UnresolvedSanctionsScreening | 409 with errorCode SANCTIONS_SCREENING_UNRESOLVED; follow each payout nextAction. Account overrides never clear sanctions. |
PayInAwaitingConsumerFunding | A 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.
errorCode | Returned by | Meaning |
|---|---|---|
KYB_KYC_NOT_PASSED | $Verify, $Send, $VerifyAndSend | The company's KYB/KYC verification is not confirmed. Resolve company verification with DirecFunds. |
BILLING_PAYMENT_METHOD_REQUIRED | $Verify, $VerifyAndSend | No 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, $VerifyAndSend | Submitted 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, $VerifyAndSend | Above the per-transaction Same Day ACH limit. |
SAME_DAY_ACH_PROVIDER_CONFIGURATION | $Send, $VerifyAndSend | Same Day ACH is not configured for the provider. Contact DirecFunds with the traceId. |
FUNDING_COMPANY_REQUIRED | $Send, $VerifyAndSend | The disbursement does not identify a company for routing. |
FUNDING_HOLDING_ACCOUNT_MISSING | $Send, $VerifyAndSend | No eligible holding account exists. |
FUNDING_HOLDING_ACCOUNT_AMBIGUOUS | $Send, $VerifyAndSend | Multiple holding accounts require configuration. |
FUNDING_HOLDING_ACCOUNT_INVALID | $Send, $VerifyAndSend | The configured holding account is invalid. |
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
| Code | Meaning |
|---|---|
200 | OK — 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. |
201 | Created — inspect the returned resource and Location. |
202 | Accepted — inspect verification and request state; settlement is asynchronous. |
304 | Not Modified — reuse the conditional reporting response. |
204 | No Content — used by DELETE endpoints, $Request, and $Send |
400 | Bad 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. |
401 | Unauthorized — the bearer token is missing, expired, or invalid. |
403 | Forbidden — 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. |
404 | Not Found — the requested resource does not exist in the caller's company. |
409 | Conflict — 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). |
412 | Precondition 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. |
422 | Unprocessable 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. |
428 | Precondition 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. |
429 | Too Many Requests — the rate limit was exceeded; wait the Retry-After seconds before retrying. |
500 | Internal Server Error — a fault inside the gateway. On a write the outcome is unknown; follow the 5xx recovery rule below before retrying. |
502 | Bad 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. |
503 | Service 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
429withRetry-After. - Idempotent retries. Disbursement Request, granular Disbursement, Pay In, Pay Out, and atomic
$CreateWithLegscreation plus webhook subscription creation,$Test,$Redeliver, the$Request,$Verify,$Send, and$VerifyAndSendactions, the Disbursement Request$SubmitForApproval,$Cancel,$Reject, and$CancelScheduleactions, recipient-payment$Cancel,POST /Onboarding/$Provision, bank-account$Verify, and the branch bank-account and opt-in permission-automationPUTs all support anX-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$Redeliveralways require it. Supplied malformed keys always return400. 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 returns422(IdempotencyConflict); a duplicate arriving while the original is still processing returns409(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 completevalidationFailures. A corrected request needs a new key. Idempotency records expire after 48 hours — use your ownclientReferencefor business-level duplicate detection, never the key record. - Held verification. A provider throttle can produce an
Inconclusivepay out. Check the authoritative disbursement and payout statuses before taking another action. An exact retry with the sameX-Idempotency-Keyreplays 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 asClearedByReview. A documented administrator override may be available for an eligible account result only after sanctions isClearorClearedByReviewand the destination has been independently confirmed. - 5xx recovery. A
500or502on a write means the outcome is unknown. Read authoritative state first:GET /DisbursementRequests?clientReference={yourReference}orGET /DisbursementRequests/{id}for bundled requests,GET /Disbursement?externalReference={yourReference}orGET /Disbursement/{id}/Readinessfor granular ones, andGET /PayOut/Disbursement/{id}for its pay outs. Retry only with the sameX-Idempotency-Keyand 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 same5xx, stop and email support@direcfunds.com with thetraceId. 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 a400,404, or422unchanged. - 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.
- Production credentials issued. Do not reuse Test credentials, the Test token endpoint, or the Test scope in Production.
- Business disbursements product enabled for the company — otherwise bundled validation reports
ProductNotEnabledand granularPOST /Disbursementreturns403. - Company KYB/KYC passed — otherwise money-movement actions refuse with
422 KYB_KYC_NOT_PASSED. - 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. - Idempotency keys on every protected write. Production requires a fresh UUID v4
X-Idempotency-Keyon protected money operations when configured enforcement is enabled; Test follows its own environment setting. Send the header in both environments. A missing required key returns400(INVALID_IDEMPOTENCY_KEY). - 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.
- Reverse wire authorization on file with DirecFunds for each source account that funds by Wire.
- 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. - User permissions assigned — requesters have request permission and approvers have approve permission on the relevant branch and source account.
- Approval strategy confirmed on the company (Two Party Approval requires distinct requester and approver users).
- Trace-id logging in place — capture the
X-Trace-Idresponse header on every call.
Tips for Integration Testing
- Use the explicit Test base URL
https://testapi.direcfunds.com/v1for all development work. - Begin with
GET /Integration,GET /PaymentRails, andGET /DisbursementRequests/Capabilitiesinstead of hard-coding environment behavior. - Use
POST /DisbursementRequests/$Validateto 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(targetAccountIdis required); the primary request flow accepts recipient destinations inline. - Use a new
X-Idempotency-Keyfor 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
$VerifyAndSendfor the recommended approval path. The separate granular$Verifyand$Sendactions remain supported when an advanced workflow needs distinct control points.