Service Payment

Service Payment metodlari orqali Subscribe merchantlar turli xizmatlar, jumladan kommunal to‘lovlarni amalga oshirishi mumkin.

Methods

Service Payment quyidagi metodlarga ega:

1. servicePayment/list/
2. servicePayment/fields/
3. servicePayment/info/
4. servicePayment/create/
5. servicePayment/pay/
6. servicePayment/transaction/status/
7. merchant/servicePayment/transaction/all/

1. service Payment: list method

Ushbu metod barcha mavjud xizmatlarni qaytaradi.

Endpoint details

Method: GET
URL: BASE_URL/servicePayment/list/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Merchant uchun mavjud xizmatlar ro‘yxatini olish uchun so‘rovga available_for_me=true query parametrini qo‘shing.

Query params:

BASE_URL/servicePayment/list/?available_for_me=true

Response example

{
  "result": {
    "services": [
      {
        "service_id": "6ae5eaf5-9b70-4aa9-9260-2438e99affa0",
        "name": "Плата за электроэнергию",
        "category": {
          "id": 3,
          "name": "Коммунальные услуги"
        },
        "amount": {
          "min": 500,
          "max": 5000000
        },
        "is_active": true,
        "has_info_method": true,
        "can_cancel": false,
        "payment_available": true
      },
      {
        "service_id": "d2369eff-a542-4d59-90d1-f00c76d0b4e4",
        "name": "Горячая вода и отопление",
        "category": {
          "id": 3,
          "name": "Коммунальные услуги"
        },
        "amount": {
          "min": 500,
          "max": 3000000
        },
        "is_active": true,
        "has_info_method": true,
        "can_cancel": false,
        "payment_available": true,
        "logo": "https://cdn.paylov.uz/2024/12/05/mobi.png"
      }
    ]
  }
}

2. service Payment: fields method

Ushbu metod xizmat talab qiladigan field’larni qaytaradi.

Request example

Method: GET
URL: BASE_URL/servicePayment/fields/{service_id}/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Path param	Type	Description
service_id	string	servicePayment/list/ orqali qaytgan Service ID

Response example

{
  "result": {
    "data": [
      {
        "service_id": "6ae5eaf5-9b70-4aa9-9260-2438e99affa0",
        "name": "Плата за электроэнергию",
        "category": {
          "id": 33,
          "name": "Переводы"
        },
        "amount": {
          "min": 500,
          "max": 5000000
        },
        "has_info_method": true,
        "can_cancel": false,
        "payment_available": true,
        "is_active": true,
        "logo": "https://cdn.paylov.uz/2024/12/05/mobi.png",
        "fields": [
          {
            "field_id": "9",
            "name": "region",
            "title": "region",
            "type": "select",
            "content": "text",
            "validation": null,
            "length": null,
            "required": true,
            "dependency_of": null,
            "values": [
              {
                "id": 7,
                "value": "1",
                "title": "г. Ташкент",
                "filter": null
              },
              {
                "id": 8,
                "value": "2",
                "title": "Ташкентская область",
                "filter": null
              }
            ]
          },
          {
            "field_id": "10",
            "name": "soato",
            "title": "soato",
            "type": "select",
            "content": "text",
            "validation": null,
            "length": null,
            "required": true,
            "dependency_of": "region",
            "values": [
              {
                "id": 48,
                "value": "26280",
                "title": "26280 - Алмазарский ЭСП",
                "filter": "1"
              },
              {
                "id": 49,
                "value": "26264",
                "title": "26264 - Бектемирский ЭСП",
                "filter": "1"
              }
            ]
          },
          {
            "field_id": "11",
            "name": "customer_code",
            "title": "customer_code",
            "type": "text",
            "content": "number",
            "validation": null,
            "length": null,
            "required": true,
            "values": []
          }
        ],
        "response_fields": [
          {
            "field_id": "1311",
            "name": "fio",
            "title": "fio",
            "postfix": null
          },
          {
            "field_id": "1314",
            "name": "last_paid_date",
            "title": "last_paid_date",
            "postfix": null
          },
          {
            "field_id": "1315",
            "name": "last_paid",
            "title": "last_paid",
            "postfix": "UZS"
          },
          {
            "field_id": "1313",
            "name": "saldo",
            "title": "balance",
            "postfix": "UZS"
          },
          {
            "field_id": "1343",
            "name": "tariff_price",
            "title": "tariff_price",
            "postfix": null
          },
          {
            "field_id": "1344",
            "name": "kwn",
            "title": "kVts xisoblangani",
            "postfix": null
          }
        ]
      }
    ]
  }
}

Explanation
Qaytgan field’larni type qiymatiga qarab 2 guruhga ajratish mumkin: text va select.

• Agar type = select bo‘lsa, foydalanuvchi values ro‘yxatidan bittasini tanlashi kerak.
• Agar type = text bo‘lsa va values bo‘sh bo‘lsa, bu foydalanuvchi tomonidan kiritiladigan maydon ekanini anglatadi. Masalan, xizmatdagi abonent yoki hisob raqami.

info va create metodlarida account field’ini generatsiya qilish uchun kerakli field’larni shu yerdan olishingiz kerak.
So‘ng uni quyidagi ko‘rinishda shakllantirasiz:

account = {}

for field in result['data']['fields']:

    if field['type'] == 'select':
        account[field['name']] = field['values'][0]['value']
    else:
        account[field['name']] = ''

# bu account field’ni to‘g‘ri yaratish uchun oddiy misol

response_fields — info, create va pay metodlari javobida chiqishi mumkin bo‘lgan field’lar ro‘yxatini bildiradi.

3. service Payment: info method

Ushbu metod xizmat bo‘yicha mijoz ma’lumotlarini qaytaradi.

Ba’zi xizmatlarda foydalanuvchining shu xizmatdagi account ma’lumotlarini qaytaradigan metod mavjud. Masalan, kommunal xizmatlar.

Metod balans, manzil, ism va account bo‘yicha boshqa zarur ma’lumotlarni qaytaradi.

Endpoint details

Method: POST
URL: BASE_URL/servicePayment/info/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request example

Fields	sample_data	Type	Required	Description
service_id	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Yes	servicePayment/list/ orqali qaytgan Service ID
account	{"soato": "26290", "region": "1", "customer_code": "1000000"}	dict	Yes	Xizmat talab qiladigan field’lar

{
  "service_id": "9f877739-bc25-4f0f-a13f-ec485fd04250",
  "account": {
    "soato": "26290",
    "region": "1",
    "customer_code": "1000000"
  }
}

Response example

{
  "result": {
    "data": [
      {
        "name": "time",
        "value": "14.10.2024 14:53:48",
        "title": "time"
      },
      {
        "name": "fio",
        "value": "FIO - -",
        "title": "fio"
      },
      {
        "name": "address",
        "value": "Д******* Я******, 9***, 8",
        "title": "address"
      },
      {
        "name": "last_paid_date",
        "value": "2024-08-23",
        "title": "last_paid_date"
      },
      {
        "name": "pokcob",
        "value": "3431.28",
        "title": "bypass_indication"
      },
      {
        "name": "dateob",
        "value": "2024-10-08",
        "title": "bypass_date"
      },
      {
        "name": "last_paid",
        "value": "50000 UZS",
        "title": "last_paid"
      },
      {
        "name": "saldo",
        "value": "15105.15 UZS",
        "title": "balance"
      },
      {
        "name": "region",
        "value": "г. Ташкент",
        "title": "region"
      },
      {
        "name": "soato",
        "value": "26290 - Яшнабадский ЭСП",
        "title": "soato"
      },
      {
        "name": "customer_code",
        "value": "1000000",
        "title": "customer_code"
      }
    ]
  }
}

4. service Payment: create method

Ushbu metod xizmat bo‘yicha mijoz account ma’lumotlari bilan birga transactionId qaytaradi.

Endpoint details

Method: POST
URL: BASE_URL/servicePayment/create/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request fields

Field	sample_data	Type	Required	Description
service_id	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Yes	service_id
account	{"soato": "26290", "region": "1", "customer_code": "1000000"}	string	Yes	Xizmat talab qiladigan field’lar account ichida yuborilishi kerak
amount	500	int	Yes	Summa sum ko‘rinishida
userId	007	string	No	userId (merchant tomonidan berilgan ID)
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	Agar cardId yuborilsa, to‘lov OTP tasdiqlash bilan amalga oshirilishini bildiradi
phoneNumber	+998999999999	string	No	Ushbu maydon karta bilan bog‘langan telefon raqamiga mosligini tekshirish uchun ishlatiladi
sms		dict	No	OTP tafsilotlari uchun SMS obyekti

Request example without OTP (One Time Password)

{
  "amount": 500,
  "service_id": "9f877739-bc25-4f0f-a13f-ec485fd04250",
  "account": {
    "soato": "26290",
    "region": "1",
    "customer_code": "1000000"
  },
  "userId": "007"
}

Response example without OTP

{
  "result": {
    "transactionId": "b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26",
    "data": [
      {
        "name": "region",
        "value": "г. Ташкент",
        "title": "region"
      },
      {
        "name": "soato",
        "value": "26290 - Яшнабадский ЭСП",
        "title": "soato"
      },
      {
        "name": "customer_code",
        "value": "1000000",
        "title": "customer_code"
      },
      {
        "name": "time",
        "value": "14.10.2024 15:01:07",
        "title": "time"
      },
      {
        "name": "fio",
        "value": "FIO - -",
        "title": "fio"
      },
      {
        "name": "address",
        "value": "Д******* Я******, 9***, 8",
        "title": "address"
      },
      {
        "name": "last_paid_date",
        "value": "2024-08-23",
        "title": "last_paid_date"
      },
      {
        "name": "pokcob",
        "value": "3431.28",
        "title": "bypass_indication"
      },
      {
        "name": "dateob",
        "value": "2024-10-08",
        "title": "bypass_date"
      },
      {
        "name": "last_paid",
        "value": "50000 UZS",
        "title": "last_paid"
      },
      {
        "name": "saldo",
        "value": "15105.15 UZS",
        "title": "balance"
      }
    ]
  }
}

Request example With OTP (One Time Password)

{
  "amount": 500,
  "service_id": "9f877739-bc25-4f0f-a13f-ec485fd04250",
  "account": {
    "soato": "26290",
    "region": "1",
    "customer_code": "1000000"
  },
  "userId": "007",
  "cardId": "string"
}

Response example With OTP

{
  "result": {
    "transactionId": "b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26",
    "data": [
      {
        "name": "region",
        "value": "г. Ташкент",
        "title": "region"
      }
    ],
    "sms": {
      "otpSentPhone": "hidden_phone"
    }
  }
}

5. service payment: pay method

Ushbu metod tranzaksiya muvaffaqiyatli bajarilsa transactionId qaytaradi.

Endpoint details

Method: POST
URL: BASE_URL/servicePayment/pay/
Header:

Authorization: Bearer <ACCESS_TOKEN>

Request Fields

Field	sample_data	Type	Required	Description
transactionId	b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26	string	Yes	/servicePayment/create/ metodi qaytargan transactionId
cardId	9f877739-2149-4831-88a4-d1857309c77c	string	Yes	Paylov tizimida yaratilgan cardId
userId	007	string	No	userId (merchant tomonidan berilgan ID)
otp	123456	string	No	create metodida yuborilgan OTP’ni tekshirish uchun ishlatiladi. Agar create metodida cardId yuborilgan bo‘lsa, bu maydon majburiy bo‘ladi

Request example

{
  "transactionId": "b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26",
  "cardId": "9f877739-2149-4831-88a4-d1857309c77c",
  "userId": "007"
}

Response example

{
  "result": {
    "transactionId": "b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26",
    "cardId": "9f877739-2149-4831-88a4-d1857309c77c",
    "payedAt": "2024-10-14 15:07:23",
    "paymentRef": "023581615065",
    "eposMerchant": "90510020873",
    "eposTerminal": "92902804"
  }
}

6. service Payment: transaction status

Ushbu metod tranzaksiya holatini qaytaradi.

Endpoint details

Method: GET
URL: BASE_URL/servicePayment/transaction/status/?transactionId=b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26
Header:

Authorization: Bearer <ACCESS_TOKEN>

Query param	Type	Description
transactionId	string	tranzaksiya identifikatori

Response example

{
  "result": {
    "transactionId": "b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26",
    "status": "paid",
    "payedAt": "2024-10-14 15:07:23",
    "serviceId": "9f877739-bc25-4f0f-a13f-ec485fd04250",
    "cancelTime": null,
    "amount": 500
  }
}

Status Codes

• paid: muvaffaqiyatli yakunlangan tranzaksiya
• cancelled: bekor qilingan tranzaksiya
• created: yaratilgan

7. service Payment: transactions All

Ushbu metod merchant’ning barcha paid bo‘lgan Service Payment tranzaksiyalarini qaytaradi.
Natijalarni serviceId, userId, beginDate, endDate bo‘yicha filtrlash mumkin.

Endpoint details

Method: GET
URL: BASE_URL/servicePayment/transaction/all
Header:

Authorization: Bearer <ACCESS_TOKEN>

Response example

{
  "result": {
    "totalTransaction": 2,
    "transactions": [
      {
        "id": "2e701897-b04b-4fb0-99c5-520d78d557db",
        "userId": "646",
        "cardNumber": "986034******8885",
        "owner": "BOTIROV TEMURBEK",
        "amount": 500,
        "date": "2024-11-21 11:48:47",
        "serviceId": "3b03419c-2850-401f-b418-75d4c9b71b66"
      },
      {
        "id": "6aa8b698-cd79-4187-a822-21ac3f421839",
        "userId": "646",
        "cardNumber": "986034******8885",
        "owner": "BOTIROV TEMURBEK",
        "amount": 500,
        "date": "2024-09-30 11:26:32",
        "serviceId": "3b03419c-2850-401f-b418-75d4c9b71b66"
      }
    ],
    "error": null
  }
}

System ERROR cases

Agar xatolik yuz bersa, tizim 400 status code bilan error message qaytaradi.

Error Response

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Error codes here