Overview
A disbursement:- Sends funds to multiple recipients in one batch
- Uses CSV upload to define recipients and amounts
- Includes validation to catch errors before execution
- Requires approval before funds are sent
Creating a Disbursement
Step 1: Navigate to Disbursements
Click Disbursements in the sidebar, then click Create Disbursement.Step 2: Enter Disbursement Details
| Field | Required | Description |
|---|---|---|
| Name | Yes | Descriptive name (e.g., “January Payroll”) |
| Description | No | Additional details |
| Currency | Yes | HTG or USD |
Step 3: Upload CSV
Upload a CSV file with recipient information:CSV Columns
| Column | Required | Description |
|---|---|---|
| bousol_uid | Yes | Client external ID or Stellar wallet address |
| asset_amount | Yes | Amount to send |
Identifying Recipients
Thebousol_uid column accepts:
| Format | Example | Resolution |
|---|---|---|
| External ID | CUST001 | Looks up client by external ID, uses their wallet |
| Wallet Address | GABC...XYZ | Uses the address directly |
Step 4: Review Validation
After upload, the system validates each row:| Status | Description | Action Needed |
|---|---|---|
| Valid | Ready to pay | None |
| Invalid | Error found | Fix and re-upload |
| Error | Cause | Solution |
|---|---|---|
| Client not found | External ID doesn’t exist | Add client or use wallet address |
| Invalid wallet | Wallet address format incorrect | Verify the address |
| Invalid amount | Amount not a valid number | Check CSV formatting |
| Missing wallet | Client has no wallet address | Add wallet to client record |
Step 5: Submit for Approval
Once all rows are valid (or you’ve acknowledged invalid rows will be skipped):- Review the summary:
- Total recipients
- Total amount
- Valid vs. invalid rows
- Click Submit for Approval
Disbursement Status
| Status | Description |
|---|---|
| Processing | CSV is being validated |
| Pending Submit | Validation complete, ready to submit |
| Pending Approval | Submitted, awaiting approval |
| Executing | Approved, payments being sent |
| Completed | All payments sent |
| Failed | Execution failed |
| Rejected | Approval denied |
Status Flow
Approval Workflow
Disbursements typically require approval due to their batch nature:- Creator uploads CSV and submits
- Approver reviews recipient list and total amount
- Approver approves or rejects with comments
- System executes approved disbursements
Reviewing as Approver
When reviewing a disbursement:- Check the total amount matches expectations
- Review the recipient list for accuracy
- Verify the funding source has sufficient balance
- Approve or reject with a comment
Managing Disbursements
Viewing Disbursements
The list shows all disbursements with status filters:| Filter | Description |
|---|---|
| All | All disbursements |
| Pending | Awaiting action |
| Completed | Successfully executed |
| Failed | Execution failed |
Disbursement Actions
| Action | When Available | Description |
|---|---|---|
| View Details | Any status | See full disbursement info |
| View Items | Any status | See individual recipients |
| Re-upload CSV | Pending Submit | Upload corrected CSV |
| Submit | Pending Submit | Submit for approval |
| Approve | Pending Approval | Approve execution |
| Reject | Pending Approval | Deny execution |
| Retry | Failed | Retry failed payments |
| Cancel | Before execution | Cancel the disbursement |
Viewing Disbursement Items
Click on a disbursement, then View Items to see each recipient:| Column | Description |
|---|---|
| Row # | CSV row number |
| Recipient | Client name or wallet address |
| Amount | Payment amount |
| Status | Valid, Invalid, Sent, Failed |
| Error | Validation or execution error message |
Filtering Items
- All — All recipients
- Valid — Ready for payment
- Invalid — Has validation errors
- Sent — Successfully paid
- Failed — Payment failed
Validation Summary
The validation summary shows:| Metric | Description |
|---|---|
| Total Rows | Number of recipients in CSV |
| Valid | Rows ready for payment |
| Invalid | Rows with errors |
| Total Amount | Sum of valid payments |
Execution
When a disbursement executes:- System processes each valid recipient
- Payments are sent in batches for efficiency
- Each payment is recorded with transaction hash
- Failed payments can be retried
Partial Success
If some payments fail:- Successful payments are recorded as Sent
- Failed payments are marked for retry
- You can retry failed items without re-creating the disbursement
Best Practices
CSV Preparation
- Validate data before upload — Check for duplicates, invalid amounts
- Use consistent identifiers — Stick to external IDs or wallet addresses
- Keep backups — Save your CSV files for records
Amounts
- Double-check totals — Ensure the sum matches your expected disbursement
- Account for fees — Ensure sufficient balance including any fees
- Test first — For new processes, do a small test disbursement
Approval
- Clear descriptions — Name disbursements clearly (e.g., “January 2026 Payroll”)
- Document purpose — Use the description field
- Separate duties — Different people create and approve
Monitoring
- Track execution — Watch the status during execution
- Review failures — Investigate and retry failed payments promptly
- Keep records — Export completed disbursements for accounting