Skip to main content
Securely send money to Clients with Disbursements. Here’s the high-level overview. To save a bank account or debit card in your application and pay it later, see the Stored Disbursement Methods guide.

​
Prerequisites

Firms must be ACTIVE for payments in general, but disbursements are gated separately: the API returns an error if disbursements are not enabled for that Firm (disbursements are not allowed for this firm). Enabling disbursements is an additional setup step in onboarding, not something that automatically turns on the moment firm.status becomes ACTIVE. If creation fails, the Firm needs disbursements enabled in Confido (completed by Confido operations)—contact support@confidolegal.com if you are unsure of the Firm’s status.
1

Create a Disbursement

Create a disbursement link and specify the email or phone number that can access the link.
2

Distribute the link

Get the link to the Client. The Client can then access the link to accept the disbursement.
3

Client accepts

Client unlocks link by verifying ownership of email or phone. Client enters account information.
4

Funds sent

Funds are sent from the Firm’s account to the Client’s account.

​
The Disbursement Object

For complete details of all available fields, see the Disbursement Object in our GraphQL Playground.
allowedMethods: DisbursementMethod[] A list of methods that the client is allowed to use when accepting the disbursement from the payout page. The allowed methods will fall back to the Firm’s defaults unless set specifically on the disbursement. DisbursementMethod.ACH Slow ACH transaction via Plaid or manually entering account number and routing number. DisbursementMethod.PUSH_TO_CARD Instant transaction to a Visa or Mastercard debit card. DisbursementMethod.MAIL_CHECK A physical check is mailed to the named payee at a U.S. mailing address. This method must be enabled for the Firm. DisbursementMethod.REQUEST_CHECK Firm would be informed that the client wants a check sent to them. amount: Int The amount to disburse to the client. If the client chooses an instant method from the payout page, the net disbursement to them will be amount - instant_fee. authorizedIdentities: Identity[] The identities that are authorized to accept the disbursement. Any of the authorized identities can be used on the payout page to access the disbursement. After the client authenticates on the payout page, we verify that the email or phone they used matches one of the authorizedIdentities. client The client that the disbursement is associated with. This is optional. fundingAccount The bank account the disbursement will come out of. id Unique identifier for the disbursement. UUID format. matter The matter the disbursement is associated with. This is optional. metadata A flexible JSON object that allows you to store and transfer arbitrary data. When a transaction is created for the disbursement, this metadata object is copied and added to the transaction. This lets you associate transactions with external entities and pass through custom data as needed. status DRAFT The disbursement has been created but has not been approved. At this stage there is no url and no funds can be transferred. APPROVED The disbursement has been approved and is ready for the client to accept. At this status, the disbursement will have a unique url. FUNDS_IN_TRANSIT The client has visited the payout page, entered their method details, and accepted the funds but the funds have not reached the client’s account yet. DELIVERED The client has received the funds in their account. FAILED Failed attempts reached maxFailedTxns. A firm admin can raise that limit and the disbursement can be attempted again. See Failed payouts. STOPPED The firm stopped payment on a mailed check before it was deposited. VOID The disbursement was voided. See Void a Disbursement. canStopPayout: Boolean Indicates whether the payout can be stopped. Currently this is true only for a MAIL_CHECK disbursement in FUNDS_IN_TRANSIT status. transactions: Transaction[] When the client accepts the disbursement a Transaction is created. Most disbursements will only have one transaction in this list. A disbursement may have more than one transaction when an earlier payout failed or an ACH payout was returned. Each payout is its own transaction with its own id. See Failed payouts. url The URL where the payout page is hosted, allowing the client to accept their funds. This field is nullable and will only be populated once the disbursement reaches the APPROVED status. The URL will change whenever the disbursement is updated, so it’s important to provide the client with the new URL after any update, as the previous one will no longer be valid.

​
Failed payouts

Each failed attempt to send the disbursement increments failedTxnCount. The disbursement stays APPROVED until failedTxnCount reaches maxFailedTxns. maxFailedTxns defaults to 5. The status then becomes FAILED. A firm admin can attempt it again with disbursementUpdate, setting maxFailedTxns higher than failedTxnCount. That update returns the disbursement to APPROVED. While the disbursement is FAILED, that is the only field the update accepts. Confido does not resubmit a failed payout. The next attempt creates a new payout transaction with a new id. The disbursement id stays the same, and transactions includes each payout.

​
Create a Disbursement

Use the disbursementCreate mutation to create a new disbursement. Input
allowedMethods This lets you specify certain allowed methods for this disbursement only. If left blank, the disbursement will fall back to the Firm’s default methods. clientUpsert Links an existing client or creates and links a new one to the disbursement. This is useful for checking if the client is already in the system and linking them, or creating a new record if needed. This should not be used with clientId. metadata A flexible JSON object that allows you to store and transfer arbitrary data. When a transaction is created for the disbursement, this metadata object is copied and saved on the transaction. This lets you associate transactions with external entities and pass through custom data as needed. For example, you could create a disbursement with metadata = { external_settlementId: 'my_settlement_id' }. Then, when the client accepts their funds, the corresponding transaction object would have this same metadata. status You can pass status=APPROVED into the create call if you want to skip the approval process. Otherwise, the disbursement will be created in DRAFT and will need to be approved.

​
Update a Disbursement

Use the disbursementUpdate mutation to update a disbursement. Disbursements can only be updated in DRAFT and APPROVED status. Input

​
Approve a Disbursement

Use the disbursementApprove mutation to approve a disbursement. If successful, the disbursement will now have a unique URL.

​
Unapprove a Disbursement

You can use the disbursementUnapprove mutation to send the disbursement back to DRAFT and invalidate the previous URL. When the disbursement is approved again, you will get a new URL.

​
Stop a Payout

Use disbursementStopPayout to request a stop payment on a MAIL_CHECK payout while it is in FUNDS_IN_TRANSIT. The mutation requires the FIRM_ADMIN role. The check can be stopped before the recipient deposits it. After a successful stop, the disbursement status becomes STOPPED and the check can no longer be deposited. Check the Disbursement’s canStopPayout field before offering this action. It is true only when the payout is in FUNDS_IN_TRANSIT and its processor supports stopping it; currently, this is supported for MAIL_CHECK payouts.
Stopping a check that is in transit is different from voiding a disbursement that has not been sent. To void an eligible disbursement, use disbursementVoid.

​
Void a Disbursement

Use disbursementVoid to mark an eligible disbursement as VOID. It can be used for DRAFT, APPROVED, EXPIRED, or FAILED disbursements and is available to FIRM_ADMIN and FIRM_USER roles. It does not request a stop payment on a check in transit.

​
Delete a Disbursement

Use the disbursementDelete mutation to delete a Disbursement. Disbursements can only be deleted in DRAFT and APPROVED status.

​
Get a Disbursement

Fetch a single disbursement with disbursementGet query.

​
List Disbursements

List disbursements that match the given query params with disbursementList. For a full list of available query parameters, see our GraphQL Playground.

​
Webhooks

Get a webhook when a Disbursement is updated with the disbursement.updated webhook. Also get webhooks when a Disbursement is accepted via the transaction.created webhook. See the webhooks docs