Overview
This guide explains the complete disbursement workflow with Decaf for platforms, payroll teams, NGOs, and marketplaces. You can send funds by phone number and recipients claim directly through WhatsApp.
What you'll learn
- How to set up your account and API credentials - How to create and submit disbursements - How to monitor statuses and delivery outcomes - What recipients experience when claiming funds
Setup
1. Register your company with Decaf and complete onboarding checks. 2. Generate your API credentials and store them securely. 3. Configure your source of funds and payout preferences. 4. Prepare recipient records with valid phone numbers and reference IDs.
Create disbursements
You can create individual disbursements or run batch disbursements for payroll and aid programs.
Best practices
- Always send a unique idempotency key per payout attempt. - Include your internal reference to simplify reconciliation. - Validate recipient phone format before submission. - Add metadata for your finance and operations reporting.
Monitor and review
Track every disbursement lifecycle state from creation to delivery: - pending - claimed - processing - delivered - failed - expired - cancelled
Use API reads and webhooks together:
- API reads help with on-demand checks and back-office views. - Webhooks keep your systems in sync in real time.
Recipient experience
Recipients are notified on WhatsApp and can claim without downloading a new app. Typical flow: 1. Recipient receives notification. 2. Recipient chooses payout method (bank transfer, cash pickup, or wallet options where available). 3. Recipient confirms details. 4. Funds are delivered.
Operational recommendations
- Build retry logic with idempotency awareness. - Alert on failed and expired disbursements. - Reconcile daily totals against your internal ledger. - Keep webhook signature verification enabled in production.
Need integration support? Contact the Decaf integrations team at integrations@decaf.so.