API Integration Guide

Ushbu qo‘llanma onboarding jarayonidan boshlab tokenlarni olish va autentifikatsiyadan o‘tgan API so‘rovlarini yuborishgacha bo‘lgan to‘liq integratsiya oqimini tushuntiradi.

1. Onboarding Process

What is onboarding?

Onboarding bu API uchun kerak bo‘ladigan ma’lumotlarni olishga mo‘ljallangan bir martalik boshlang‘ich sozlash jarayoni.

Bu jarayon orqali siz quyidagi ma’lumotlarni olasiz:

username
password
consumer_key
consumer_secret

Jarayonni boshlash uchun Paylov tomonidan berilgan onboarding token kerak bo’ladi.

Xavfsizlik qoidalari

Onboarding yakunlangach, username va password siz tomoningizda belgilanadi, consumer_key va consumer_secret esa Paylov tomonidan taqdim etiladi.

To’rtta ma’lumotni ham qat’iy maxfiy saqlang. Ulardan parol kabi foydalaning — hech kimga bermang, mijoz tomonidagi kodda yoki ochiq repositorylarda chiqarmang, xavfsiz secrets manager yoki muhit o’zgaruvchilarida saqlang.

consumer_secret sizib chiqqan yoki begona shaxsga ma’lum bo’lgan taqdirda, darhol Paylov ma’muriyatiga xabar bering — ushbu credentials zudlik bilan revoke qilinadi.

Step 1: Verify onboarding token

Avval onboarding token haqiqiy ekanini tekshirishingiz kerak.

Endpoint

http

GET {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Parameters

token required — onboarding token

Example request

bash

curl -X GET "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"

Success response `200 OK`

json

{
  "status": "ok"
}

Error response `400 Bad Request`

json

{
  "error": "invalid_or_expired"
}

Step 2: Set username and password

Token tekshirilgandan keyin username va password yaratasiz. Shu jarayondan so‘ng sizga consumer_key va consumer_secret qaytariladi.

Password requirements

password quyidagi talablarga mos bo‘lishi kerak:

kamida 8 ta belgidan iborat bo‘lishi kerak
kamida bitta kichik harf a-z bo‘lishi kerak
kamida bitta katta harf A-Z bo‘lishi kerak
kamida bitta raqam 0-9 bo‘lishi kerak
kamida bitta maxsus belgi bo‘lishi kerak, masalan !@#$%^&*

Valid password examples

Secure@Pass123!
MyP@s3W0rd
Tr0pic@lLh!eze

Invalid password examples

password123 — katta harf va maxsus belgi yo‘q
Pass123 — juda qisqa
PASSWORD123! — kichik harf yo‘q

Endpoint

http

POST {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Request headers

http

Content-Type: application/json

Request body

json

{
  "username": "...",
  "password": "..."
}

Example request

bash

curl -X POST "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN" \
-H "accept: */*" \
-H "Content-Type: application/json" \
-d '{
  "username": "...",
  "password": "..."
}'

Success response `200 OK`

json

{
  "consumer_key": "app_a1b2c3d4e5f6g7h8i9j0k1",
  "consumer_secret": "Ks8Lp90q0Rr1Ss2Tt3Uu4Vv5Ww6Xx7Yy8Zz9Aa0Bb1Cc2Dd3Ee",
  "username": "my_username"
}

Important notes

consumer_key va consumer_secret sizning API credentials ma’lumotlaringiz hisoblanadi. Ularni xavfsiz joyda saqlang.
consumer_secret faqat bir marta ko‘rsatiladi. Uni yo‘qotsangiz, yangi credentials yaratishingizga to‘g‘ri keladi.
Onboarding token faqat bir marta ishlatiladi.
username va password ma’lumotlarini ham xavfsiz saqlang.

Account aktivatsiyasi

consumer_key va consumer_secret olinganidan so‘ng account darhol faol bo‘lmaydi. Account Paylov administratorlari tomonidan aktivlashtirilmaguncha ushbu credentials orqali access_token olish va API so‘rovlarini yuborish imkoni bo‘lmaydi.

Onboarding yakunlangach, account aktivlashtirilishi haqida Paylov bilan bog‘laning va tasdiq olganingizdan keyin integratsiyani davom ettiring.

2. Obtaining Access Token

What is an access token?

access_token autentifikatsiyadan o‘tgan API so‘rovlarini yuborish uchun kerak bo‘ladi. Uni har bir API so‘rovda yuborishingiz kerak.

Token request process

Endpoint

http

POST {BASE_URL}/merchant/oauth2/token/

Authentication

consumer_key va consumer_secret qiymatlarini base64 formatga encode qilib, Basic Authentication ishlatiladi.

Request headers

bash

Authorization: Basic base64(consumer_key:consumer_secret) # YycX3bGtsMnJfWH...
Content-Type: application/json

Request body

json

{
  "grant_type": "password",
  "username": "some-username",
  "password": "strong-password"
}

grant_type required — password yoki refresh_token
username — grant_type=password bo‘lganda required
password — grant_type=password bo‘lganda required

Eslatma

Request body faqat JSON formatda qabul qilinadi. Maydonlarga null yuborilsa, 400 validation_error qaytadi.

Step 1: Prepare Basic Authorization

consumer_key va consumer_secret quyidagi formatda birlashtiriladi:

text

consumer_key:consumer_secret

So‘ng ushbu qiymat base64 formatga encode qilinadi.

Step 2: Send token request

Example request

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/" \
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>" \
-H "Content-Type: application/json" \
-d '{
  "grant_type": "password",
  "username": "my_username",
  "password": "secure_password_123"
}'

Success response `200 OK`

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

Response explanation

access_token — API so‘rovlar uchun ishlatiladigan token, 1 soat amal qiladi
refresh_token — yangi access_token olish uchun ishlatiladi, 30 kun amal qiladi
expires_in — access_token amal qilish muddati, sekundlarda
refresh_expires_in — refresh_token amal qilish muddati, sekundlarda

Error response `401 Unauthorized`

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "Invalid credentials"
  }
}

this account not activated

Onboarding token orqali credentials olingandan keyin hisob darhol faol bo‘lmaydi. Hisob Paylov adminlari tomonidan active qilinmaguncha token so‘rovi quyidagi xatolikni qaytaradi:

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "this account not activated"
  }
}

Bu holatda credentials noto‘g‘ri emas — hisobni faollashtirish uchun Paylov ma’muriyatiga murojaat qiling.

3. Making API Requests with Access Token

Using access token

Har bir API so‘rovda Authorization header ichida access_token yuborilishi kerak.

Header format

http

Authorization: Bearer YOUR_ACCESS_TOKEN

Example request

bash

curl -X GET "https://{BASE_URL}/merchant/status/" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Refreshing Access Token

access_token muddati tugaganda, yangi token olish uchun refresh_token ishlatiladi. Bu jarayonda username va password ni qayta yuborish shart emas.

Endpoint

http

POST {BASE_URL}/merchant/oauth2/token/

Request headers

http

Authorization: Basic base64(consumer_key:consumer_secret)
Content-Type: application/json

Request body

json

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

refresh_token — grant_type=refresh_token bo‘lganda required

Example request

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/" \
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>" \
-H "Content-Type: application/json" \
-d '{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Success response `200 OK`

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

INFO

Refresh muvaffaqiyatli bo‘lgach, eski refresh_token bekor qilinadi. Keyingi so‘rovlarda faqat yangi qaytarilgan refresh_token dan foydalaning.

5. Revoking Tokens

Token’dan keyin foydalanilmasligi uchun uni bekor qilishingiz mumkin. Faqat access_token bekor qilinadi.

Endpoint

http

POST {BASE_URL}/merchant/oauth2/revoke/

Request headers

http

Content-Type: application/json

Request body

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example request

bash

curl -X POST "https://{BASE_URL}/merchant/oauth2/revoke/" \
-H "Content-Type: application/json" \
-d '{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Success response `200 OK`

json

{
  "status": "success"
}

Error response `400 Bad Request`

json

{
  "result": null,
  "error": {
    "code": "invalid_token",
    "message": "Token not found or already revoked"
  }
}

6. Error Handling

Barcha xatoliklar quyidagi formatda qaytariladi:

json

{
  "result": null,
  "error": {
    "code": "invalid_grant",
    "message": "Invalid credentials"
  }
}

`400 Bad Request`

`code`	`message`	Sababi
`invalid_request`	`Basic Authorization header required`	`Authorization` header yuborilmagan yoki `Basic` bilan boshlanmaydi
`invalid_request`	`Invalid Authorization header format`	`base64(consumer_key:consumer_secret)` noto‘g‘ri formatda
`invalid_request`	`username and password required`	`grant_type=password` da `username` yoki `password` yuborilmagan
`invalid_request`	`refresh_token required`	`grant_type=refresh_token` da `refresh_token` yuborilmagan
`unsupported_grant_type`	`Grant type '...' is not supported`	`grant_type` `password` yoki `refresh_token` emas
`validation_error`	—	Body maydonlari noto‘g‘ri yoki `null` yuborilgan
`invalid_token`	`Token not found or already revoked`	Revoke qilinayotgan token topilmadi yoki allaqachon bekor qilingan
`invalid_or_expired`	`Token is invalid or expired`	Onboarding token noto‘g‘ri yoki muddati tugagan

`401 Unauthorized`

grant_type=password uchun:

`code`	`message`	Sababi
`invalid_grant`	`Invalid consumer key`	`consumer_key` noto‘g‘ri yoki faol emas
`invalid_grant`	`Invalid consumer secret`	`consumer_secret` noto‘g‘ri
`invalid_grant`	`IP address not in whitelist`	So‘rov IP manzili ruxsat etilganlar ro‘yxatida yo‘q
`invalid_grant`	`Invalid credentials`	`username` yoki `password` noto‘g‘ri
`invalid_grant`	`this account not activated`	Hisob hali adminlar tomonidan active qilinmagan
`invalid_grant`	`User account is locked`	Parol ko‘p marta noto‘g‘ri kiritilgani uchun hisob bloklangan

grant_type=refresh_token uchun:

`code`	`message`	Sababi
`invalid_client`	`Invalid consumer key`	`consumer_key` noto‘g‘ri yoki faol emas
`invalid_grant`	`Refresh token expired`	`refresh_token` muddati tugagan
`invalid_grant`	`Invalid refresh token`	`refresh_token` noto‘g‘ri
`invalid_grant`	`Not a refresh token`	`refresh_token` o‘rniga boshqa token yuborilgan
`invalid_grant`	`Refresh token invalid or expired`	`refresh_token` bekor qilingan yoki muddati tugagan
`invalid_grant`	`User credential inactive`	Hisob faol emas

7. Quick Reference

API endpoints

Method	Endpoint	Purpose
`GET`	`/merchant/onboarding/`	Onboarding tokenni tekshirish
`POST`	`/merchant/onboarding/`	Onboarding jarayonini yakunlash
`POST`	`/merchant/oauth2/token/`	Access token olish yoki yangilash
`POST`	`/merchant/oauth2/revoke/`	Tokenni bekor qilish

Error codes

Error	Description
`invalid_request`	So‘rov formati noto‘g‘ri
`invalid_client`	`consumer_key` noto‘g‘ri (refresh so‘rovida)
`invalid_grant`	Credentials yoki `refresh_token` noto‘g‘ri, yoki hisob faol emas
`unsupported_grant_type`	`grant_type` qo‘llab-quvvatlanmaydi
`invalid_token`	Revoke qilinayotgan token topilmadi yoki allaqachon bekor qilingan
`validation_error`	Body maydonlari noto‘g‘ri
`invalid_or_expired`	Token noto‘g‘ri yoki muddati tugagan
`token_required`	`token` parametri yuborilmagan

API Integration Guide ​

1. Onboarding Process ​

What is onboarding? ​

Step 1: Verify onboarding token ​

Endpoint ​

Parameters ​

Example request ​

Success response 200 OK ​

Error response 400 Bad Request ​

Step 2: Set username and password ​

Password requirements ​

Valid password examples ​

Invalid password examples ​

Endpoint ​

Request headers ​

Request body ​

Example request ​

Success response 200 OK ​

Important notes ​

2. Obtaining Access Token ​

What is an access token? ​

Token request process ​

Endpoint ​

Authentication ​

Request headers ​

Request body ​

Step 1: Prepare Basic Authorization ​

Step 2: Send token request ​

Example request ​

Success response 200 OK ​

Response explanation ​

Error response 401 Unauthorized ​

3. Making API Requests with Access Token ​

Using access token ​

Header format ​

Example request ​

4. Refreshing Access Token ​

Endpoint ​

Request headers ​

Request body ​

Example request ​

Success response 200 OK ​

5. Revoking Tokens ​

Endpoint ​

Request headers ​

Request body ​

Example request ​

Success response 200 OK ​

Error response 400 Bad Request ​

6. Error Handling ​

400 Bad Request ​

401 Unauthorized ​

7. Quick Reference ​

API endpoints ​

Error codes ​

API Integration Guide

1. Onboarding Process

What is onboarding?

Step 1: Verify onboarding token

Endpoint

Parameters

Example request

Success response `200 OK`

Error response `400 Bad Request`

Step 2: Set username and password

Password requirements

Valid password examples

Invalid password examples

Endpoint

Request headers

Request body

Example request

Success response `200 OK`

Important notes

2. Obtaining Access Token

What is an access token?

Token request process

Endpoint

Authentication

Request headers

Request body

Step 1: Prepare Basic Authorization

Step 2: Send token request

Example request

Success response `200 OK`

Response explanation

Error response `401 Unauthorized`

3. Making API Requests with Access Token

Using access token

Header format

Example request

4. Refreshing Access Token

Endpoint

Request headers

Request body

Example request

Success response `200 OK`

5. Revoking Tokens

Endpoint

Request headers

Request body

Example request

Success response `200 OK`

Error response `400 Bad Request`

6. Error Handling

`400 Bad Request`

`401 Unauthorized`

7. Quick Reference

API endpoints

Error codes