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/$Prepare fills sourceAccountId and requesterUserId when 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. $Validate must return valid: true with no Blocked or InputRequired preflight, and $VerifyAndSend must return 202 with the request in Processing or later. Anything else stops the run and logs the reason.
  • Approver. When self-approval is allowed, approverUserId defaults to the requester. When $Validate reports requiresSeparateApprover: true, set approverUserId to 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 /Integration reports features.webhooks: true. The irreversible webhook disable is in a final folder that is skipped unless allowDestructive is true.
  • Credentials. Select a Postman environment and keep clientSecret and accessToken there as secret-type variables. The token script writes accessToken to the selected environment.
  • Billing. If Capabilities reports billingReady: false, DirecFunds has not finished billing setup for the company and payout rails report active: false; contact DirecFunds. Separately, when the billing payment-method check is enforced, $VerifyAndSend returns 422 BILLING_PAYMENT_METHOD_REQUIRED until a company admin saves a card or US bank account on the Portal Billing page. billingReady does 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:

  1. Run Find by clientReference first. A 200 means the request exists, so do not create it again; a 404 means it was not created.
  2. 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.
  3. 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 the X-Trace-Id before using any new key.
  4. Any other 4xx clears 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.