Wallets
Wallets Overview
Understand the difference between the Embedded Wallet API and the direct Wallet API, and choose the right approach for your integration.
Two ways to work with wallets
Mazad provides two wallet integration approaches depending on your platform architecture and needs.
Recommended
Embedded Wallet API
Wallets are automatically created when you sync users. Your platform acts as the custodian and manages wallets on behalf of your users through server-to-server API calls.
- ✓Auto wallet creation via user sync
- ✓Merchant-initiated transfers and holds
- ✓Checkout popup for collecting payments
- ✓Full control over the user experience
Direct Wallet API
Query wallet balances, list transactions, and perform FX conversions directly. Useful for building dashboards, analytics, or when you need read access to wallet data.
- ✓Read wallet balances across currencies
- ✓List and filter transaction history
- ✓Real-time FX rates and currency conversion
- ✓Ideal for admin panels and reporting
When to use which
Choose the right API based on what you are building.
| Scenario | Use |
|---|---|
| Collecting payments from users | Embedded Wallet (Checkout Popup) |
| Moving funds between user wallets | Embedded Wallet (Transfers) |
| Holding funds in escrow | Embedded Wallet (Holds) |
| Displaying balance in your dashboard | Direct Wallet API (Balances) |
| Showing transaction history to users | Direct Wallet API (Transactions) |
| Converting between currencies | Direct Wallet API (FX) |
| Building an admin reporting panel | Direct Wallet API (Balances + Transactions) |
| Paying out to multiple users | Payroll API (Batches) |
Both APIs use the same wallets
The Embedded Wallet API and Direct Wallet API operate on the same underlying wallet objects. You can freely use both APIs together — for example, use Embedded Wallet for payments and Direct Wallet API for balance queries.
In this section
The following pages cover the Direct Wallet API endpoints.