Funding covers how money moves between your user’s bank account and their investment wallet. Bluum supports ACH transfers via Plaid and manual bank transfers.
Deposit methods
| Method | How it works | Settlement |
|---|
ACH via Plaid (ach) | Automated pull from linked bank account | 1-3 business days |
Manual Bank Transfer (manual_bank_transfer) | User initiates a transfer from their bank using provided instructions | Varies (1-5 business days) |
Plaid Link integration
Before using ACH deposits, the user must link a bank account through Plaid Link. This is a two-step process:
1. Create a Link token
Your backend requests a Plaid Link token from Bluum:
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/funding-sources/plaid/link-token" \
-H "Authorization: Basic $AUTH" \
-H "Content-Type: application/json" \
-d '{ "enable_hosted_link": false }'
2. Exchange the public token
Your frontend launches Plaid Link with the token. After the user selects their bank, Plaid returns a public_token to your frontend. Send it to Bluum:
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/funding-sources/plaid/connect" \
-H "Authorization: Basic $AUTH" \
-H "Content-Type: application/json" \
-d '{ "public_token": "public-sandbox-abc123" }'
itemId, accountId) needed for deposits and withdrawals.
Your Frontend Your Backend Bluum API
│ │ │
│ │──── Create Link Token ────►│
│ │◄─── link_token ───────────│
│◄─── Launch Plaid Link ────────│ │
│──── User selects bank ────────►│ │
│──── public_token ─────────────►│ │
│ │──── Exchange Token ───────►│
│ │◄─── Bank account details ──│
Set enable_hosted_link: true for a Plaid-hosted redirect flow. The response includes a hosted_link_url you redirect the user to, instead of embedding the Plaid Link widget.
Deposit lifecycle
pending → processing → received → completed
│
failed
| Status | Meaning |
|---|
pending | Deposit created, not yet initiated |
processing | ACH transfer initiated with the bank |
received | Funds received, awaiting final settlement |
completed | Funds available in wallet |
failed | Transfer failed (insufficient funds, bank rejection) |
Withdrawal lifecycle
pending → processing → submitted → completed
│ │
canceled failed
pending status can be canceled.
Manual bank transfers
For manual_bank_transfer deposits, the response includes bank details and a reference code:
{
"method_details": {
"referenceCode": "BLUUM-ABC123XY",
"bankDetails": {
"bankName": "Choice Financial Group",
"accountName": "Bluum Finance, Inc.",
"accountNumber": "202534766488",
"routingNumber": "091311229",
"instructions": "Include reference code \"BLUUM-ABC123XY\" in your transfer memo."
}
},
"expires_at": "2025-06-22T10:45:00.000Z"
}
expires_at if funds are not received.
Wire details PDF
Download a formatted PDF with wire transfer instructions for a manual bank transfer deposit:
curl -X GET "$BASE_URL/accounts/$ACCOUNT_ID/deposits/$DEPOSIT_ID/wire-details" \
-H "Authorization: Basic $AUTH" \
--output wire-details.pdf
manual_bank_transfer.
Idempotency
Always include an Idempotency-Key header on deposit and withdrawal requests:
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/deposits" \
-H "Idempotency-Key: dep-unique-request-id-123" \
...
Key endpoints
| Method | Path | Description |
|---|
POST | /accounts/{id}/funding-sources/plaid/link-token | Create Plaid Link token |
POST | /accounts/{id}/funding-sources/plaid/connect | Exchange Plaid public token |
GET | /accounts/{id}/funding-sources | List linked funding sources |
POST | /accounts/{id}/deposits | Create a deposit |
GET | /accounts/{id}/deposits/{deposit_id} | Get deposit status |
POST | /accounts/{id}/deposits/{deposit_id}/cancel | Cancel a pending deposit |
GET | /accounts/{id}/deposits/{deposit_id}/wire-details | Download wire details PDF |
POST | /accounts/{id}/withdrawals | Create a withdrawal |
GET | /accounts/{id}/withdrawals/{withdrawal_id} | Get withdrawal status |
POST | /accounts/{id}/withdrawals/{withdrawal_id}/cancel | Cancel a pending withdrawal |
