API Reference

Quick Qr

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

Quick QR API

Quick QR API нь мерчант бүртгэх, QR нэхэмжлэх үүсгэх, төлбөрийн төлөв баталгаажуулах боломжийг HTTP REST API-аар олгоно.

Орчин

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

Нэвтрэлт

Quick QR нь хоёр алхамт token урсгал ашигладаг.

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

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

Authorization: Basic {base64(username:password)}

Request body дотор мерчантад холбогдох дараах утгыг дамжуулна:

terminal_id

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

Бусад endpoint-ууд дээр дараах header ашиглана:

Authorization: Bearer {access_token}

Token сунгах бол POST /v2/auth/refresh ашиглана.

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

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

  • aimaghot, sumduureg лавлах мэдээлэл авах
  • байгууллага болон хувь хүнээр мерчант бүртгэх
  • мерчантын мэдээлэл шинэчлэх, харах, устгах, жагсаалт авах
  • нэхэмжлэх үүсгэх, харах, цуцлах
  • POST /v2/payment/check ашиглан төлбөр баталгаажуулах

Endpoint бүлгүүд

Auth

Access token авах болон сунгах endpoint-ууд.

Merchant

Мерчант бүртгэх, профайл удирдах, бүртгэлд шаардлагатай хот аймаг болон сум дүүргийн лавлах утгууд авах endpoint-ууд.

Invoice

Quick QR нэхэмжлэх үүсгэх, дэлгэрэнгүй харах, төлөгдөөгүй нэхэмжлэх цуцлах endpoint-ууд.

Payment

Нэхэмжлэх төлөгдсөн эсэхийг шалгах endpoint.

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

  1. POST /v2/auth/token ашиглан access token авна.
  2. Хэрэв мерчант бүртгэх бол лавлах endpoint-уудаас city, district кодоо авна.
  3. Мерчантыг байгууллага эсвэл хувь хүнээр бүртгэнэ.
  4. POST /v2/invoice ашиглан нэхэмжлэх үүсгэнэ.
  5. Буцсан QR төлбөрийн мэдээллийг хэрэглэгчид харуулна.
  6. POST /v2/payment/check ашиглан төлбөрийг баталгаажуулна.

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

  • Token авах хүсэлт дээр terminal_id заавал шаардлагатай.
  • Мерчантын create/update endpoint-ууд нь мерчантын төрөл, регистрийн мэдээлэл, MCC төрлийн утгуудыг шалгана.
  • Нэхэмжлэх үүсгэх үед мерчант, дансны мэдээлэл, process code зэрэг талбаруудыг зөв дамжуулах шаардлагатай.

Зөвхөн 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-ий хугацаатай холбоотой алдаа биш.

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

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

Endpoints

15