Service Payment

via service Payment methods Subscribe merchants can pay to various services including utility bills

Methods

Service payment has following methods:

servicePayment/list/
servicePayment/fields/
servicePayment/info/
servicePayment/create/
servicePayment/pay/
servicePayment/transaction/status/
merchant/servicePayment/transaction/all/

1. service Payment: list method

This method returns all available services

Endpoint details

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

http

Authorization: Bearer <ACCESS_TOKEN>

To retrieve the list of services available for your merchant, add the query parameter available_for_me=true to your request

Query params:

plaintext

BASE_URL/servicePayment/list/?available_for_me=true

Response example

json

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

Returns fields that service requires

Request example

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

http

Authorization: Bearer <ACCESS_TOKEN>

Path param	Type	Description
service_id	string	Service ID returned by the servicePayment/list/

Response example

json

{
  "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
These returned fields can be separated into 2 groups by their type text and select types.

if type is select then user should select one of the values that is returned in the “values” list field.
if type is text and values field is empty it means it is user specific input like account number of a user in a service.

when generating account field in info and create methods you need to get the required fields from here. and generate it like this:

python

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 - Lists the fields that may appear in the responses of the info, create, and pay methods. Note:

3. service Payment: info method

Returns client info of a service

Some services has a method that returns account info of a user in a service. ex: utility services.

The method returns information like balance, address, name, and/or other necessary info of an account.

Endpoint details

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

http

Authorization: Bearer <ACCESS_TOKEN>

Request example

Fields	sample_data	Type	Required	Description
service_id	9f877739-bc25-4f0f-a13f-ec485fd04250	string	Yes	Service ID returned by the servicePayment/list/
account	`{"soato": "26290", "region": "1", "customer_code": "1000000"}`	dict	Yes	Fields required by the service

json

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

Response example

json

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

Returns transactionId with a client account info of a service

Endpoint details

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

http

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	Fields required by the service should be included in the account field.
amount	500	int	Yes	amount in sum.
userId	007	string	No	userId (ID declared by the merchant)
cardId	9f877739-bc25-4f0f-a13f-ec485fd04250	string	No	If `cardId` is provided, it indicates that the payment will be processed with OTP confirmation.
phoneNumber	+998999999999	string	No	field is used to verify whether it matches the phone number tied to the card.
sms		dict	No	SMS object for OTP details.

Request example without OTP (One Time Password)

json

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

Response example without OTP

json

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

json

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

json

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

5. service payment: pay method

Returns transaction id if transaction succeed

Endpoint details

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

http

Authorization: Bearer <ACCESS_TOKEN>

Request Fields

Field	sample_data	Type	Required	Description
transactionId	b6135bb4-ef3c-4ab1-a5aa-db174a9bdc26	string	Yes	transactionId that is returned by the `/servicePayment/create/` method
cardId	9f877739-2149-4831-88a4-d1857309c77c	string	Yes	cardId that is created in Paylov system
userId	007	string	No	userId (ID declared by the merchant)
otp	123456	string	No	field is used to verify the OTP (One-Time Password) sent during the `create` method.Required when cardId included in the `create` method

Request example

json

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

Response example

json

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

Returns transaction status

Endpoint details

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

http

Authorization: Bearer <ACCESS_TOKEN>

Query param	Type	Description
transactionId	string	transaction id

Response example

json

{
  "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: successfully completed transaction
cancelled: cancelled transaction
created: created

7. service Payment: transactions All

Returns all “paid” service Payment Transactions of a merchant.
Can be filtered by serviceId, userId, beginDate, endDate

Endpoint details

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

http

Authorization: Bearer <ACCESS_TOKEN>

Response example

json

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

If an error occurs, system returns error message with status code 400

Error Response

json

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

Error codes here

User Card

OFD (Fiscalization)

Service Payment

Methods

1. service Payment: list method

Endpoint details

2. service Payment: fields method

3. service Payment: info method

4. service Payment: create method

Endpoint details

5. service payment: pay method

Endpoint details

6. service Payment: transaction status

Endpoint details

Status Codes

7. service Payment: transactions All

Endpoint details

System ERROR cases

Error Response

Service Payment ​

Methods ​

1. service Payment: list method ​

Endpoint details ​

2. service Payment: fields method ​

3. service Payment: info method ​

4. service Payment: create method ​

Endpoint details ​

5. service payment: pay method ​

Endpoint details ​

6. service Payment: transaction status ​

Endpoint details ​

Status Codes ​

7. service Payment: transactions All ​

Endpoint details ​

System ERROR cases ​

Error Response ​

Service Payment

Methods

1. service Payment: list method

Endpoint details

2. service Payment: fields method

3. service Payment: info method

4. service Payment: create method

Endpoint details

5. service payment: pay method

Endpoint details

6. service Payment: transaction status

Endpoint details

Status Codes

7. service Payment: transactions All

Endpoint details

System ERROR cases

Error Response