Partner implementation contract

Integration constraints and operational guardrails

These constraints are part of the supported partner contract. Building to them from day one avoids the failure modes that are hardest to recover from in production. Each one is checked during integration review before Production credentials are issued.

Approval submission

Set approvalContext.submitForApproval: true to create the request directly in PendingApproval. Set it to false to stage the request in Initialized, then call POST /DisbursementRequests/{id}/$SubmitForApproval with a fresh idempotency key when it is ready for approval.

Scheduling

A future scheduledFor may be up to 365 days ahead. A single $VerifyAndSend approves and verifies the request, then holds it in Scheduled without starting money movement. DirecFunds automatically releases it for routing at or after the due time. The partner must not call $VerifyAndSend again; it should observe the transition through authoritative reads and, where enabled, signed webhooks. POST /DisbursementRequests/{id}/$CancelSchedule clears the timestamp and returns the request to PendingApproval. Always send timestamps with an explicit UTC offset (Z); offset-less values are rejected with 400.

Scheduling can be switched off. Send scheduledFor only when GET /DisbursementRequests/Capabilities reports supportsScheduling: true; otherwise validate and create refuse it with SchedulingUnavailable ("Scheduled dispatch is temporarily unavailable"). Omit scheduledFor and submit an immediate request instead.

Order mapping and request boundaries

DirecFunds has no orderId field and does not combine several title-platform Orders into one disbursement request. Map each Order disbursement to one independent POST /DisbursementRequests call containing 1 to 100 recipient payments. If a user selects several Orders, fan them out as separate calls and report success or failure per request; there is no atomic bulk endpoint or cross-request rollback. One Order may produce more than one request over time, but an existing request cannot be appended to. Give every request its own clientReference and every write or action its own idempotency key.

Idempotency-key lifetime

Idempotency-key records are retained server-side for 48 hours. That window exists to make retries of the same operation safe after an uncertain outcome — it is not a business-level duplicate check. A key replayed after the record expires is treated as a brand-new operation. Use your own stable clientReference (unique per DirecFunds request within your company) for business dedupe, and recover authoritative state after a lost response by reading the resource back by clientReference or id — the API does not add a replay-indicator header.

A server error is recorded against the key too. A same-key retry after a 5xx replays that recorded outcome for the rest of the 48 hours instead of running the operation again (a bundle create that did commit is recovered and returned). If same-key retries keep failing, stop: read the request back by clientReference, and contact support with the X-Trace-Id. Use a new key only after confirming that nothing was created or sent.

Recovery actions and actors

Recipient-payment cancellation requires an actorUserId identifying the person who authorized it; that actor must hold approval permission for the branch and must always differ from the original requester, regardless of the company's approval strategy. (Request-level $Cancel is less strict: there the original requester may act.) Act only when the payment's allowedNextActions permits $Cancel, with a fresh X-Idempotency-Key. A payment can be canceled on its own 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. After that stage, contact DirecFunds support with the request and recipient references. A Pending status alone does not prove the bank has not received an instruction, so do not reissue a payment until its outcome and any collected funding have been reconciled. $Retry and $ReplaceDestination are reserved in the current baseline, are never returned as allowed actions, and return 409. Completed payments are never resent.

Webhooks and the event feed

Webhooks are enabled integration by integration and depend on the current integration configuration. Check features.webhooks in GET /Integration; when it is false, the subscription endpoints return 404 "Webhook Capability Unavailable". Webhooks are emitted only for bundled requests created with POST /DisbursementRequests.

GET /DisbursementRequests/{id}/Events is the authoritative event history. Treat webhooks as wake-up hints, and use the feed to catch up after an outage or an identified delivery gap. Where webhooks are not enabled for your integration, read open requests and their feed instead. Checkpoint the feed with its own nextCursor; a webhook's sequence is not an after value for the feed.

Webhook secret rotation

Rotate a signing secret in place with PUT /DisbursementRequests/WebhookSubscriptions/{subscriptionId}. Deliveries include X-DirecFunds-Subscription-Id, so the receiver can select the correct secret. Inspect attempts with GET .../{subscriptionId}/Deliveries and redrive a dead-lettered delivery with POST .../{subscriptionId}/Deliveries/{deliveryId}/$Redeliver. Webhooks are at-least-once, so deduplicate by X-DirecFunds-Event-Id.

Base URL and versioning

The /v1 segment belongs to the base URL (https://testapi.direcfunds.com/v1), never to path templates — calling /v1/v1/DisbursementRequests is the most common first-integration mistake. Pin the contract with X-Api-Version: 1.0 on every request.

Acceptance meaning

201 Created on the bundle and 202 Accepted on $VerifyAndSend mean the action was accepted, not that it was routed, submitted to a provider, paid, or settled. The returned request may be Scheduled, Processing (including an internal PendingInfo wait), or NeedsAttention. Treat settlement as proven only by the recipient payment's terminal status in GET /DisbursementRequests/{id}, its /Events feed, and /Reconciliation totals.