How to Update a Disbursement with Documents API | DisburseCloud

How to Update a Disbursement with Documents

Overview

The Update Disbursement with Document API allows you to attach documents to an existing disbursement after it has been created. Documents can be attached as check attachments for postal checks or as custom documents requiring payee signatures.

Prerequisites


InfoBefore using this API, ensure you have:
  • Valid Access Token: Bearer token from authentication
  • Created Disbursement: A valid disbursement_uuid from a successfully created disbursement
  • PDF Document: Either a new PDF file (max 10MB, 60 pages) or existing document_uuid
  • Valid Status: Disbursement must be in Pending, EmailSentToPayee, or SentRegistrationEmail status

API Endpoint Details

Sandbox URL: https://sandbox.services.disbursecloud.com/api/v1/documents/update-disbursement-document

Production URL: https://app.services.disbursecloud.com/api/v1/documents/update-disbursement-document

Method: POST

Content-Type: multipart/form-data

Authorization: Bearer Token (required)

Info
Workflow

Step 1: Create a Disbursement

First, create your disbursement using the Create Disbursement API to get a disbursement_uuid.

Step 2: Attach Document

Use this API to attach your document immediately after creation or later (within valid time window).

Request Parameters

Field
Required
Type
Description
file
Yes*
File (PDF)
document file to upload (max 10MB, 60 pages)
disbursement_uuid
Yes
String
UUID of the disbursement to update
payee_uuid
Conditional
String
Required when disbursement has multiple payees
document_uuid
Optional
String
Use existing uploaded document instead of new file
one-time-use
No
Boolean
true for single use, false to reuse (default: false)



Notes
Note: Provide either file or document_uuid, not both.

Info
How Documents Behave

Direct Disburse (Postal Check)

When direct_disburse: true:

  • Document becomes a check attachment
  • Physically mailed with the postal check
  • No signature required
  • ⚠️ 15-minute window: Must attach within ~15 minutes of creation before status changes to Processing

Email or SMS Delivery

When email: true and sms: true:

  • Document becomes a custom document
  • Payee must sign digitally before selecting payment method
  • More flexible timing - can update anytime before payee starts payment process
Info
Sample Request:




Response:



Common Errors

Invalid Disbursement UUID

{
    "Message": "Invalid Disbursement UUID"
}
InfoSolution: Verify the UUID is correct and disbursement exists.

Invalid Status
{
    "Message": "Action denied. The disbursement is currently in Processing and no changes are allowed"
}
InfoSolution: Check disbursement status. Cannot update if already in Processing or later status.

Critical Timing Rules

WarningDirect Disburse - 15 Minute Window

For disbursements with direct_disburse: true:

  • Must attach document within ~15 minutes of creation
  • After 15 minutes, status changes from Pending to Processing
  • Once in Processing, documents cannot be added
  • Best Practice: Attach immediately after creating the disbursement

Info
Email/SMS Delivery - Flexible Timing

For email/SMS disbursements:

  • Can update while status is Pending, EmailSentToPayee, or SentRegistrationEmail
  • No strict time limit until payee starts payment process

Document Requirements

Info
  • Format: -        It supports .pdf .gif .png .tiff .tif .doc .docx and .jpg files for check attachments
  • ​Max Size: 10 MB
  • Max Pages: 60 pages

  • Create Your First Disbursement with document - Complete Guide
  • Upload Custom Documents API
  • Upload Check Attachment API
  • Understanding Disbursement Statuses
  • Direct Disburse vs Email Delivery Options

Need Help?

Email: devsupport@disbursecloud.com
API Documentation: https://docs.google.com/document/d/1Z7IJvXjD2-AjC6TIGJVKgrkHJMSO8ajCjgexy2RAvCw




    • Related Articles

    • How to Set Up Terms & Conditions for Disbursements

      Overview DisburseCloud allows you to require customers to accept terms & conditions before they can select a payment method. This article explains how to configure T&Cs using After Payee Authentication Documents and Custom Documents, helping you ...

    • #OTP Verification on Sandbox Environment

      ##Overview In the Sandbox environment of DisburseCloud, the OTP (One-Time Password) verification feature is not fully functional. This is by design, as the Sandbox environment is intended for testing and integration purposes only. ##Details When ...