Оплата услуги

через сервис Способы оплаты Подписавшись, мерчанты могут оплачивать различные услуги, включая счета за коммунальные услуги.

Методы

Оплата услуги имеет следующие способы:

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. Оплата услуги: метод списка

Этот метод возвращает все доступные сервисы

Подробности конечной точки

Метод: GET
URL: BASE_URL/servicePayment/list/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Чтобы получить список услуг, доступных для вашего мерчанта, добавьте в запрос параметр available_for_me=true.

Параметры запроса:

BASE_URL/servicePayment/list/?available_for_me=true

Пример ответа

{
  "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. Оплата услуги: метод полей

Возвращает поля, которые требуются службе

Запросить пример

Метод: GET
URL: BASE_URL/servicePayment/fields/{service_id}/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Параметр пути	Тип	Описание
service_id	string	Служба ID, возвращаемая servicePayment/list/

Пример ответа

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

Объяснение
Эти возвращаемые поля можно разделить на две группы по типам text и select.

• если type равен select, то пользователь должен выбрать одно из значений, возвращаемых в поле списка «значения».

• если type равен text и поле значений пусто, это означает, что это вводимые пользователем данные, например номер учетной записи пользователя в службе.

при создании поля учетной записи в методах info и create вам необходимо получить необходимые поля отсюда. и генерировать это так:

account = {}

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

	if field['type'] == 'select':

		account[field['name']] = field['values'][0]['value']

	else:

		account[field['name']] = ''
	

# this is just an example to create account field correctly

response_fields — список полей, которые могут появиться в ответах методов info, create и pay. Примечание:

3. Оплата услуги: информационный способ

Возвращает информацию о клиенте службы

В некоторых службах есть метод, который возвращает информацию об учетной записи пользователя в службе. например: коммунальные услуги.

Метод возвращает такую информацию, как баланс, адрес, имя и/или другую необходимую информацию об учетной записи.

Сведения о конечной точке

Метод: POST
URL: BASE_URL/servicePayment/info/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Запросить пример

Поля	sample_data	Тип	Требуется	Описание
service_id	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Да	Служба ID, возвращаемая servicePayment/list/
account	{"soato": "26290", "region": "1", "customer_code": "1000000"}	dict	Да	Поля, необходимые для сервиса

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

Пример ответа

{
  "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. Оплата услуги: создать метод

Возвращает transactionId с информацией об учетной записи клиента службы.

Подробности конечной точки

Метод: POST
URL: BASE_URL/servicePayment/create/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Поля запроса

Поле	sample_data	Тип	Требуется	Описание
service_id	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Да	service_id.
account	{"soato": "26290", "region": "1", "customer_code": "1000000"}	string	Да	Поля, необходимые для службы, должны быть включены в поле учетной записи.
amount	500	int	Да	сумма в сумме.
userId	007	string	Нет	userId (ID заявлено мерчантом)
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Нет	Если указан cardId, это означает, что платеж будет обработан с подтверждением OTP.
phoneNumber	+998999999999	string	Нет	Поле используется для проверки соответствия номеру телефона, привязанному к карте.
sms		dict	Нет	Объект SMS для подробностей OTP.

Пример запроса без OTP (одноразового пароля)

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

Пример ответа без 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"
      }
    ]
  }
}

Пример запроса с OTP (одноразовым паролем)

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

Пример ответа с OTP

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

5. оплата услуги: способ оплаты

Возвращает идентификатор транзакции, если транзакция прошла успешно

Подробности конечной точки

Метод: POST
URL: BASE_URL/servicePayment/pay/
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Поля запроса

Поле	sample_data	Тип	Требуется	Описание
transactionId	b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26	string	Да	transactionId, возвращаемый методом /servicePayment/create/
cardId	9f877739-2149-4831-88a4-d1857309c77c	string	Да	cardId, созданный в системе Paylov
userId	007	string	Нет	userId (ID заявлено мерчантом)
отп	123456	string	Нет	используется для проверки OTP (одноразового пароля), отправленного во время метода create . Обязательно, если cardId включен в метод create

Запросить пример

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

Пример ответа

{
  "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. Оплата услуги: статус транзакции

Возвращает статус транзакции

Подробности конечной точки

Метод: GET
URL: BASE_URL/servicePayment/transaction/status/?transactionId=b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Параметры запроса	Тип	Описание
transactionId	string	идентификатор транзакции

Пример ответа

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

Коды состояния

• paid: транзакция успешно завершена
• cancelled: отмененная транзакция
• created: создано

7. Оплата услуги: транзакции Все

Возвращает все «платные» сервисные платежные операции мерчанта.
Можно фильтровать по serviceId, userId, beginDate, endDate.

Подробности конечной точки

Метод: GET
URL: BASE_URL/servicePayment/transaction/all
Заголовок:

Authorization: Bearer <ACCESS_TOKEN>

Пример ответа

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

Системные случаи ERROR

В случае возникновения ошибки система возвращает сообщение об ошибке с кодом состояния 400.

Ошибка ответа

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

Коды ошибок здесь