Treasury API Integration Guide

Step-by-step guidance for integrating with the Treasury APIs, including authentication and best practices.

The integration is designed around an event-driven model:

Dorman system creates a Hosted Link session.
The customer completes bank verification.
Dorman processes the request.
Dorman sends webhook notifications when the status changes.

Webhook notifications are the primary method for receiving status updates. The ACH Status API is available as a fallback mechanism when webhook notifications are unavailable.

Overview

This should contain a simple flow.

Register Webhook
       │
       ▼
Create Hosted Link Session
       │
       ▼
Redirect Customer
       │
       ▼
Customer Completes Plaid
       │
       ▼
Receive Webhook Event
       │
       ▼
Update Customer Status
       │
       ▼
(Optional)
Get ACH Status API

Before You Begin

Before integrating the Treasury APIs, ensure you have:

Broker API Key - Used to authenticate all API requests
HTTPS Webhook Endpoint - Receives ACH lifecycle notifications
Webhook Authentication Logic - Validates Authorization header
HMAC Signature Validation - Validates webhook authenticity

Authentication

All Treasury APIs require the broker API key.

Example:

Ocp-Apim-Subscription-Key: your-api-key

If authentication fails, the API returns standard HTTP responses such as:

400 – Missing header
401 – Broker inactive
404 – Invalid broker key

Authentication requirements apply to all Treasury APIs.

Webhook Integration

Webhook notifications are a core part of the integration.

Dorman sends ACH lifecycle events to the webhook endpoint you register.

Examples:

ACH_SETUP_PENDING
ACH_SETUP_APPROVED
ACH_SETUP_DENIED
ACH_SETUP_FAILED
ACH_SETUP_EXITED
ACH_SETUP_EXPIRED
ACH_SETUP_REVOKED

Webhook notifications should be considered the primary source of status updates.

API 1 – Broker Webhook Registration and De-Registration

This API is the first API that should be integrated before using any other Dorman Treasury APIs. It registers the broker's webhook endpoint so Dorman can deliver asynchronous ACH status notifications throughout the Hosted Link lifecycle.

Webhook registration is performed using the generic Webhook Registration API.

For Treasury integrations:

webhookType = TREASURY_SETUP

The Webhook Registration API documentation is available here:

[Webhook API Guide]

API 2 – Create Hosted Link Session

Broker Integration Guidelines

This API creates a Plaid Hosted Link session that allows a customer to securely connect their bank account.

Each customer requiring ACH setup must have a new Hosted Link session created.

Endpoint:

POST /api/ach-bank/hosted-link-session

This API creates a Plaid Hosted Link session for a customer.

Information required

{
"DormanTradingAccountNumber": "U12345",

"CustomerEmail": "customer@example.com"
}

When to call this API

Call this API when a customer chooses to link a bank account for ACH payments.

A new Hosted Link session should only be created when:

the customer has not previously linked a bank account,
an earlier session has expired,
the customer exited the Hosted Link flow,
or the previous ACH account has been removed.

Before calling this API

Verify that you have:

A valid Dorman Trading Account Number
The customer's email address
A registered webhook endpoint
Your broker API key

After receiving the response

Store the following values immediately:

sessionId
expiresAt

The sessionId is the primary identifier for the ACH setup process and should be retained for:

status lookups,
troubleshooting,
ACH removal,
customer support.

Redirecting the customer

Redirect the customer to the hostedLinkUrl exactly as returned.

Do not modify the URL.
Do not attempt to extract or alter the Plaid link token.

What happens next

After the customer completes the Hosted Link flow:

Plaid sends a webhook to Dorman.
Dorman validates the session.
Dorman creates the ACH account if validation succeeds.
Dorman sends an event notification to your registered webhook.

No additional action is required while the customer is completing the Hosted Link flow.

Event Types

ACH_SETUP_PENDING - Bank verified, awaiting review

ACH_SETUP_APPROVED - ACH approved

ACH_SETUP_DENIED - ACH denied

ACH_SETUP_FAILED - Validation failed

ACH_SETUP_EXITED - Customer exited

ACH_SETUP_EXPIRED - Session expired

ACH_SETUP_REVOKED - ACH removed

Example Notification

{
"callback_type": "TREASURY_SETUP",

"event_type": "ACH_SETUP_APPROVED",

"session_id": "uuid",

"account_number": "U12345",

"session_status": "APPROVED",

"error_code": null,

"occurred_at": "2026-01-01T10:00:00Z"

}

If the customer does not complete the session

Depending on the outcome, Dorman may notify your webhook with:

ACH_SETUP_EXITED
ACH_SETUP_FAILED
ACH_SETUP_EXPIRED

Your application should allow the customer to create a new Hosted Link session when appropriate.

Best Practices

Persist the sessionId immediately.
Display an appropriate message while waiting for webhook notifications.
Do not repeatedly create Hosted Link sessions for the same customer.
Use the ACH Status API if webhook delivery is delayed.

API 3 – Get ACH Setup Status

Broker Integration Guidelines

This API provides the latest ACH setup status for a customer and is intended primarily as a fallback mechanism when webhook notifications cannot be received.

Endpoint:

GET /api/ach-bank/ach-setup-status

When to call this API

Use this API only when necessary, including:

webhook delivery failure,
manual status refresh,
customer support investigations,
recovery after application downtime.

It should not replace webhook processing.

Lookup methods

You may query using:

sessionId
accountNumber

If a sessionId is available, always use it because it provides the most accurate tracking throughout the Hosted Link lifecycle.

How to use the response

Use the returned status to update the customer experience.

Examples:

CREATED: Customer has not completed Hosted Link.

PROCESSING: Dorman is currently processing the Plaid webhook.

PENDING: Awaiting Dorman approval.

APPROVED: ACH setup completed successfully.

DENIED: Customer's bank account was rejected.

FAILED: Review the error_code.

EXITED: Customer closed the Hosted Link before completion.

EXPIRED: Customer must start a new Hosted Link session.

REVOKED: The ACH account has been removed.

Best Practices

Prefer sessionId over accountNumber.
Continue relying on webhook notifications whenever possible.
Avoid frequent polling.
Use this API only when the current status is unknown.

API 4 – ACH Removal

Broker Integration Guidelines

This API removes a ACH bank account from Dorman.

The removal is performed using a soft delete so historical records remain available for audit purposes.

Endpoint:

DELETE /api/ach-bank/remove

When to call this API

Call this API when:

the customer requests removal,
the customer wants to link a different bank account,
an ACH account is no longer valid,
the broker decides to revoke the ACH setup.

Lookup recommendation

If available, always remove using sessionId.

If the sessionId is unavailable, accountNumber may be used.

What happens after removal

Once the request succeeds:

the ACH account becomes inactive,
the Hosted Link session is marked REVOKED,
a webhook notification is sent,
future ACH processing stops for that account.

What your application should do

Update the customer status immediately after a successful response.
Do not continue using the removed ACH account.
If the customer wishes to link another bank account, begin a completely new Hosted Link session.

Best Practices

Do not call this API repeatedly.
Treat repeated removal requests as successful if the account has already been revoked.
Update your local records immediately after receiving success.