Contract history
API changelog
Contract-affecting changes to the Experience API, newest first. Entries describe the API contract once the corresponding release is deployed;
they do not establish deployment dates or feature activation in an environment. Pin the exact contract you built against by recording the ETag
returned by /openapi/experience.json — it
identifies the precise specification document your integration was tested with.
Upcoming
-
Per-user payment-type permissions (subject to separate activation). Workspace administrators
can choose, once activated in the DirecFunds portal, which payment types each user may request and approve.
User reads will report those grants in a read-only
allowedPaymentRailIdslist; the API cannot change them. Once activated, a request is refused with a400Preflight problem (The user does not have permission to use payment type [X]) when the requester, intended approver, or approver lacks a grant for a payout rail or the funding rail in that request. Activation will be announced here before it takes effect.
November 2026
-
Breaking — recipient-payment cancellation window:
POST /DisbursementRequests/{id}/RecipientPayments/{paymentReference}/$Cancelis accepted only while the request is still an editable draft (before approval and dispatch), the payment has not been sent, and another payment remains; the funding amount shrinks to match. Otherwise it returns409, including forFailed,Rejected, andInconclusivepayments. A payment'sallowedNextActionslistsCancelonly under these conditions. For anything else, contact DirecFunds support. -
Breaking — funding-source bank details are fixed: a pay in keeps a copy of its
source account's bank details.
PUT /TargetAccount/{id}on that copy returns400when it changes the account number, routing number, beneficiary, account type, or SWIFT/BIC. To fund from different bank details, update the managed bank account, then delete and recreate the pay in. -
Billing check at approval: when billing payment-method enforcement is enabled,
$Verifyand$VerifyAndSendread the company's billing payment method at the moment of the call, so a newly saved card or US bank account is recognized on the next attempt. Stripe Link payment methods do not satisfy the check. Already-approved payments, including scheduled releases, are never refused by it.
October 2026
- Events feed event ids: each Events feed record's
eventIdnow equals theX-DirecFunds-Event-Idof the webhook delivery for the same change. Before this fix the two could differ, so a record you already read may show a differenteventIdon replay. Its numericidand theaftercursor are unchanged. -
Billing payment method required for approval when enforcement is enabled. Granular
$Verifyand$VerifyAndSend, and bundled-request$VerifyAndSend, return422witherrorCode: "BILLING_PAYMENT_METHOD_REQUIRED"and typehttps://dev.direcfunds.com/ProblemDetails/BillingPaymentMethodRequiredwhen the company has no chargeable card or US bank account saved on its Billing page in the DirecFunds portal. Nothing is verified or sent.GET /Onboarding/Readinessdoes not check billing, sodisbursementsEnabled: truedoes not rule this refusal out. If the billing check itself is unavailable, the same code is returned with a detail asking you to try again later. - Wire recipient checks at setup: Wire payouts whose recipient address is incomplete, or whose city is longer than 35 characters, are refused when the request is validated or created (saved recipients included), instead of failing after approval and funding.
-
Draft preflight assessment:
POST /DisbursementRequests/$Validatereturns an additivepreflightobject withstatusBlocked,InputRequired, orVerificationRequired, pluschecks[]andfindings[](field path, code, resolution owner, next action,blocksVerification). Read it separately fromvalid: a valid draft can still reportInputRequired.VerificationRequiredmeans the locally available input passed; approval and provider verification still decide the outcome. An absentpreflightnever means ready to send. -
Actionable error fields: Problem Details responses now include
errorCode,resolution(category,owner,retryMode,nextAction), andtraceId. Money-movement refusal bodies (errorCode,message) gainresolutionandtraceId; existing fields are unchanged. Branch onerrorCode, not on titles. -
Breaking — account number length:
accountNumberon bank accounts, Target Accounts, and onboarding provisioning accepts 1 to 17 digits (previously 6 to 20). Values of 18 to 20 digits now return400. -
Breaking — Target Account disclosure:
GET /TargetAccountandGET /TargetAccount/{id}returnaccountNumberandroutingNumbermasked as****plus the last four digits, as bank accounts already did. Filtering Target Accounts by either field returns400. Keep your own record of the full values you submitted. -
Filter limits: a
filterlarger than 64 KiB, or with more than 64 properties, 128 conditions, or 512 values, is refused with400. -
Removed — direct Pay Out deletion:
DELETE /PayOut/{id}always returns405, to preserve funding totals and audit history. Use the disbursement aggregate removal or cancellation operation instead. -
Delivery timing and reconciliation scope:
GET /DisbursementRequests/{id}/DeliveryAssessmentand the bundleddeliveryAssessmentfield give a read-only timing assessment from recorded evidence; neither promises arrival nor releases funds.GET /DisbursementRequests/{id}/ReconciliationaddsreconciliationScope,bankStatementMatching, andcustomerAccountingMatching:Reconciledmeans the recipient legs completed, not that a bank statement or your accounting was matched. -
Correction checklist: request events carry
requiredInputFields, the recipient field names that need correction before verification can start. Values are never included, and an empty list is not verification clearance.GET /Disbursement/{id}/ReadinessreportsroutingInfrastructureReady; when it isfalse, sending is blocked with aFUNDING_*code. - Error contract corrections: bundled state/capability refusals now preserve
409in both HTTP status and Problem Details instead of being rewritten to 400. Body-validation errors usehttps://dev.direcfunds.com/ProblemDetails/FormValidationinstead of the historical unavailablehttps://direcfunds.com/problems/form-validation. - Manual verification: verification statuses include
ManuallyVerified. The audited administrator action does not send money; normal approval and sanctions controls still apply. - Filter validation: invalid filter types, values, and Match/Contains on non-string
properties return
400. Match/Contains default to case-insensitive comparison. - Funding settlement: read
funding.goodFundsReleaseAtfor held Same Day ACH funding. AProcessingrequest can be waiting for good funds.
Idempotency enforcement
-
Idempotency-key enforcement. Production requires
X-Idempotency-Keyon protected operations when configured enforcement is enabled. Test follows its own environment setting; when enforcement is enabled, a missing key returns a400Problem Details titled Invalid Idempotency Key. Webhook subscription creation,$Test, and$Redeliveralready require the header on every call. Send it on every supported write/action, including protected onboarding, verification and permission updates.
September 2026
- Breaking ACH destination requirement (September 9): ACH and Same Day ACH inline
payout destinations require
depositAccountType: "Checking"or"Savings". -
Breaking — scheduled timestamps: offset-less
scheduledForvalues are rejected with400; they were previously interpreted as UTC. Always send a UTCZsuffix or an explicit offset. - Recipient evidence: verified rails require Person date of birth, full address and phone, or Business EIN (alternatively, full address plus 10-digit phone). Wire additionally requires the recipient address.
- Availability: Zelle is unavailable. Disbursement creation requires the Business
disbursements product: without it, bundled
$Validatereturns200withvalid: falseand issue codeProductNotEnabled, bundled create returns a400Problem Details carrying that code, and granularPOST /Disbursementreturns403. Unresolved sanctions screening refuses money movement with409. - Webhook delivery: only 2xx acknowledges a delivery. Every non-2xx, including 410,
is retried within the retry budget; 410 does not disable a subscription. Deliveries can arrive out of order.
When
GET /Integrationreportsfeatures.webhooks: false, the subscription endpoints return404(Webhook Capability Unavailable). - Bank filters: filtering BankAccount by accountNumber or routingNumber returns 400.
Pay Outs expose
actualPaymentNetwork; event records includepaymentRailand provider outcome fields. -
User lifecycle clarified: API-created users start active and non-administrator.
DELETE /User/{id}soft-deactivates a user with ETag protection; deactivated users are omitted from list reads and return404by id. A retained id and complete required profile can be restored withPUTandactive: truewithoutIf-Match. Sendingactive: falseis rejected. -
Managed source-account funding rails: bundled requests, granular Pay Ins, and
$CreateWithLegsnow acceptWire(reverse wire) andSamedayAchdebit. Same Day ACH funding requiresachDebitAuthorizationAccepted: trueand an ACH-capable verified source account. StandardAchfunding returns400; both ACH rails remain available for recipient Pay Outs. RefreshGET /PaymentRailsandGET /DisbursementRequests/Capabilitiesrather than using a cached funding list.
August 2026
-
Operational discovery: company-scoped
GET /DisbursementRequests/Search,GET /DisbursementRequests/Summary, andGET /DisbursementRequests/Eventsare now documented for bounded reporting, aggregation, and controlled event catch-up. -
Webhook lifecycle: create can generate a one-time signing secret when
signingSecretis omitted;eventTypesdefaults to["*"]. Subscription test, in-place secret rotation, delivery inspection, and dead-letter redelivery operations are included in the reference and downloadable collection. -
Recovery guidance: recipient-payment
$Retryand$ReplaceDestinationare reserved actions. Clients must useallowedNextActionsand live capability reads, and must never infer a retry from a failed, rejected, canceled, or unknown status. - Contract metadata: the OpenAPI document now publishes stable operation IDs, complete operation descriptions, webhook validation constraints, and the current event-type vocabulary. Schema narrowings remain subject to the compatibility review recorded with the release.
July 2026
-
Approver review confirmation.
$Verifyand$VerifyAndSendaccept an optionalreviewConfirmedfield recording the approver's review. Omitting it is treated as confirmation, so existing integration payloads keep working unchanged; an explicitreviewConfirmed: falseis refused with400(Review Confirmation Required). -
Breaking for ACH funding: an
AchorSamedayAchfunding instruction (bundlefundingInstruction, granular Pay In, and$CreateWithLegspay-in legs) must includeachDebitAuthorizationAccepted: true— the NACHA business debit-authorization acknowledgment. Requests without it are rejected with400. Wire funding is unaffected. -
Validation tightenings (each now a
400Problem Details naming the field): amounts accept at most 2 decimal places; the wire memo character set excludes[ \ ] ^ _ `; a recipientstatemust be a 2-letter state code andpostalCodeis limited to 16 characters;transactionPurpose: "Other"requiresotherPurpose(≤ 256 characters). -
New partner surface: the bundled
/DisbursementRequestsaggregate (create,$Validate,$VerifyAndSend, events, reconciliation, capabilities, summary, recipient-payment recovery actions),GET /Onboarding/Readiness,GET /AuditLog, Test-only/Sandboxscenarios, signed webhook subscriptions (feature-flagged viaGET /Integration), and opt-in permission automation (GET/PUT /User/{id}/Permissions).
Compatibility promises
- The current contract is
v1; a futurev2with breaking changes will run side by side. - Granular resources (
/Disbursement,/PayIn,/PayOut,/TargetAccount) remain supported for advanced integrations. DirectDELETE /PayOut/{id}returns405; the other granular operations remain supported. - Status values are stable strings returned verbatim; new values may be added. Preserve unknown values, take no money-moving action because of them, refresh authoritative state, and route unresolved values for review.
- Going forward, breaking changes are announced here and through your integration contact before Production enforces them. The 2026 entries document contract changes; they do not establish when an environment deployed or activated them.