API Reference

eBarimt 3.0

Version 3.0.0PaymentsPublic
Postman collection татахRelease notes

eBarimt 3.0 API

QPay eBarimt 3.0 API нь мерчантын нэхэмжлэх үүсгэх, төлбөр амжилттай эсэхийг баталгаажуулах, тухайн төлбөр дээр и-баримт үүсгэх эсвэл цуцлах боломжийг HTTP REST API-аар олгоно.

Орчин

  • Sandbox: https://merchant-sandbox.qpay.mn
  • Production: https://merchant.qpay.mn

Нэвтрэлт

eBarimt 3.0 нь Merchant API-ийн хоёр алхамт token урсгалыг ашиглана.

Алхам 1 - Access token авах

POST /v2/auth/token endpoint-ийг дараах header-тай дуудна:

Authorization: Basic {base64(client_id:client_secret)}

Алхам 2 - Хамгаалагдсан endpoint дуудах

Invoice, payment, eBarimt endpoint-ууд дээр дараах header ашиглана:

Authorization: Bearer {access_token}

Үндсэн боломжууд

Энэхүү API нь дараах үйлдлүүдийг дэмжинэ:

  • eBarimt татварын мэдээлэлтэй мерчантын нэхэмжлэх үүсгэх
  • payment callback авсны дараа төлбөр төлөгдсөн эсэхийг шалгах
  • төлөгдсөн гүйлгээ дээр и-баримт үүсгэх
  • иргэн эсвэл байгууллагад и-баримт үүсгэх
  • төлбөр буцаагдсан үед бүртгэгдсэн и-баримтыг цуцлах

Endpoint бүлгүүд

Auth

Merchant API дуудлагад ашиглах access token авах endpoint.

Invoice

Төлөх боломжтой нэхэмжлэх үүсгэнэ. eBarimt-д шаардлагатай district_code, tax_type, classification_code, мөрийн татварын мэдээлэл зэрэг талбаруудыг дамжуулна.

Payment

Нэхэмжлэх төлөгдсөн эсэхийг баталгаажуулж, буцсан payment_id утгыг авна.

Ebarimt

Төлөгдсөн гүйлгээнд и-баримт үүсгэх эсвэл payment_id-аар и-баримт цуцлах endpoint-ууд.

Гүйлгээний урсгал

Бүрэн урсгал нь хоёр үе шаттай: нэхэмжлэл үүсгэх (НЭХЭМЖЛЭЛ ҮҮСГЭХ) ба гүйлгээ шалгах (ГҮЙЛГЭЭ ШАЛГАХ). Томруулж харахын тулд зураг дээр дарна уу.

eBarimt 3.0 төлбөрийн урсгал: мерчант нэхэмжлэх үүсгэж, хэрэглэгч QR эсвэл deeplink-ээр төлж, мерчант төлбөрийг баталгаажуулсны дараа и-баримт үүсгэнэ

Зөвлөмжит интеграцийн дараалал

  1. POST /v2/auth/token ашиглан access token авна.
  2. POST /v2/invoice ашиглан нэхэмжлэх үүсгэхдээ шаардлагатай eBarimt татварын талбаруудыг дамжуулна.
  3. Буцсан QR эсвэл deeplink төлбөрийн мэдээллийг хэрэглэгчид харуулна.
  4. Callback авсны дараа POST /v2/payment/check ашиглан төлбөрийг баталгаажуулна.
  5. Буцсан payment_id ашиглан POST /v2/ebarimt_v3/create endpoint-оор и-баримт үүсгэнэ.
  6. Төлбөр буцаагдсан бол DELETE /v2/ebarimt_v3/{payment_id} endpoint-оор и-баримтыг цуцална.

Анхаарах зүйлс

  • Production орчинд и-баримт үүсгэхээс өмнө QPay-д хандан eBarimt тохиргоог идэвхжүүлнэ.
  • Иргэнд баримт үүсгэх бол ebarimt_receiver_type: CITIZEN, байгууллагад бол COMPANY ашиглана.
  • Нэхэмжлэхийн tax_type талбарын дэмжигдэх утгууд нь 1, 2, 3.
  • Payment status-ийг cron job-оор байнга шалгахгүй; payment callback авсны дараа POST /v2/payment/check дуудна.

Зөвхөн QPay API-ийн хариугаар ирсэн deeplink болон түүнтэй холбоотой мэдээллийг өөрчлөлтгүй ашиглана. Мерчант deeplink-ийг өөрөө зохиох, параметрүүдийг өөрчлөх, эсвэл QPay-ээс ирсэн өгөгдлийг өөрийн хэрэгцээнд тохируулан өөрчилсний улмаас үүссэн алдаа, мөн QPay-ийн системийн шинэчлэлтийн дараа эдгээр өөрчлөлтөөс шалтгаалан интеграц ажиллахгүй болсон тохиолдолд QPay хариуцлага хүлээхгүй.

Token, deeplink болон бусад string төрлийн хариу өгөгдлийн урт тогтмол биш бөгөөд системийн шинэчлэлтээр уртсаж болно. Хадгалах шаардлагатай бол өгөгдлийн сандаа TEXT зэрэг хувьсах урттай, хангалттай багтаамжтай төрөл ашиглана. Одоогийн жишээ өгөгдлийн уртаар багана, validation-ийн хязгаар тогтоох, өгөгдлийг таслахгүй. Хүсэлтийн талбаруудад schema-д тодорхой заасан maxLength хязгаарыг мөрдөнө.

QPay аюулгүй байдлын шаардлагатай шинэчлэлт хийхэд token хугацаанаасаа өмнө хүчингүй болж, API 401 эсвэл 403 HTTP status буцааж болно. Мерчантын систем ийм хариуг боловсруулж, хадгалсан token-ийг хүчингүйд тооцон POST /v2/auth/token-оор шинэ token автоматаар авч, хүсэлтийг хамгийн ихдээ нэг удаа дахин илгээдэг байна. Шинэ token авсан ч алдаа үргэлжилбэл давталтыг зогсоож, эрх болон тохиргоогоо шалган QPay-д хандана. 401 / 403 нь зөвхөн token-ий хугацаатай холбоотой алдаа биш.

Access token-ий үндсэн хүчинтэй хугацаа 24 цаг боловч мерчантын тохиргооноос хамаарч өөр байж болно. Бодит дуусах хугацааг хариуны expires_in Unix timestamp (секунд)-аар шалгана. Энэ нь үлдсэн секундийн тоо биш; 24 цагийг коддоо тогтмол утгаар тооцохгүй.

Нэхэмжлэх үүсгэх бүрд шинэ token авахгүй; хүчинтэй token-оо дахин ашиглана. Access болон refresh token-ийг мерчантын серверийн memory storage эсвэл хугацаатай memory cache-д хадгалахыг зөвлөж, өгөгдлийн санд байнга хадгалахаас аль болох зайлсхийнэ. Token-ийг хэрэглэгчийн browser-ийн localStorage / sessionStorage-д хадгалахгүй. Хугацаа дуусахад эсвэл token хүчингүй болоход автоматаар шинэчилнэ.

Endpoints

5