Experience API v1

Make your first test disbursement

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.

Authenticate, create one balanced Wire disbursement, submit it for approval, and read its status. This quickstart assumes DirecFunds has prepared your Test company and payment fixtures.

Start in Test. Use https://testapi.direcfunds.com/v1. Never place a client secret in source code, a browser application, a support ticket, or this documentation.

Onboarding a new title company first? Follow the Partner Onboarding and Disbursement Guide before this transaction quickstart.

This quickstart requires an enabled Business disbursements product and a verified company source account. Selecting only Due diligence payments in registration does not enable POST /v1/DisbursementRequests or the granular business-disbursement examples below. For that product, use the Portal's property-payment workflow after DirecFunds enables it; no company source account is required for buyer-funded due diligence payments.

Payment prerequisites and funding settlement

The company must have the Business disbursements product enabled independently of onboarding readiness. Without it, bundled $Validate returns 200 with valid: false and the issue code ProductNotEnabled, bundled create returns 400 (Preflight) with the same code, and granular POST /Disbursement returns a bare 403. Wire/RTP/FedNow need transactionDetails.memoLine; purpose Other needs otherPurpose. Same Day ACH has a $1,000,000 transaction limit and a 2:45 PM Eastern cutoff.

Billing payment method. When billing payment-method enforcement is enabled, the API refuses $Verify and $VerifyAndSend with 422 and errorCode: BILLING_PAYMENT_METHOD_REQUIRED (problem type) until a company administrator saves a chargeable card or US bank account under Manage → Billing → Payment method in the DirecFunds Portal. Onboarding readiness does not check this, so disbursementsEnabled: true alone does not prove approvals will be accepted. If the refusal's detail says to try again later, the billing check was temporarily unavailable; retry later with a new idempotency key.

Offer only rails returned by GET /PaymentRails and marked active: true in GET /DisbursementRequests/Capabilities. Zelle is unavailable in Test and Production. Each payout must choose its rail explicitly.

Wire recipients require address1, city (at most 35 characters), state, and postalCode. On Wire, ACH, Same Day ACH, RTP and FedNow, a Person also needs a past dateOfBirth, full address and 10-digit phone. A Business needs a 9-digit EIN in tin, or a full address and 10-digit phone; Wire still requires the address even when an EIN is supplied. A Person's recipient.name and the destination's accountBeneficiary must be written as a personal name: words of letters, apostrophes, or hyphens separated by single spaces, such as Jane Seller. Digits, underscores, and other punctuation are refused when the destination account is verified, and $Validate does not check this format. The gateway validates Wire addresses during validate/create. The optional bundled preflight assessment reports locally available identity-input blockers; provider identity verification still happens separately. A successful $Validate does not guarantee $VerifyAndSend can route the request.

ACH and Same Day ACH inline payout accounts require depositAccountType: Checking or Savings. Same Day ACH funding also needs a verified, ACH-capable source account classified as Checking or Savings, plus achDebitAuthorizationAccepted: true. Account readiness alone does not prove classification.

Same Day ACH funding holds dependent payouts until the debit completes, provider good-funds confirmation exists, and funding.goodFundsReleaseAt has passed. The request can remain Processing during this wait. Use the returned UTC release time; the configured Production hold recorded on October 9, 2026 is 120 hours and may change.

202 Accepted from bundled $VerifyAndSend can include failed or inconclusive verification with no routing. Inspect request.status, payment verification outcomes, and allowedNextActions. Granular verify calls can return 200 with Failed or Inconclusive; proceed only when authoritative state permits sending.

Read approvalRequirements.requiresSeparateApprover. Separation can also be required by Single Party with Limit, a missing approval limit, the requester's permissions, or the Production fallback policy. If supplied, intendedApproverUserId must always differ from the requester.

For synthetic Test examples, use https://testapi.direcfunds.com/v1 and routing number 100000000 with DirecFunds UAT Bank. Reserved fixtures are refused outside Test. Real routing instructions must pass directory validation; the directory replaces bankName. A changed saved-recipient bank account has a 24-hour cooling period.

Bundled flow at a glance

In the granular workflow, the integration partner creates and correlates the Disbursement, PayIn Target Account, PayIn, recipient Target Accounts, and PayOuts before requesting approval. The recommended bundled workflow sends the complete closing to POST /v1/DisbursementRequests; DirecFunds validates and commits those related records atomically while returning links to the unchanged granular resources.

Creating the request does not move money. The sourceAccountReferenceId selects the prepared trust account, and DirecFunds creates one PayIn whose amount is the server-calculated sum of recipientPayments[].amount. After the approver authorizes $VerifyAndSend (a user other than the requester when approvalRequirements.requiresSeparateApprover is true), DirecFunds starts that PayIn using the selected reverse-wire drawdown or authorized Same Day ACH debit. Standard ACH is funding-ineligible; ACH and Same Day ACH remain available as recipient PayOut rails. Each recipient PayOut follows its explicitly selected rail.

Map one Order disbursement to one DirecFunds request. The API has no orderId. A request contains one independent payment batch with 1 to 100 recipients, not several Orders. Fan out a multi-Order selection as separate calls and handle partial success per call; there is no atomic bulk rollback. One Order may create additional requests later, but every request needs a distinct clientReference and existing requests cannot be appended to.

Funding: Wire/reverse-wire or SamedayAch debit. Validate and create, approve and verify, wait for good funds, then observe routing and settlement. Inspect allowedNextActions for recovery; retry and destination replacement are reserved.

Before you begin

Before you start, confirm that you have:

  • a Test client ID and client secret, created by a company administrator in the Test Portal under Manage → API Integration (the secret is shown once; rotating it issues a new client ID and secret immediately);
  • a Test company with one internal payment scope and one active source bank account;
  • a chargeable card or US bank account saved under Manage → Billing in the Test Portal, when the billing payment-method check is enforced at approval;
  • a requester with request and source-account permission;
  • an approver with approval and source-account permission (a different user when approvalRequirements.requiresSeparateApprover is true, for example under Two Party Approval); and
  • an approved Test recipient account fixture.

The examples use placeholders intentionally: replace YOUR_SOURCE_ACCOUNT_ID, YOUR_REQUESTER_USER_ID, YOUR_APPROVER_USER_ID, and the other YOUR_* values with the IDs you confirm in step 2. Step 1 stores the access token in ACCESS_TOKEN, which the later commands read.

Missing a credential or fixture? Request Test access and include your company name and integration contact. Do not include secrets in the email.

Request conventions

Use the explicit /v1 base URL and send JSON requests with a bearer token. Pin the contract version with X-Api-Version: 1.0; the /v1 prefix belongs to the base URL, so path templates never repeat it.

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json
X-Api-Version: 1.0

These operations take X-Idempotency-Key: Disbursement Request creation; the request-level $SubmitForApproval, $VerifyAndSend, $Reject, $Cancel, and $CancelSchedule actions and recipient-payment $Cancel; granular Disbursement, Pay In, Pay Out, and atomic $CreateWithLegs creation; the granular $Request, $Verify, $Send, and $VerifyAndSend actions; bank-account $Verify; $Provision; the branch bank-account and user-permission PUTs; and webhook subscription creation, $Test, and $Redeliver. Production requires the header on these operations when configured enforcement is enabled; Test follows its own environment setting. Send the header in both environments. Any key you send must be exactly one UUID v4 value in every environment; a malformed key returns 400 with errorCode: INVALID_IDEMPOTENCY_KEY. Use a new UUID v4 for each distinct operation. Reuse the original key only when retrying the exact same operation and byte-identical body after an uncertain outcome.

Lifecycle outputs are open strings. OpenAPI uses x-extensible-enum to list current known values without closing the wire contract. Generate these properties as strings and implement a safe default branch for values the client does not yet recognize.

1. Get an access token

The OAuth 2.0 client-credentials request is form encoded. Keep token acquisition in trusted server-side code.

export TOKEN_URL="https://direcfundstest2.b2clogin.com/direcfundstest2.onmicrosoft.com/B2C_1A_CLIENT_CREDENTIALS/oauth2/v2.0/token"
export CLIENT_ID="YOUR_TEST_CLIENT_ID"
export CLIENT_SECRET="YOUR_TEST_CLIENT_SECRET"

export ACCESS_TOKEN="$(curl --silent --request POST "$TOKEN_URL" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=https://direcfundstest2.onmicrosoft.com/public/.default" \
  | jq -r '.access_token')"

The command stores the response's access_token in ACCESS_TOKEN (it uses jq; read the JSON field another way if you prefer). Cache the token only until shortly before expires_in. The client-credentials flow does not return a refresh token; request another access token when needed.

2. Confirm your Test fixtures

Begin with discovery instead of hard-coding feature or rail behavior. Confirm the integration is connected to the expected Test company, then verify the internal payment scope and source account.

curl "https://testapi.direcfunds.com/v1/Integration" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/PaymentRails" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/DisbursementRequests/Capabilities" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/Company" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/Branch" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/BankAccount" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/Onboarding/Readiness" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
Test setup is self-service. If readiness reports setup findings and your Test company already has company settings, an active branch, an active user, and at least one source bank account that is not disabled, use the Test sandbox or call POST /v1/Sandbox/$Prepare. The idempotent action creates a dedicated synthetic source account (reusing your existing account's address), records the Test KYB/KYC bypass, and returns the prepared bankAccountId and userId without a provider call or any money movement, then you can repeat the readiness check. It does not add a billing payment method.

Continue only when the final response identifies the expected company and returns disbursementsEnabled: true, and the bankAccounts[] entry you will fund from reports wireReady: true (this example uses Wire funding; Same Day ACH funding needs achReady: true). Its bank-account display values are masked; use that entry's bankAccountId as the request's sourceAccountReferenceId.

3. Create the disbursement request

This is the primary money-movement write. DirecFunds resolves the single authorized payment scope and validates permissions, funding-account readiness, calculated totals, recipient destinations, recipient details, and rail eligibility before creating anything. The disbursement, source-account snapshot, pay-in, destination snapshots, and pay-outs commit together or not at all.

branchId is optional for bundled requests. Omit it when the authenticated integration, requester, and source account have exactly one authorized active scope. DirecFunds returns the resolved value. If more than one scope is eligible, the API returns PAYMENT_BRANCH_SELECTION_REQUIRED and your integration must send a deliberate mapping.

Your integration chooses the rails. Set fundingInstruction.paymentRail and each recipient's paymentRail. DirecFunds validates those exact choices and never silently substitutes another rail. Managed source-account funding accepts Wire (reverse wire) or SamedayAch debit with achDebitAuthorizationAccepted: true. Standard Ach funding is unsupported; both ACH rails remain available for recipient payouts. A validation failure creates nothing.

Before the create call below, send the same JSON body to POST /v1/DisbursementRequests/$Validate. That preflight creates no records and moves no money. Correct every validation issue, then create the request with a new idempotency key.

Read preflight separately from valid. A valid draft can report InputRequired for incomplete recipient identity evidence. Each finding identifies its field, payment reference, resolution owner, and next action. VerificationRequired means the locally assessed identity inputs are present. It does not check every format rule (for example the Person name format above), and approval and provider verification are still required. The checks explicitly leave company readiness, verification price, funding release, and delivery timing unassessed. An absent assessment from an older backend does not establish readiness. Missing person fields are identified individually; saved-recipient findings direct the administrator to the saved record. Alias-only payments report bank-rail identity evidence as NotApplicable.

An inline bank-account destination is checked against the routing directory during validation; the directory bank name replaces the submitted bank name. Recipients created or updated with directory validation enabled retain their lookup evidence, so repeating a payment does not require another paid directory lookup. Directory checks are separate from account ownership and from ACH, wire, RTP, or FedNow eligibility checks. When FedNow participation cannot be confirmed for a destination routing number, $Validate returns valid: false with the reason in issues[].message. Creating the same request returns 400 with the reason in validationFailures[].errorMessages. Confirm the destination or explicitly choose another eligible rail and review the changed payment. The API does not substitute a rail automatically. A CAUTION match appears in the validation response as a BankDirectoryCaution warning while valid remains true; review that advisory before submitting the request.

request_key="$(uuidgen)"

curl --request POST "https://testapi.direcfunds.com/v1/DisbursementRequests" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "X-Idempotency-Key: $request_key" \
  --header "Content-Type: application/json" \
  --data '{
    "clientReference": "partner-2026-000123",
    "fundingInstruction": {
      "sourceAccountReferenceId": "YOUR_SOURCE_ACCOUNT_ID",
      "paymentRail": "Wire"
    },
    "expectedTotal": 100.00,
    "currency": "USD",
    "recipientPayments": [{
      "paymentReference": "seller-001",
      "paymentRail": "Wire",
      "amount": 100.00,
      "transactionPurpose": "LoanPayoff",
      "destination": {
        "type": "BankAccount",
        "bankAccount": {
          "bankName": "DirecFunds UAT Bank",
          "accountNumber": "100200200",
          "routingNumber": "100000000",
          "depositAccountType": "Checking",
          "accountBeneficiary": "Jane Seller",
          "bankAddress1": "500 Walnut St",
          "bankCity": "Cincinnati",
          "bankState": "OH",
          "bankPostalCode": "45202"
        }
      },
      "recipient": {
        "name": "Jane Seller",
        "recipientType": "Person",
        "dateOfBirth": "1992-10-10",
        "address1": "50 Centennial Ave",
        "city": "Cincinnati",
        "state": "OH",
        "postalCode": "45202",
        "phone": "5134556770"
      },
      "transactionDetails": {
        "memoLine": "Partner Test"
      }
    }],
    "approvalContext": {
      "requesterUserId": "YOUR_REQUESTER_USER_ID",
      "intendedApproverUserId": "YOUR_APPROVER_USER_ID",
      "submitForApproval": true
    }
  }'

Save the returned id as DISBURSEMENT_REQUEST_ID. Retrying the identical request with the same idempotency key returns the original request. The source account id identifies the trust account; DirecFunds calculates the funding amount as the sum of recipientPayments[].amount. Optional expectedTotal catches a client-side mismatch but never supplies the pay-in amount. clientReference must be unique within your company, contain 1 to 128 characters, start with a letter or number, and otherwise use only letters, numbers, periods, underscores, or hyphens.

Optional staged approval and scheduling

Set approvalContext.submitForApproval to false to stage the request in Initialized. When ready, call POST /DisbursementRequests/{id}/$SubmitForApproval with a fresh idempotency key. A future scheduledFor may be up to 365 days ahead and must include a UTC Z suffix or an explicit offset; a value without one returns 400. $VerifyAndSend verifies and holds the request in Scheduled; DirecFunds automatically releases it for routing at or after the due time, so no second partner call is required. $CancelSchedule clears the schedule and returns it to PendingApproval; request-level $Cancel abandons the entire undispatched request. Follow allowedNextActions before acting.

Zelle is unavailable in Test and Production. Offer only rails returned by GET /PaymentRails and enabled by active: true in GET /DisbursementRequests/Capabilities.

Use an existing saved recipient

If you already have an authorized saved recipient, replace the inline destination with { "type": "SavedRecipient", "savedRecipientId": "YOUR_SAVED_RECIPIENT_ID" }. Omit bankAccount, email and phone from that destination. Preserve the selected rail and inspect authoritative eligibility; a changed saved-recipient bank account has a 24-hour cooling period.

4. Verify and send

The example below is the immediate path. approverUserId is required; use approvalRequirements.requiresSeparateApprover to determine whether the approver must differ from the requester and must have approval and source-account permission. The optional reviewConfirmed field records that the approver reviewed the payment details. Omission is treated as true only for backward compatibility; new integrations should send true explicitly after review. An explicit reviewConfirmed: false is refused with 400 and nothing is sent. For a future scheduledFor, this same call approves the request once and holds it in Scheduled; DirecFunds automatically releases it when due, with no second approval or send call from the partner.

verify_key="$(uuidgen)"

curl --request POST \
  "https://testapi.direcfunds.com/v1/DisbursementRequests/YOUR_DISBURSEMENT_REQUEST_ID/\$VerifyAndSend" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "X-Idempotency-Key: $verify_key" \
  --header "Content-Type: application/json" \
  --data '{
    "approverUserId": "YOUR_APPROVER_USER_ID",
    "reviewConfirmed": true
  }'

A 202 Accepted response is not proof that the request was routed or paid. Inspect the returned request.status, which may be Scheduled, Processing (including an internal PendingInfo funding wait), or NeedsAttention, then continue from authoritative reads and signed webhooks. For a scheduled request, do not make another approval or send call when it becomes due. Reuse the original key only to retry the initial $VerifyAndSend with the same body after an uncertain result. A 422 with errorCode: BILLING_PAYMENT_METHOD_REQUIRED means nothing was verified or sent; a company administrator must save a billing payment method in the Portal before you call again with a new key.

Advanced integrations may still use the granular disbursement actions when they need to observe or control verification and sending separately.

5. Read request status and events

Read the normalized lifecycle from the stable request id. The response includes an independent status, provider reference, failure details, attempt history, and allowed actions for every recipient payment. If some payments settle and another fails, the closing becomes PartiallyCompleted; inspect the failed payment and its allowedNextActions. Retry and destination replacement are reserved, and a payment can be canceled on its own only before approval, so contact DirecFunds support to reconcile a failed payment. Completed payments are never resent.

Treat Canceled as terminal non-success and never retry or resend it automatically. If any lifecycle status is unknown, preserve the exact value, take no money-moving action based on it, refresh the authoritative request and reconciliation state, and route the unresolved state for operational review.

curl "https://testapi.direcfunds.com/v1/DisbursementRequests/YOUR_DISBURSEMENT_REQUEST_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/DisbursementRequests/YOUR_DISBURSEMENT_REQUEST_ID/Events?after=0&limit=100" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl "https://testapi.direcfunds.com/v1/DisbursementRequests/YOUR_DISBURSEMENT_REQUEST_ID/Reconciliation" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

For controlled catch-up, persist the event response's nextCursor when it is non-null; null means the last page. Send that cursor as after on the next page request. Event history is append-only, so consumers should also de-duplicate by event id. Both /Events and /Reconciliation are read-only observation endpoints; calling either one does not submit, retry, or advance a payment. Normal lifecycle progress is driven by signed webhooks. Before the due time, a request remains Scheduled. At or after scheduledFor, DirecFunds automatically releases it for routing; monitor signed webhooks and authoritative reads rather than calling $VerifyAndSend again.

Granular integrations can also read GET /Disbursement/YOUR_DISBURSEMENT_ID/Status, GET /PayOut/YOUR_PAYOUT_ID/Status, or GET /PayOut/Disbursement/YOUR_DISBURSEMENT_ID. These compact routes read the same authoritative resources as the full disbursement and pay-out representations.

Test failure and recovery paths

In Test, call GET /v1/Sandbox/Scenarios, then use the returned scenario name with POST /v1/Sandbox/PayIn/{id}/$Simulate or POST /v1/Sandbox/PayOut/{id}/$Simulate and a body such as { "scenario": "Completed" }. These endpoints update normal statuses and event history without moving money and return 404 outside Test. Use the PayIn or PayOut leg id, not the disbursement id. The two ACH-specific scenarios apply only to pay-in legs; read discovery for the current supported scenarios:

scenarioResulting transferStatusTerminal
ProcessingProcessingNo
SubmittedSubmittedNo
InconclusiveInconclusiveNo
PendingAccountActivationPendingAccountActivationNo
CompletedCompletedYes
CanceledCanceledYes
RejectedRejectedYes
AchUnauthorizedReturn (PayIn only)Failed; records a Test R10 fixtureYes
AchNotificationOfChange (PayIn only)Inspect the returned leg and correction evidenceNo
FailedFailedYes

Drive a terminal failure (Failed or Rejected) on one recipient payment after a sibling reaches Completed in a multi-recipient closing to rehearse the PartiallyCompleted state — exactly the situation your production error handling must survive.

A failed or rejected recipient payment has no partner recovery action: its allowedNextActions is empty, recipient-payment $Cancel returns 409 for a failed, rejected, or dispatched payment, and $Retry and $ReplaceDestination are reserved and return 409. Contact DirecFunds support to reconcile it. Never recreate or resend recipient payments that are already complete.

Optional: automate user permissions

Explicit opt-in required. A company administrator must enable Allow Permission Automation for the integration. Ordinary POST /User and PUT /User/{id} requests must not contain permission fields.
  1. Create or identify the user.
  2. Call GET /User/{userId}/Permissions and retain the response ETag header.
  3. Replace the complete intended permission state with PUT, using that ETag and a fresh idempotency key.
permission_key="$(uuidgen)"

curl --include \
  "https://testapi.direcfunds.com/v1/User/YOUR_USER_ID/Permissions" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

curl --request PUT \
  "https://testapi.direcfunds.com/v1/User/YOUR_USER_ID/Permissions" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'If-Match: "ETAG_FROM_GET"' \
  --header "X-Idempotency-Key: $permission_key" \
  --header "Content-Type: application/json" \
  --data '{
    "branches": [{
      "branchId": "YOUR_BRANCH_ID",
      "canRequest": true,
      "canApprove": false,
      "bankAccountIds": ["YOUR_SOURCE_ACCOUNT_ID"]
    }]
  }'

This is a complete replacement: omitted branches and bank accounts are removed. A stale ETag returns 412. Reusing an idempotency key for different data returns 422.

User profile lifecycle is separate from permission replacement. DELETE /User/{id} with the current If-Match soft-deactivates the user; subsequent list reads omit it and a by-id read returns 404. Retain the id and required profile fields if reactivation may be needed. Restore the user with PUT /User/{retainedId}, the complete required profile, and "active": true; that recovery command does not require If-Match. Omit active on ordinary writes and never send "active": false—use DELETE to deactivate.

Handle errors and retries safely

StatusWhat to do
400Correct validation, lifecycle, amount, or permission prerequisites, then send the corrected request with a new idempotency key. Do not retry unchanged.
401/403Refresh authentication, or check the integration's granted permissions and the user's authority. A bare 403 from granular POST /Disbursement can also mean the Business disbursements product is not enabled.
409REQUEST_IN_PROGRESS: an earlier call with the same key is still running; wait briefly and repeat the identical call with the same key and body to collect its outcome. Any other 409: re-read the resource, inspect allowedNextActions, and resolve the state conflict before trying again.
412Your change was not applied. Read the latest permission document and retry intentionally with its ETag and a new key.
422Read errorCode. BILLING_PAYMENT_METHOD_REQUIRED: a company administrator must save a billing payment method in the Portal. IDEMPOTENCY_CONFLICT: the key was already used with a different body; recover the original outcome instead of reusing the key. Otherwise resolve the returned policy or compliance refusal.
429Honor Retry-After and back off before retrying with the same key and body.
Timeout or 5xxThe outcome of a write is unknown. Read authoritative state first, for example GET /DisbursementRequests?clientReference=YOUR_CLIENT_REFERENCE or GET /DisbursementRequests/{id}. Retry only with the same key and byte-identical body. A failed keyed write is recorded and replayed for up to 48 hours, so if same-key retries keep returning the same error, stop and email support with the traceId. Use a new key only after confirming nothing was created.

Error responses, both Problem Details bodies and the { errorCode, message } money-movement refusals, carry errorCode, a resolution object (category, owner, retryMode, nextAction), and traceId. Branch on errorCode and resolution.retryMode, not on the human-readable title.

Capture the X-Request-Id and X-Trace-Id response headers — they carry the same correlation id (X-Trace-Id is canonical; X-Request-Id is a compatibility alias) — and include it when contacting support.

Audit API activity

If your integration has Audit.Read, GET /v1/AuditLog returns its own API activity metadata newest first. Use inclusive UTC from and to filters and an optional limit (default 100, maximum 500). GET /v1/AuditLog/{traceId} returns one interaction.

curl "https://testapi.direcfunds.com/v1/AuditLog?from=2026-07-20T00:00:00Z&limit=100" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Each entry contains the trace id, UTC timestamp, HTTP method, allowlisted route template, response status, and server-side duration. Request and response bodies and raw query strings are not retained; the compatibility query field is always empty. Use the trace id to connect a client-side failure, its Problem Details response, and a support investigation. /DisbursementRequests/{id}/Events is the separate business-lifecycle history for a closing.

Subscribe to signed events

Treat GET /v1/Integration as authoritative. When features.webhooks is true for your environment, create and manage subscriptions through /v1/DisbursementRequests/WebhookSubscriptions. New event-driven integrations should not begin lifecycle testing until that feature is enabled. When it is false, webhook administration endpoints return 404 Webhook Capability Unavailable; use payment-status polling and authoritative reads instead.

A subscription requires only a public HTTPS callback. 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 subscribable catalog values; * must be sent by itself and webhook.ping is diagnostic only. Send a fresh UUID v4 X-Idempotency-Key for subscription creation, $Test, and $Redeliver; reuse the same key and request after an uncertain result. Deliveries are at least once. Read the Unix-seconds signing timestamp from X-DirecFunds-Timestamp. X-DirecFunds-Signature is t=<unixSeconds>,v1=<signature>: verify the HMAC-SHA256 v1= value over timestamp + "." + rawBody using the t= timestamp before parsing the JSON, reject stale timestamps, and de-duplicate with X-DirecFunds-Event-Id. Use X-DirecFunds-Subscription-Id to select the signing secret, rotate it in place with PUT, inspect attempts under /{subscriptionId}/Deliveries, and use $Redeliver for dead-lettered attempts. Before processing live events, call /{subscriptionId}/$Test to send a signed webhook.ping through the production transport. Treat each signed event as a wake-up hint, coalesce by resource id, discard stale sequence values, and GET the linked request for authoritative state. Use /Events only for controlled catch-up or investigation, not continuous polling. The full event-type catalog, envelope fields, and retry policy are in the API integration guide, and a working C# verifier is on the code samples page.