Embedded Wallet

Wallet API

Read wallet balances and transaction history for any embedded user. Use these endpoints to display financial data inside your platform UI.

Get wallet balance

GET/embedded/users/{id}/wallet

Retrieve the wallet details and all currency balances for an embedded user. The {id} can be either the mazad_user_id or your external_id.

Path Parameters

Name	Type	Required	Description
id	string	required	The mazad_user_id (mzd_usr_...) or your external_id.

Request example

curl -X GET https://wallet.e-mazad.store/api/v1/embedded/users/usr_12345/wallet \
  -H "Authorization: Bearer sk_sandbox_abc123"

Response

{
  "success": true,
  "data": {
    "wallet_id": "wal_a1b2c3d4e5f6",
    "mazad_user_id": "mzd_usr_9f8e7d6c5b4a",
    "external_id": "usr_12345",
    "status": "active",
    "balances": [
      {
        "currency": "IQD",
        "available": 1500000,
        "held": 250000,
        "total": 1750000
      },
      {
        "currency": "USD",
        "available": 5000,
        "held": 0,
        "total": 5000
      }
    ],
    "created_at": "2026-03-15T10:30:00Z"
  }
}

Balance fields

available is the amount the user can spend right now. held is the amount locked by pending payments or escrow holds. total = available + held. All amounts are in the smallest currency unit (fils for IQD, cents for USD).

List transactions

GET/embedded/users/{id}/transactions

Retrieve a paginated list of transactions for an embedded user's wallet. Returns most recent transactions first.

Path Parameters

Name	Type	Required	Description
id	string	required	The mazad_user_id (mzd_usr_...) or your external_id.

Query Parameters

Name	Type	Required	Description
currency	string	optional	Filter by currency code (e.g., IQD, USD). Defaults to all currencies.
type	string	optional	Filter by transaction type: credit, debit, hold, release, refund.
from	string	optional	Start date in ISO 8601 format (e.g., 2026-03-01T00:00:00Z).
to	string	optional	End date in ISO 8601 format.
page	integer	optional	Page number for pagination. Defaults to 1.
per_page	integer	optional	Results per page. Min 1, max 100. Defaults to 20.

Request example

curl -X GET "https://wallet.e-mazad.store/api/v1/embedded/users/usr_12345/transactions?currency=IQD&per_page=10&page=1" \
  -H "Authorization: Bearer sk_sandbox_abc123"

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_f1e2d3c4b5a6",
        "type": "debit",
        "amount": 50000,
        "currency": "IQD",
        "description": "Payment for Order #1234",
        "reference": "pay_x1y2z3",
        "balance_after": 1450000,
        "created_at": "2026-03-20T14:22:00Z"
      },
      {
        "id": "txn_a9b8c7d6e5f4",
        "type": "credit",
        "amount": 1500000,
        "currency": "IQD",
        "description": "Wallet top-up",
        "reference": "top_m1n2o3",
        "balance_after": 1500000,
        "created_at": "2026-03-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 2,
      "total_pages": 1
    }
  }
}

Rate limiting

The transactions endpoint is rate-limited to 60 requests per minute per merchant. For high-volume integrations, use webhooks to track transactions in real-time instead of polling this endpoint.

User Sync Checkout Popup