Developer tooling
Code samples and tooling
Ready-to-run tooling for the recommended bundled workflow. Everything targets the Test environment; keep credentials in your secret store, never in these files.
Postman collection
The collection walks the full recommended flow in order: token, discovery, Test sandbox preparation,
$Validate, create, $VerifyAndSend, tracking (with Test-only
$Simulate calls), search, summary, company-wide events, reconciliation, and audit log.
Every request carries X-Api-Version: 1.0, and every write the API keys carries an
X-Idempotency-Key. Run it with the Collection Runner against Test:
-
Sandbox preparation runs first.
POST /Sandbox/$PreparefillssourceAccountIdandrequesterUserIdwhen they are empty. It needs an onboarded Test company with an active branch, an active user, and an existing source bank account. -
The run stops on failure.
$Validatemust returnvalid: truewith noBlockedorInputRequiredpreflight, and$VerifyAndSendmust return202with the request inProcessingor later. Anything else stops the run and logs the reason. -
Approver. When self-approval is allowed,
approverUserIddefaults to the requester. When$ValidatereportsrequiresSeparateApprover: true, setapproverUserIdto a second user with approve permission. -
Optional examples never touch the request you sent. The lifecycle folder creates its
own staged and scheduled Test requests, and they end Canceled or Rejected. The webhook folder runs only
when
GET /Integrationreportsfeatures.webhooks: true. The irreversible webhook disable is in a final folder that is skipped unlessallowDestructiveistrue. -
Credentials. Select a Postman environment and keep
clientSecretandaccessTokenthere as secret-type variables. The token script writesaccessTokento the selected environment. -
Billing. If Capabilities reports
billingReady: false, DirecFunds has not finished billing setup for the company and payout rails reportactive: false; contact DirecFunds. Separately, when the billing payment-method check is enforced,$VerifyAndSendreturns422 BILLING_PAYMENT_METHOD_REQUIREDuntil a company admin saves a card or US bank account on the Portal Billing page.billingReadydoes not report that check.
Download the Postman collection
Retrying after a timeout or a 5xx. Create and $VerifyAndSend keep their
X-Idempotency-Key (and create keeps its clientReference) in collection variables
until they receive a definitive response. After an uncertain outcome:
-
Run Find by clientReference first. A
200means the request exists, so do not create it again; a404means it was not created. - To retry, re-send the same request unchanged. It reuses the original key and body, so DirecFunds returns the recorded outcome instead of repeating the operation.
-
If same-key retries keep returning
502, stop. The recorded outcome may be the failure itself, and it is replayed for 48 hours. Email support@direcfunds.com with theX-Trace-Idbefore using any new key. -
Any other
4xxclears the stored key, because nothing was done; the next send is a new operation with a new key.
C#: token and bundled disbursement request
A minimal .NET client for the two calls every integration makes first. Production code should cache
the token until shortly before expires_in and route all calls through
IHttpClientFactory.
using System.Net.Http.Headers;
using System.Net.Http.Json;
var http = new HttpClient();
// 1. Client-credentials token (form encoded — keep this server-side only).
var tokenResponse = await http.PostAsync(
"https://direcfundstest2.b2clogin.com/direcfundstest2.onmicrosoft.com/B2C_1A_CLIENT_CREDENTIALS/oauth2/v2.0/token",
new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "client_credentials",
["client_id"] = clientId,
["client_secret"] = clientSecret,
["scope"] = "https://direcfundstest2.onmicrosoft.com/public/.default",
}));
tokenResponse.EnsureSuccessStatusCode();
var token = (await tokenResponse.Content.ReadFromJsonAsync<TokenResponse>())!.AccessToken;
// 2. Create the closing atomically. Generate ONE UUID v4 key per distinct operation and store it
// with your Order before sending; every retry of this create reuses that key and the
// byte-identical body (including clientReference).
var idempotencyKey = Guid.NewGuid().ToString();
var request = new HttpRequestMessage(HttpMethod.Post,
"https://testapi.direcfunds.com/v1/DisbursementRequests")
{
Content = JsonContent.Create(disbursementRequestBody),
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Headers.Add("X-Api-Version", "1.0");
request.Headers.Add("X-Idempotency-Key", idempotencyKey);
var response = await http.SendAsync(request);
var traceId = response.Headers.TryGetValues("X-Trace-Id", out var values)
? values.FirstOrDefault()
: null; // log this on every call — it is the id Support needs.
// On a timeout or 5xx the outcome is unknown: read GET /DisbursementRequests?clientReference=...
// before retrying, and retry only with the same key and body.
internal sealed record TokenResponse(
[property: System.Text.Json.Serialization.JsonPropertyName("access_token")] string AccessToken,
[property: System.Text.Json.Serialization.JsonPropertyName("expires_in"),
System.Text.Json.Serialization.JsonNumberHandling(
System.Text.Json.Serialization.JsonNumberHandling.AllowReadingFromString)] int ExpiresIn);
C#: webhook signature verification
Verify the HMAC before parsing the JSON. The X-DirecFunds-Signature header is
t=<unixSeconds>,v1=<signature>: compute HMAC-SHA256 with your signing secret over
{timestamp}.{rawBody} using the t= value, compare in constant time against the
v1= value, reject stale timestamps, and de-duplicate on X-DirecFunds-Event-Id. Select the secret by
X-DirecFunds-Subscription-Id. Rotate it in place with
PUT /DisbursementRequests/WebhookSubscriptions/{subscriptionId} and replace the stored
value only after the update succeeds.
using System.Security.Cryptography;
using System.Text;
static bool VerifyWebhook(
string rawBody, // the EXACT bytes received — do not re-serialize
string signatureHeader, // X-DirecFunds-Signature, e.g. "t=1735689600,v1=<lowercase hex>"
IReadOnlyList<string> candidateSecrets, // secret selected for X-DirecFunds-Subscription-Id
TimeSpan tolerance)
{
// The header is "t=<unixSeconds>,v1=<signature>". Split on ',' and read each prefixed
// element; ignore unrecognized prefixes so future scheme versions do not break you.
long? timestamp = null;
string? presented = null;
foreach (var element in signatureHeader.Split(','))
{
var part = element.Trim();
if (part.StartsWith("t=", StringComparison.Ordinal) &&
long.TryParse(part["t=".Length..], out var unixSeconds))
{
timestamp = unixSeconds;
}
else if (part.StartsWith("v1=", StringComparison.Ordinal))
{
presented = part["v1=".Length..];
}
}
if (timestamp is null || string.IsNullOrEmpty(presented))
{
return false;
}
// Replay protection: reject timestamps outside the tolerance window in either direction.
var skew = Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp.Value);
if (skew > (long)tolerance.TotalSeconds)
{
return false;
}
var signedPayload = Encoding.UTF8.GetBytes($"{timestamp.Value}.{rawBody}");
foreach (var secret in candidateSecrets)
{
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var expected = Convert.ToHexString(hmac.ComputeHash(signedPayload)).ToLowerInvariant();
if (CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(expected),
Encoding.UTF8.GetBytes(presented)))
{
return true;
}
}
return false;
}
Delivery is at least once: store the X-DirecFunds-Event-Id you have processed and skip
duplicates. Coalesce notifications by resource id, compare a notification's sequence only with
other webhook notifications to discard stale ones, and re-read the linked request for authoritative state.
Webhooks are a low-latency signal. They are enabled per integration (check
features.webhooks on GET /Integration) and depend on the current integration configuration. The Events feed, GET /DisbursementRequests/{id}/Events, is the authoritative record
for recovery and reconciliation: persist its nextCursor as your checkpoint. Never use a webhook
sequence value as the feed's after cursor; the two number events differently.