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.
| 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.
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.
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.
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.requiresSeparateApproveristrue, 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"
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.
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:
scenario | Resulting transferStatus | Terminal |
|---|---|---|
Processing | Processing | No |
Submitted | Submitted | No |
Inconclusive | Inconclusive | No |
PendingAccountActivation | PendingAccountActivation | No |
Completed | Completed | Yes |
Canceled | Canceled | Yes |
Rejected | Rejected | Yes |
AchUnauthorizedReturn (PayIn only) | Failed; records a Test R10 fixture | Yes |
AchNotificationOfChange (PayIn only) | Inspect the returned leg and correction evidence | No |
Failed | Failed | Yes |
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
POST /User and PUT /User/{id} requests must not contain permission fields.
- Create or identify the user.
- Call
GET /User/{userId}/Permissionsand retain the responseETagheader. - 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
| Status | What to do |
|---|---|
400 | Correct validation, lifecycle, amount, or permission prerequisites, then send the corrected request with a new idempotency key. Do not retry unchanged. |
401/403 | Refresh 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. |
409 | REQUEST_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. |
412 | Your change was not applied. Read the latest permission document and retry intentionally with its ETag and a new key. |
422 | Read 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. |
429 | Honor Retry-After and back off before retrying with the same key and body. |
Timeout or 5xx | The 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.