Full API Reference
Complete list of all Mazad Wallet API endpoints. Every request requires authentication via your secret key in the Authorization: Bearer sk_sandbox_... header.
https://wallet.e-mazad.store/api/v1All paths below are relative to this base URL. For production, use https://wallet.e-mazad.store/api/v1.
Idempotency required
POST requests that create or modify resources should include an Idempotency-Key header with a UUID v4 value. See the Authentication page for details.Embedded Wallet — Users
Sync your platform users into Mazad and auto-provision wallets.
/embedded/users/syncCreate or update an embedded wallet user. Wallets are auto-created on first sync.
Embedded Wallet — Wallets
Read wallet balances and transaction history for embedded users.
/embedded/users/{id}/walletGet wallet details and all currency balances for an embedded user.
/embedded/users/{id}/transactionsList paginated transactions for an embedded user wallet.
Embedded Wallet — Checkout
Create checkout sessions and process payments through the hosted popup.
/embedded/checkout/sessionsCreate a new checkout session. Returns a session token for the popup.
/embedded/checkout/sessions/{id}Retrieve checkout session status and payment details.
Payments
Retrieve, capture, void, and refund payments.
/embedded/payments/{id}Get full payment details including status, amounts, and timestamps.
/embedded/paymentsList payments with optional filters for status, user, currency, and date range.
/embedded/payments/{id}/captureCapture an authorized payment. Supports full and partial capture.
/embedded/payments/{id}/voidVoid an authorized payment and release held funds.
/embedded/payments/{id}/refundRefund a completed payment. Supports full and partial refunds.
Payment Links
Generate shareable payment links that open a Mazad-hosted checkout page.
/payment-linksCreate a new payment link with amount, currency, and optional expiry.
/payment-linksList all payment links with optional status and date filters.
/payment-links/{id}Retrieve payment link details and usage statistics.
/payment-links/{id}Deactivate a payment link. Already-paid links cannot be deactivated.
QR Codes
Generate and process QR code payments for in-person transactions.
/qr/generateGenerate a merchant-presented QR code for a specific amount.
/qr/payProcess a payment by scanning a customer-presented QR code.
/qr/{id}Retrieve QR code details and payment status.
Subscriptions — Plans
Create and manage subscription plans with pricing, intervals, and trial periods.
/subscriptions/plansCreate a new subscription plan with amount, currency, and billing interval.
/subscriptions/plansList all subscription plans with optional status filter.
/subscriptions/plans/{id}Retrieve plan details including subscriber count and status.
Subscriptions — Management
Enroll subscribers and manage subscription lifecycle.
/subscriptionsCreate a new subscription by enrolling a customer in a plan.
/subscriptionsList subscriptions with filters for plan, status, and customer.
/subscriptions/{id}Retrieve subscription details including billing history.
/subscriptions/{id}/pausePause an active subscription. No charges until resumed.
/subscriptions/{id}/resumeResume a paused subscription and restart billing.
/subscriptions/{id}Cancel a subscription permanently.
Payroll
Submit batch payouts to multiple recipients in a single API call.
/payroll/batchesCreate and submit a new payroll batch with recipients and amounts.
/payroll/batches/{id}Get batch progress including per-recipient payout status.
/payroll/batches/{id}/payoutsList individual payouts within a batch with status details.
Wallets
Query wallet balances and transaction history directly.
/wallets/{wallet_id}/balancesGet all currency balances for a wallet.
/wallets/{wallet_id}/transactionsList wallet transactions with filters for type, currency, and date.
Foreign Exchange
Get real-time exchange rates and execute currency conversions.
/fx/ratesGet live exchange rates for a base currency.
/fx/quoteRequest an FX quote with locked rate. Valid for 15 seconds.
/fx/executeExecute a currency conversion using a valid quote.
/fx/historyList past FX trades with date and currency filters.
Session Tokens
Generate short-lived tokens for client-side SDK operations.
/session-tokensCreate a scoped session token for a specific user. Expires in 15 minutes.
Webhooks
Mazad sends webhook events to your configured endpoint for real-time notifications.
/webhooks (your server)Receive payment.completed, subscription.activated, and other lifecycle events.
Authentication Summary
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer sk_sandbox_... | Always |
| Content-Type | application/json | POST / PATCH |
| Idempotency-Key | UUID v4 | Recommended for POST |
HTTP Status Codes
| Status | Meaning |
|---|---|
| 200 | Success. The request completed and the response body contains the result. |
| 201 | Created. A new resource was created successfully. |
| 400 | Bad Request. The request body is malformed or missing required fields. |
| 401 | Unauthorized. API key is missing, invalid, or expired. |
| 403 | Forbidden. The API key does not have permission for this action. |
| 404 | Not Found. The requested resource does not exist. |
| 409 | Conflict. Idempotency key reused with different request body. |
| 422 | Unprocessable Entity. Validation failed (e.g., insufficient balance). |
| 429 | Too Many Requests. Rate limit exceeded. Retry after the indicated delay. |
| 500 | Server Error. Something went wrong on our end. Contact support if persistent. |
Detailed endpoint documentation
Ready to integrate Mazad into your platform?
Our team will review your business and issue your production API keys within 2 business days.