Банк руу гаргах

Gerege Wallet данснаас (хүний эсвэл байгууллагын) мөнгийг бодит банкны данс руу гаргах хүсэлт илгээх, хянах, цуцлах. Уншихад ~6 минут. Хэрэгтэй: Gerege App-д нэвтэрсэн хүн, эсвэл байгууллагын админ; дансанд хүрэлцэх үлдэгдэл; бодит банкны дансны дугаар.

Яагаад гаргах нь «хүсэлт» вэ

Gerege Wallet-ийн банкны код 0098 нь Монголбанкнаас олгогдоогүй (түр код). Тиймээс бусад банк Gerege Wallet-ийн IBAN руу мөнгө шилжүүлж чадахгүй, Gerege Wallet ч бусад банк руу шууд шилжүүлж чадахгүй. Гаргалт бол хүсэлт: таны дансанд дүн барьцаалагдаж (давхар зарцуулагдахгүй), оператор өөрийн бодит банкны данснаас таны заасан данс руу шилжүүлээд банкны гүйлгээний дугаарыг бүртгэнэ. Цэнэглэх нь мөн адил операторын бодит дансаар дамжина.

Урсгал

1. Та хүсэлт илгээнэ → дансанд дүн барьцаалагдана → requested.
2. Оператор хүсэлтийг ажилд авна → processing (энэ мөчөөс цуцлах боломжгүй — оператор бодит банкаар шилжүүлж байна).
3. Оператор бодит банкаар шилжүүлээд банкны гүйлгээний дугаараа оруулна → paid, барьцаа таны данснаас хасагдана, bank_reference-д тэр дугаар. Эсвэл татгалзана → rejected, барьцаа буцаж суллагдана.
4. Та «Мөнгө гарлаа» (дүн, банкны нэр) эсвэл «буцлаа» мэдэгдэл авна; татгалзсан шалтгаан апп дотор.

Хугацаа: гаргалтыг оператор гараар хийдэг (ажлын цагт). Үйлчилгээний баталгаат хугацаа (SLA) — тодорхой болно.

Хүсэлт илгээх

Хэн	Зам
Хүн, өөрийн идэвхтэй MNT данс	POST /api/v1/bank/me/accounts/{id}/withdrawals
Байгууллагын админ	POST /api/v1/bank/org/{tenant}/accounts/{id}/withdrawals

curl -sS https://geregeapp.mn/api/v1/bank/me/accounts/$ACCOUNT_ID/withdrawals \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Idempotency-Key: wd-2026-10-27-0001" \
  -H "Content-Type: application/json" \
  -d '{"amount": 250000, "bank_name": "Хаан банк", "bank_account": "5012345678", "holder_name": "Алиса Бат"}'

Талбар	Дүрэм
amount	1 000 – 50 000 000 ₮, бүхэл; дансны боломжит үлдэгдлээс ихгүй
bank_name	2 – 100 тэмдэгт
bank_account	MN IBAN эсвэл 5 – 20 оронтой дугаар (зай, зураас хасагдана). Gerege Wallet-ийн (0098) IBAN бол use_transfer — шилжүүлэг хий
holder_name	2 – 100 тэмдэгт, хүлээн авах дансны эзэмшигч

• Idempotency-Key заавал, 8 – 128 тэмдэгт. Ижил key + ижил бие → тэр хүсэлт (200); өөр бие → 409 idempotency_conflict. Сүлжээ тасарвал (pending үлдэж болно) ижил key-ээр дахин илгээ.
• Нэг эзэмшигчид нэг дор нээлттэй (хүлээгдэж буй, processing хүртэл) 3 хүсэлт хүртэл.
• Rate limit — минутад 6.
• SMS баталгаа: дүн операторын тогтоосон босгоос их бол эхний хариу 428 confirmation_required {challenge_id, phone (далдалсан), expires_at}, таны баталгаажсан утас руу код очно. Ижил хүсэлтийг (ижил бие, ижил Idempotency-Key) X-Confirmation-Id: <challenge_id> ба X-Confirmation-Code: <код> толгойтой дахин илгээ. Код нь энэ данс, дүн, хүлээн авах данс, key-тэй холбоотой — өөр гаргалтад ажиллахгүй. Байгууллагын гаргалтад код админы өөрийн дугаарт очно.

Хариу 201 (шинэ) — гаргалтын харагдац, requested.

Гаргалтын объект

{
  "id": "4c1f…",
  "account_id": "…",
  "account_number": "0980000017",
  "amount": 250000,
  "currency": "MNT",
  "status": "requested",
  "destination": {"bank_name": "Хаан банк", "bank_account": "5012345678", "holder_name": "Алиса Бат"},
  "bank_reference": null,
  "failure_code": null,
  "reject_reason": null,
  "cancelable": true,
  "created_at": "…", "updated_at": "…",
  "processing_at": null, "paid_at": null, "rejected_at": null, "canceled_at": null
}

status	Утга	Цуцлах
pending	барьцааны хариу тодорхойгүй — ижил Idempotency-Key-ээр дахин илгээ; платформ 5 минутын дараа өөрөө шалгаж, 1 цагт олдохгүй бол failed (юу ч барьцаалагдаагүй)	тийм
requested	дүн барьцаалагдсан, операторын ээлжинд	тийм
processing	оператор ажилд авсан, бодит банкаар шилжүүлж байна	үгүй
paid	шилжүүлсэн; bank_reference = банкны гүйлгээний дугаар	—
rejected	оператор татгалзав (reject_reason), барьцаа суллагдсан	—
canceled	та цуцалсан, барьцаа суллагдсан	—
failed	барьцаа тавигдсангүй (failure_code: жишээ нь insufficient_funds, account_frozen, hold_not_placed)	—

Жагсаах, унших, цуцлах

Method	Зам (хүн; байгууллагад /api/v1/bank/org/{tenant}/…)	Хариу
GET	/api/v1/bank/me/accounts/{id}/withdrawals?limit=&before=	{"data": [Withdrawal], "next_before": time \| null} — шинэ нь эхэнд, limit анхдагч 50, ≤ 100; дараагийн хуудсанд before=<next_before>
GET	/api/v1/bank/me/accounts/{id}/withdrawals/{wid}	Withdrawal / 404
POST	/api/v1/bank/me/accounts/{id}/withdrawals/{wid}/cancel	pending / requested үед 200 (canceled, барьцаа суллагдана); аль хэдийн цуцалсан бол 200; бусад → 409 not_cancelable {status}

Байгууллагын хүсэлт, цуцлалт байгууллагын audit-д бичигдэнэ. Gerege App-д (iOS): хүн Хэтэвч → «Банк руу гаргах»-аас; байгууллагын админ Тохиргоо → Хэтэвч → «Байгууллагын данс»-аас (данс нээх, үлдэгдэл, гүйлгээ, гаргах). Хүсэлт илгээх, төлөв харах, оператор эхлүүлэхээс өмнө цуцлах — апп дотор.

Алдаа

HTTP	code	Хэзээ
400	—	Idempotency-Key алга эсвэл 8 – 128 биш
400	invalid_amount	1 000 – 50 000 000 биш
400	invalid_bank_name · invalid_holder_name	2 – 100 тэмдэгт биш
400	invalid_bank_account	MN IBAN эсвэл 5 – 20 орон биш
400	use_transfer	Gerege Wallet-ийн (0098) данс — гаргалт биш шилжүүлэг
403	—	байгууллагын route-д админ биш
404	—	данс таных биш / гаргалт алга
409	idempotency_conflict	key өөр хүсэлтэд ашиглагдсан
409	too_many_open	нээлттэй 3 хүсэлт бий (open)
409	not_cancelable	processing эсвэл дууссан (status)
422	account_unavailable	данснаас одоо мөнгө гарах боломжгүй (идэвхгүй, MNT биш)
422	insufficient_funds	боломжит үлдэгдэл хүрэлцэхгүй (мөр үүсэхгүй)
428	confirmation_required	SMS кодоор баталгаажуулна (дээр)
400 · 403 · 410 · 429 · 502 · 503	wrong_code (attempts_left), confirmation_invalid, phone_required, code_expired, too_many_codes, sms_failed, sms_unavailable	SMS баталгааны алдаа
503	withdrawals_unavailable	энэ суулгацад гаргалт идэвхгүй
503	license_required	дэвтэр түр зөвхөн уншина