Service Payment

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

Swagger docs

Methods

Service payment has following methods:

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

This method returns all available services

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

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

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

Returns fields that service requires

Swagger docs

Request example

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

api-key: kfggfgf.given_api_key_by_paylov

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

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
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:

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.

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

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

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

Returns transactionId with a client account info of a service

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

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)

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

Returns transaction id if transaction succeed

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

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

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

Returns transaction status

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

Query param	Type	Description
transactionId	string	transaction id

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: 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

Swagger docs

Endpoint details

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

api-key: kfggfgf.given_api_key_by_paylov

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

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

Error Response

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

Error codes here

---

FAQ

How to Auth When sending any request include API key in the headers

api-key: JYVhflfd.your_api_key

💡 Note: API key is given by the system adminstration.

How to create the account field in info and create methods

Account field includes necessary fields and values that is required by a service merchant.

Steps to create account field:

1. Get available fields from servicePayment/fields/ method.

2. if field type is select type, then you have to select one of the options from values field.

• Example field:

  {
    "field_id": "9",
    "name": "region",
    "title": "region",
    "type": "select",
    "content": "text",
    "required": true,
    "values": [
      {
        "id": 7,
        "value": "1",
        "title": "г. Ташкент",
        "filter": null
      }
    ]
  }

name fields value will be key and values fields value will be value in account like this

"account": {"region": "1"}

If field type is text type and values field is empty it means it is user specific field and user have to fill it.

Example field:

{
  "customer_code": "1000000"
}

All the service fields should be send in account field:

{
  "account": {
    "region": "1",
    "soato": "26290", 
    "customer_code": "1000000"
    }
}