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 allowedPaymentRailIds list; the API cannot change them. Once activated, a request is refused with a 400 Preflight 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}/$Cancel is 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 returns 409, including for Failed, Rejected, and Inconclusive payments. A payment's allowedNextActions lists Cancel only 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 returns 400 when 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, $Verify and $VerifyAndSend read 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 eventId now equals the X-DirecFunds-Event-Id of the webhook delivery for the same change. Before this fix the two could differ, so a record you already read may show a different eventId on replay. Its numeric id and the after cursor are unchanged.
  • Billing payment method required for approval when enforcement is enabled. Granular $Verify and $VerifyAndSend, and bundled-request $VerifyAndSend, return 422 with errorCode: "BILLING_PAYMENT_METHOD_REQUIRED" and type https://dev.direcfunds.com/ProblemDetails/BillingPaymentMethodRequired when 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/Readiness does not check billing, so disbursementsEnabled: true does 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/$Validate returns an additive preflight object with status Blocked, InputRequired, or VerificationRequired, plus checks[] and findings[] (field path, code, resolution owner, next action, blocksVerification). Read it separately from valid: a valid draft can still report InputRequired. VerificationRequired means the locally available input passed; approval and provider verification still decide the outcome. An absent preflight never means ready to send.
  • Actionable error fields: Problem Details responses now include errorCode, resolution (category, owner, retryMode, nextAction), and traceId. Money-movement refusal bodies (errorCode, message) gain resolution and traceId; existing fields are unchanged. Branch on errorCode, not on titles.
  • Breaking — account number length: accountNumber on bank accounts, Target Accounts, and onboarding provisioning accepts 1 to 17 digits (previously 6 to 20). Values of 18 to 20 digits now return 400.
  • Breaking — Target Account disclosure: GET /TargetAccount and GET /TargetAccount/{id} return accountNumber and routingNumber masked as **** plus the last four digits, as bank accounts already did. Filtering Target Accounts by either field returns 400. Keep your own record of the full values you submitted.
  • Filter limits: a filter larger than 64 KiB, or with more than 64 properties, 128 conditions, or 512 values, is refused with 400.
  • Removed — direct Pay Out deletion: DELETE /PayOut/{id} always returns 405, to preserve funding totals and audit history. Use the disbursement aggregate removal or cancellation operation instead.
  • Delivery timing and reconciliation scope: GET /DisbursementRequests/{id}/DeliveryAssessment and the bundled deliveryAssessment field give a read-only timing assessment from recorded evidence; neither promises arrival nor releases funds. GET /DisbursementRequests/{id}/Reconciliation adds reconciliationScope, bankStatementMatching, and customerAccountingMatching: Reconciled means 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}/Readiness reports routingInfrastructureReady; when it is false, sending is blocked with a FUNDING_* code.
  • Error contract corrections: bundled state/capability refusals now preserve 409 in both HTTP status and Problem Details instead of being rewritten to 400. Body-validation errors use https://dev.direcfunds.com/ProblemDetails/FormValidation instead of the historical unavailable https://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.goodFundsReleaseAt for held Same Day ACH funding. A Processing request can be waiting for good funds.

Idempotency enforcement

  • Idempotency-key enforcement. Production requires X-Idempotency-Key on protected operations when configured enforcement is enabled. Test follows its own environment setting; when enforcement is enabled, a missing key returns a 400 Problem Details titled Invalid Idempotency Key. Webhook subscription creation, $Test, and $Redeliver already 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 scheduledFor values are rejected with 400; they were previously interpreted as UTC. Always send a UTC Z suffix 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 $Validate returns 200 with valid: false and issue code ProductNotEnabled, bundled create returns a 400 Problem Details carrying that code, and granular POST /Disbursement returns 403. Unresolved sanctions screening refuses money movement with 409.
  • 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 /Integration reports features.webhooks: false, the subscription endpoints return 404 (Webhook Capability Unavailable).
  • Bank filters: filtering BankAccount by accountNumber or routingNumber returns 400. Pay Outs expose actualPaymentNetwork; event records include paymentRail and 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 return 404 by id. A retained id and complete required profile can be restored with PUT and active: true without If-Match. Sending active: false is rejected.
  • Managed source-account funding rails: bundled requests, granular Pay Ins, and $CreateWithLegs now accept Wire (reverse wire) and SamedayAch debit. Same Day ACH funding requires achDebitAuthorizationAccepted: true and an ACH-capable verified source account. Standard Ach funding returns 400; both ACH rails remain available for recipient Pay Outs. Refresh GET /PaymentRails and GET /DisbursementRequests/Capabilities rather than using a cached funding list.

August 2026

  • Operational discovery: company-scoped GET /DisbursementRequests/Search, GET /DisbursementRequests/Summary, and GET /DisbursementRequests/Events are now documented for bounded reporting, aggregation, and controlled event catch-up.
  • Webhook lifecycle: create can generate a one-time signing secret when signingSecret is omitted; eventTypes defaults 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 $Retry and $ReplaceDestination are reserved actions. Clients must use allowedNextActions and 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. $Verify and $VerifyAndSend accept an optional reviewConfirmed field recording the approver's review. Omitting it is treated as confirmation, so existing integration payloads keep working unchanged; an explicit reviewConfirmed: false is refused with 400 (Review Confirmation Required).
  • Breaking for ACH funding: an Ach or SamedayAch funding instruction (bundle fundingInstruction, granular Pay In, and $CreateWithLegs pay-in legs) must include achDebitAuthorizationAccepted: true — the NACHA business debit-authorization acknowledgment. Requests without it are rejected with 400. Wire funding is unaffected.
  • Validation tightenings (each now a 400 Problem Details naming the field): amounts accept at most 2 decimal places; the wire memo character set excludes [ \ ] ^ _ `; a recipient state must be a 2-letter state code and postalCode is limited to 16 characters; transactionPurpose: "Other" requires otherPurpose (≤ 256 characters).
  • New partner surface: the bundled /DisbursementRequests aggregate (create, $Validate, $VerifyAndSend, events, reconciliation, capabilities, summary, recipient-payment recovery actions), GET /Onboarding/Readiness, GET /AuditLog, Test-only /Sandbox scenarios, signed webhook subscriptions (feature-flagged via GET /Integration), and opt-in permission automation (GET/PUT /User/{id}/Permissions).

Compatibility promises

  • The current contract is v1; a future v2 with breaking changes will run side by side.
  • Granular resources (/Disbursement, /PayIn, /PayOut, /TargetAccount) remain supported for advanced integrations. Direct DELETE /PayOut/{id} returns 405; 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.