Embedded Wallet

User Sync

Mirror your platform users into Mazad. Each synced user automatically receives a wallet with IQD and multi-currency sub-wallets ready for transactions.

POST/embedded/users/sync

Create or update an embedded wallet user. If the external_id already exists, the user record is updated (upsert). A wallet is auto-created on first sync.

Request Body

Name	Type	Required	Description
external_id	string	required	Your unique user identifier. Max 128 characters. Used as the idempotency key.
full_name	string	required	Full legal name of the user. Used for KYC display.
email	string	optional	User email address. Must be a valid email format.
phone	string	optional	Phone number in E.164 format (e.g., +9647701234567).
metadata	object	optional	Arbitrary key-value pairs (max 20 keys, 500 chars per value). Stored with the user.
default_currency	string	optional	ISO 4217 currency code for the primary wallet. Defaults to IQD.

Request example

curl -X POST https://wallet.e-mazad.store/api/v1/embedded/users/sync \
  -H "Authorization: Bearer sk_sandbox_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "usr_12345",
    "full_name": "Ahmed Al-Rashid",
    "email": "ahmed@example.com",
    "phone": "+9647701234567",
    "metadata": {
      "plan": "premium",
      "signup_source": "mobile_app"
    },
    "default_currency": "IQD"
  }'

Response

{
  "success": true,
  "data": {
    "mazad_user_id": "mzd_usr_9f8e7d6c5b4a",
    "external_id": "usr_12345",
    "full_name": "Ahmed Al-Rashid",
    "email": "ahmed@example.com",
    "phone": "+9647701234567",
    "wallet_id": "wal_a1b2c3d4e5f6",
    "default_currency": "IQD",
    "metadata": {
      "plan": "premium",
      "signup_source": "mobile_app"
    },
    "created_at": "2026-03-15T10:30:00Z",
    "updated_at": "2026-03-15T10:30:00Z"
  }
}

Idempotent by external_id

Calling /embedded/users/sync multiple times with the same external_id will not create duplicate users. The first call creates the user and wallet; subsequent calls update the mutable fields (name, email, phone, metadata). The wallet is never re-created.

Common mistakes

Using mutable IDs as external_id

Do not use email addresses or phone numbers as your external_id. If the user changes their email, you will create a second wallet. Use your database primary key or a stable UUID.

Missing phone format

Phone numbers must be in E.164 format including the country code. 07701234567 will be rejected — use +9647701234567 instead.

Metadata size limits

The metadata object supports a maximum of 20 keys. Each key can be up to 40 characters, and each value up to 500 characters. Exceeding these limits returns a 422 validation error.

EW Overview Wallet API