Moneyar Wallet API

WalletV2Core · v1.0

The Moneyar digital wallet and payment platform. This document covers the six endpoints required to integrate a client application: create account, balance, cash‑in, cash‑out, transfer, and the transaction report. سامانهٔ کیف پول و پرداخت دیجیتال مانی‌یار. این مستند شش سرویس مورد نیاز برای یکپارچه‌سازی اپلیکیشن مشتری را پوشش می‌دهد: ایجاد حساب، موجودی، واریز، برداشت، انتقال وجه و گزارش تراکنش‌ها.

شرکت نوآروان پیشرو مانی‌یار · Noavaran Pishro Moneyar

Base URLhttps://wallet.moneyar.com production SecurityHTTP Basic — client id & client secret MethodsAll six endpoints are POST Content typeapplication/json · UTF-8 CurrencyIRR — the only supported value

Signup flow — create the wallet / جریان ثبت‌نام

⚑ Required at every signup. When a user registers in your app, you must call POST /api/createaccount for them. The response returns an account UID — persist this value on your user record as their wallet id. Every other endpoint (balance, cash‑in, cash‑out, transfer, report) identifies the wallet by that UID and by nothing else. If you lose it, the user has no way back to their wallet. هنگام ثبت‌نام هر کاربر در اپلیکیشن، باید سرویس POST /api/createaccount را برای او فراخوانی کنید. پاسخ، یک شناسهٔ یکتا در فیلد account برمی‌گرداند؛ این مقدار را حتماً در رکورد کاربر به‌عنوان شناسهٔ کیف پول ذخیره کنید. تمام سرویس‌های دیگر (موجودی، واریز، برداشت، انتقال و گزارش) کیف پول را فقط با همین شناسه می‌شناسند و در صورت از دست رفتن آن، دسترسی کاربر به کیف پولش ممکن نخواهد بود.

User completes signup in your app.کاربر ثبت‌نام را در اپلیکیشن شما کامل می‌کند.
Call POST /api/createaccount with currency: "IRR", the user's national code and phone number, and your own user id in externalId.سرویس POST /api/createaccount را با currency: "IRR"، کد ملی و شمارهٔ همراه کاربر و شناسهٔ کاربر در سامانهٔ خودتان در فیلد externalId فراخوانی کنید.
Read account from the response and save it as walletId on the user record.مقدار account را از پاسخ بخوانید و به‌عنوان walletId روی رکورد کاربر ذخیره کنید.
Use that walletId for every later call — as accountId, destinationid, sourceid, sourceAccountId or accountuid depending on the endpoint.در تمام فراخوانی‌های بعدی از همان walletId استفاده کنید؛ بسته به سرویس، در فیلدهای accountId، destinationid، sourceid، sourceAccountId یا accountuid.

Authentication / احراز هویت

Every endpoint requires an Authorization header carrying your client id and client secret. The authenticated client determines which wallets you can see and operate on. همهٔ سرویس‌ها به هدر Authorization شامل شناسه و کلید مخفی کلاینت نیاز دارند. کیف پول‌های قابل دسترس، بر اساس همان کلاینت احراز هویت‌شده تعیین می‌شود.

Authorization: Basic CLIENTID:CLIENTSECRET
Content-Type: application/json
accept: application/json

Credentials are issued to you by Moneyar. Keep the secret server‑side — never ship it in a mobile or browser client. اطلاعات احراز هویت توسط مانی‌یار در اختیار شما قرار می‌گیرد. کلید مخفی را فقط در سمت سرور نگه دارید و هرگز آن را در اپلیکیشن موبایل یا کلاینت مرورگر قرار ندهید.

Response envelope / ساختار پاسخ

Every response is a flat JSON object carrying code and message, plus the endpoint's own fields at the same level. There is no nested data object. Check code === 0 for success — do not rely on the HTTP status alone. همهٔ پاسخ‌ها یک شیء JSON تخت هستند که شامل code و message به‌همراه فیلدهای اختصاصی همان سرویس در یک سطح‌اند و شیء تودرتوی data وجود ندارد. برای تشخیص موفقیت، مقدار code === 0 را بررسی کنید و صرفاً به کد وضعیت HTTP اکتفا نکنید.

Field	Type	Description
code	integer	`0` means success. A non‑zero value is a business error.مقدار `0` یعنی موفقیت؛ هر مقدار غیرصفر خطای کسب‌وکاری است.
message	string	Human‑readable result. May be an empty string on success.پیام قابل خواندن نتیجه؛ ممکن است در حالت موفق خالی باشد.
…	varies	Endpoint‑specific fields: `account`, `balance`, `url`, `transactionid`, `report`.فیلدهای اختصاصی هر سرویس.

Conventions / قراردادها

Topic	Rule
currency	Mandatory, and must be exactly `"IRR"`. Any other value creates a non‑monetary wallet — the balance is treated as points / loyalty credit rather than Rial. Send `"IRR"` on every create‑account call.اجباری است و باید دقیقاً `"IRR"` باشد. هر مقدار دیگری، کیف پول را غیرریالی می‌سازد و موجودی آن به‌جای ریال به‌صورت امتیاز در نظر گرفته می‌شود. در همهٔ فراخوانی‌های ایجاد حساب مقدار `"IRR"` را ارسال کنید.
method	All six endpoints are `POST` with a JSON body — including balance and the transaction report.هر شش سرویس از نوع `POST` با بدنهٔ JSON هستند، از جمله موجودی و گزارش تراکنش.
wallet id	The UID returned by create‑account. The field name differs per endpoint: `accountId`, `destinationid`, `sourceid`, `sourceAccountId`, `accountuid`. Follow each table exactly.همان شناسهٔ بازگشتی از سرویس ایجاد حساب. نام فیلد در هر سرویس متفاوت است؛ دقیقاً مطابق جدول هر سرویس عمل کنید.
amount	Plain JSON number in Rial, e.g. `50000`. No separators, no decimals.عدد ساده به ریال، بدون جداکننده و اعشار.
resnum	Your own reference number on cash‑in and transfer. Use a unique value per request so you can reconcile against your records later.شمارهٔ پیگیری اختصاصی شما در سرویس‌های واریز و انتقال؛ برای هر درخواست مقدار یکتا بگذارید تا مغایرت‌گیری ممکن باشد.
dates	Returned as `"YYYY-MM-DD HH:mm:ss"` strings, e.g. `"2026-08-19 11:36:27"`. Not ISO‑8601, no timezone suffix.تاریخ‌ها به‌صورت رشتهٔ `"YYYY-MM-DD HH:mm:ss"` بازگردانده می‌شوند؛ فرمت ISO‑8601 نیست و پسوند منطقهٔ زمانی ندارد.
field typo	`destiantioniban` on cash‑out is misspelled in the API itself. Send it exactly as documented — do not "fix" it in your client.نام فیلد `destiantioniban` در سرویس برداشت، در خود API غلط املایی دارد؛ آن را دقیقاً به همان شکل ارسال کنید و در کلاینت اصلاح نکنید.

Endpoints / سرویس‌ها

Status codes / کدهای وضعیت

Code	Meaning
200	Request handled. Still check `code` in the body — `0` is success.درخواست پردازش شد. همچنان مقدار `code` در بدنه را بررسی کنید؛ صفر یعنی موفق.
400	Bad Request — malformed body, unknown wallet id, or a business rule rejection such as insufficient balance.درخواست نامعتبر: بدنهٔ نادرست، شناسهٔ کیف پول ناشناخته، یا رد شدن بر اساس قواعد کسب‌وکار مانند موجودی ناکافی.
401	Unauthorized — missing or wrong client credentials.احراز هویت ناموفق: اطلاعات کلاینت ارسال نشده یا نادرست است.

Only 200 and 400 are documented for these six endpoints. The full list of business code values is not published — treat any non‑zero code as a failure and surface message. برای این شش سرویس تنها کدهای ۲۰۰ و ۴۰۰ مستند شده‌اند. فهرست کامل مقادیر code منتشر نشده است؛ هر مقدار غیرصفر را خطا در نظر بگیرید و message را نمایش دهید.

Models / مدل‌ها

Request models for the six endpoints, confirmed against live responses. مدل‌های درخواست شش سرویس، تطبیق‌داده‌شده با پاسخ‌های واقعی سرویس.