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

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

Parameters

• token required — onboarding token

Example request

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

Success response 200 OK

{
  "status": "ok"
}

Error response 400 Bad Request

{
  "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

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

Request headers

Content-Type: application/json

Request body

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

Example request

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

{
  "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.

---

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

POST {BASE_URL}/merchant/oauth2/token/

Authentication

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

Request headers

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

Request body

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

Step 1: Prepare Basic Authorization

consumer_key va consumer_secret quyidagi formatda birlashtiriladi:

consumer_key:consumer_secret

So‘ng ushbu qiymat base64 formatga encode qilinadi.

Step 2: Send token request

Example request

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

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

Response explanation

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

Error response 401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials or this account not activated"
}

---

3. Making API Requests with Access Token

Using access token

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

Header format

Authorization: Bearer YOUR_ACCESS_TOKEN

Example request

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

POST {BASE_URL}/merchant/oauth2/token/

Request headers

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

Request body

{
  "grant_type": "refresh_token",
  "refresh_token": "refresh_abc123def456ghi789jkl012mno345pqr"
}

Example request

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=refresh_abc123def456ghi789jkl012mno345pqr"

Success response

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

---

5. Revoking Tokens

Token’dan keyin foydalanilmasligi uchun uni bekor qilishingiz mumkin.

Endpoint

POST {BASE_URL}/merchant/oauth2/revoke/

Request headers

Content-Type: application/json

Request body

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

Example request

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

Success response 200 OK

{
  "status": "success"
}

---

6. Error Handling

400 Bad Request

{
  "error": "invalid_request",
  "error_description": "Basic authorization header required"
}

Sababi:

Authorization header yuborilmagan yoki noto‘g‘ri formatda yuborilgan.

401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials"
}

Sababi:

username, password, consumer_key yoki consumer_secret noto‘g‘ri.

400 Invalid or Expired Token

{
  "error": "invalid_or_expired"
}

Sababi:

Token eskirgan yoki noto‘g‘ri. Yangi token oling.

---

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
invalid_grant	Credentials noto‘g‘ri
unsupported_grant_type	grant_type qo‘llab-quvvatlanmaydi
invalid_or_expired	Token noto‘g‘ri yoki muddati tugagan
token_required	token parametri yuborilmagan